HTTPSERV

An HTTP/1.1 server to serve files rooted in given directory.

<PORT> The port that the web server is to run on. [default=8080]
       Use 0 for any free port (Since NeXtMidas 2.7.0, once server is running,
       port is updated and printed to reflect the actual listen port.)

<DIR>  The directory containing the files to be served.  If the parameter
       begins with a slash (/) then it is assumed to be an absolute pathname,
       otherwise it is assumed to be relative to NMROOT.  [default=htmlhelp]

<NAME> The alias by which the directory will be accessed. [default=dat]


The NAME parameter is the alias used by the web server for the directory.
HTTP requests that begin with the specified name will be mapped to a file
that is contained in the given directory.  Files in subdirectories will be
served if the request URI begins with the NAME.

    +---------------------------------------------------------------+
    |                           WARNING                             |
    | Unlike most web servers, the names of the file accessible via |
    | HTTPSERV should be assumed to be case sensitive.              |
    +---------------------------------------------------------------+


Messages:
  HTTPGET    - Send from primitive to /MSGID= with the following:
                  NAME=HTTPGET
                  INFO=0
                  DATA={SOCKET=<outputSock>,PARAMAMETERS=<params>}
               <outputSock> is an instance of nxm.sys.net.HPage
               <params>     is a Table of input parameters (same as calling
                            <outputSock>.getParameters())

               Note that the macro ***MUST*** invoke both openSocket() and
               closeSocket() on the <outputSock>. Failure to do this will cause
               the request handler to hang!!!

  HTTPPOST   - Same as HTTPGET, except for an HTTP POST request. See the API
               for HPage.getPostData() for details on accessing POST data.
               (Note: Support for HTTP POST was added in NeXtMidas 2.7.0)

Examples:
  1. Make the files in "${NMROOT}/nxm/sys/dat" available on the net via
     "http://hostname:8080/dat/":

       nM> httpserv 8080 DIR="nxm/sys/dat" NAME="dat"

     This will instantiate a server on port 8080 that will serve files rooted
     in the ${NMROOT}/nxm/sys/dat directory and will use 'dat' as the alias for
     this directory.

     While this is running, you can do the following from another system:
       nM> status http://hostname:8080/dat/apenny.prm

     or even
       nM> noop http://hostname:8080/dat/apenny.prm localpenny

     This connection is not limited to NeXtMidas sessions, any program with
     HTTP access can access the files, for example a web browser can load the
     "Sunset.jpg" file using "http://hostname:8080/dat/Sunset.jpg".

     Note that by default ALL files under $NMROOT are accessible via
     "http://hostname:8080/nmroot/" also note that any web browser pointed
     to "http://hostname:8080/" will automatically be able to access the
     NeXtMidas documentation (if built) and status information about any of
     the primitives running over the network.

  2. Run SD360;SYS with HTTPSERV:
       nM> sd360/server=9000/http

     Now it is possible to point a web browser to "http://hostname:9000/" and
     get status information about the running RMIF connection.

     See the SD360 explain file for details.

  3. Run HTTP server on any available port and display host and listen port

       nM> httpserv port=0 /bg
       INFO: Starting HTTP Web Server at URL=http://<host>:<port>/ [HTTPSERV]

       nM> say "using host=^{reg.httpserv.host} port=^{reg.httpserv.port}"
       using host=10.10.1.59 port=38375

  4. Use the /MNAME= and /MSGID= switches to allow the macro to respond to a
     HTTP request:
        startmacro
          pipe on
            httpserv/msgid=main/mname="mymacro" port=9999
          pipe off
        endmacro

        procedure processMessage m:msg
          say "Got message name=^msg.name info=^msg.info data=^msg.data"

          if msg.name eqs "HTTPGET" then
            set socket msg.data.socket
            set params msg.data.parameters

            ! say "Got HTTPGET request, URI= ^{socket.uri}"
            invoke,,socket.openSocket()
            invoke,,socket.writeln("Got request with ^{params}")
            invoke,,socket.closeSocket()
          elseif msg.name eqs "HTTPPOST" then
            ...
          endif
        return

     A client can then use "http://localhost:9999/mymacro?a=1&b=2&c=3" to access
     this macro. NOTE: The macro MUST invoke both openSocket() and closeSocket()
     on the <socket>. Failure to do this will cause the primitive to hang!!!


Switches:
  /AUXLIST=<l>  - List of AUXs to make available under
                  "http://host:port/Files/<AUX>/<filename>". By default none
                  are listed (same as /AUXLIST=null). /AUXLIST="*" serves up
                  everything in AUX.READ (use of /AUXLIST="*" is very common).
  /HOMEPAGE=<p> - Homepage location for HTTP web server (<p> = path).
  /MNAME=<n>    - Turns on macro handling of requests where <n> is the name of
                  the macro as given in the HTTP request. If /MNAME="/mymacro"
                  (or /MNAME="mymacro", leading slash is implied) then the
                  client uses "http://<server>:<port>/mymacro" to access it).
                  When this is enabled HTTPGET and/or HTTPPOST messages will
                  be sent to /MSGID=. If /MNAME="/" (e.g. root alias) then all
                  requests will be forwarded specified message handler otherwise
                  the default HServer index will serve up the / requests.
  /MSGID=<n>    - Registry name of command to handle messages (usually MAIN),
                  only used with /MNAME= switch.
  /PRANGE=n     - Range of port numbers above <PORT> to use if already
                  allocated. [DEF=1] Since 2.9.3.

See Also: RMIF, nxm.sys.net.HServer, nxm.sys.net.HPage