Class HttpEndpoint()

Class function of the HttpEndpoint class.

An object of the class HttpEndpoint serves as a connection point for incoming HTTP or WebSocket connections. The connection point is active after calling the method :start(). :start() automatically creates a new thread for listening on the port associated with the HttpEndPoint. The port number must be passed as a parameter to the method :new().

For HTTP requests with a URL referring to a local file, the HttpEndpoint loads the file from the hard drive and returns it to the connected web client. The following table lists the extensions and the corresponding MIME types of the resources which are supported by default:

Extension	MIME type
.html	text/html
.htm	text/html
.gif	image/gif
.png	image/png
.jpg	image/jpeg jpg jpe
.js	application/x-javascript
.css	text/css
.woff	font/woff
.eot	application/vnd.ms-fontobject
.otf	application/octet-stream
.ttf	application/octet-stream
.svg	image/svg+xml
.json	application/json

A web request to a resource without an extension must be handled in application code. For this, a user-defined class must be written containing the logic for handling the request. The class must have the same name as the resource which is requested, and it must be derived from a base class which corresponds to the connection type.

If the client tries to establish a websocket connection, an object of a user-defined class is created. This class must be derived from WebSocketHandler. The following URL instantiates an object from the class MyWebSocketHandler:

ws://<servername>:<port>/MyWebSocketHandler

In case no websocket connection is to be established, an object is instantiated from a class that must be derived from the class WebHandler. The following URL instantiates an object from the class MyWebHandler, and calls the method :echo(). The parameters specified in the URL are forwarded to the handler method:

http://<servername>:<port>/MyWebHandler/echo?paramname1=value1

The following code fragment demonstrates the implementation of the handler that corresponds to the URL above:

CLASS MyWebHandler FROM WebHandler 
  EXPORTED: 
    METHOD echo 
ENDCLASS 

<...> 

METHOD MyWebHandler:echo( cParamName1 ) 
   LOCAL cHtml 
   cHtml := "" 
   cHtml += "<html><title>MyWebHandler:echo() was called</title><body>" 
   cHtml += "Parameter cParamName1 is " + cParamName1 
   cHtml += "</body></html>" 
RETURN cHtml

In addition to plain text connections, HTTP endpoints also support servicing requests via the Secure Socket Layer (SSL) protocol. For this, an SSL certificate must first be installed on the computer. Once the endpoint is bound to this certificate, HTTP and web socket connections to this endpoint can be established via SSL for increased security.

The following code fragment demonstrates the general procedure:

#define PORT 443 

// Create an endpoint for handling incoming 
// connections on the default port for HTTPS 
// Note: Port and address must be adjusted 
// for your environment! 
oHttpEndpoint := HttpEndpoint():new( PORT, "localhost" ) 

// Set the SSL certificate for the local computer. 
// The certificate will be used for subsequent 
// SSL connections. 
// Note: The certificate must be adjusted 
// for your environment! 
oHttpEndpoint:setCertificate( "machine\my\mycomputer" ) 

// Start the endpoint 
oHttpEndpoint:start() 

<...>

Creates an instance of the class HttpEndpoint.

Contains the port number.

Contains the IP number.

Contains the error code of the last socket operation.

Determines if the HttpEndpoint is currently listening.

Binds a server certificate from the Windows Certificate Store for SSL connections.

Binds a server certificate from a file for SSL connections.

Starts the listener thread.

Terminates the listener thread.

Implementing a web endpoint

// This example creates an html file in the current directory. 
// The HttpEndpoint loads the file and returns it to the 
// connected client on request. If an SSL certificate is 
// installed on the computer, the endpoint is bound to this 
// certificate in order to allow clients to connect via SSL 
// for increased security. 
#include "inkey.ch" 
#include "web.ch" 

#define PORT 81 
PROCEDURE Main() 
  LOCAL cPort 
  LOCAL oHttpEndpoint 
  LOCAL nKey 
  LOCAL cHtml 
  LOCAL lStarted 

  // 
  // Creates a sample html file on the local drive. 
  // 
  IF .NOT. File( "default.html" ) 
     cHtml := "" 
     cHtml += "<h1>Hello World!</h1>" 
     cHtml += "<h2>Greetings from: "+AppName()+"</h2>" 
     MemoWrit( "default.html", cHtml ) 
  ENDIF 

  cPort := Var2Char(PORT) 
  ? "HttpEndpoint sample." 
  ? 
  ? "With a web browser navigate to:" 
  ? 
  ? "     http://localhost:"+cPort+"/default.html" 
  ? 
  ? "Press ESC to quit" 

  // 
  // Create an endpoint for handling incoming 
  // connections on the specified port 
  // 
  // Note: Requests to .html files are handled 
  //       automatically by the Http endpoint! 
  //       No code must be written for returning 
  //       the sample .html file. 
  // 
  oHttpEndpoint := HttpEndpoint():new( PORT, "localhost" ) 
  lStarted := oHttpEndpoint:start() 
  IF .NOT. lStarted 
    ? "Startup error. Check if port "+cPort+" is already in use." 
    WAIT 
    RETURN 
  ENDIF 

  // Continue after the ESC key was pressed 
  nKey := 0 
  DO WHILE nKey <> K_ESC 
     nKey := Inkey(1) 
  ENDDO 

  // 
  // Stop the endpoint before the application 
  // terminates 
  // 
  oHttpEndpoint:stop() 

RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Class HttpEndpoint() Professional