amarquee.library/QNewHostSession           amarquee.library/QNewHostSession

   NAME
    QNewHostSession - Start a TCP thread waiting for connections 
                      on a port. (V50)

   SYNOPSIS
    #include 

    struct QSession * QNewHostSession(char * hostnames, LONG * port, char * prognames, struct TagItem *taglist)
    struct QSession * QNewHostSessionTags(char * hostnames, LONG * port, char * prognames, ULONG tag1, ...)

   FUNCTION
    This function allows your AMarquee client to accept direct TCP 
    connections from other AMarquee clients.  It will start a new
    execution thread, which will listen to the port you specify
    until an AMarquee thread attempts to connect to it.  When
    a thread does connect to its port, it will verify that the
    connecting thread matches the criteria specified via the
    "hostnames" and "prognames" arguments, and if the connecting
    program passes, it will send you a QMessage to tell you that
    a connection has been received.  This QMessage will have a
    qm_ID of zero, and the qm_Path field will contain the path
    of the connecting client's root node. (e.g. "/computername/progname").
    Also, the qm_Data field will contain the program's IP address,
    as a string.  After this QMessage has been received, you may 
    send data messages to the connected client via QSetOp, QDeleteOp, 
    QPingOp, QStreamOp, or QInfoOp, and receive QMessages in 
    the normal way.  Any other operations will cause the receiving 
    client to get a QERROR_UNIMPLEMENTED error message. 

   NOTE
    This function will return as soon as the listening port has
    been set up.  Until someone connects to its port, however,
    the QSession returned is "dormant", and any transactions 
    sent to it will result in QERROR_NO_CONNECTION QMessages. 
    (Note that you can still QFreeSession the dormant QSession,
    if you get tired of waiting for a connection)
    
    Once a connected QSession has been disconnected, it can no longer
    be used for anything and should be freed.  If you wish to receive 
    another connection, you will need to call QNewHostSession again.

    Don't forget to call QFreeSession'd on all allocated 
    QSessions before you close amarquee.library!
    
    This function requires v38+ of amarquee.library.
    
   INPUTS
    hostnames - A regular expression determining which hosts are
                allowed to connect to this QSession.  For example,
                "#?" would allow any host to connect, or "#?.edu"
                would allow only hosts from schools to connect.
    port      - Pointer to a LONG that contains the port to listen on.  
                Clients who wish to connect to your host session must 
                specify this port number when they call QNewSession.
                If the LONG contains the value 0L, then the TCP stack
                will choose an available port for you and write it
                into your variable before this function returns.
    prognames - A regular expression determining which program names
                are allowed to connect to this QSession.  The connecting
                program's name is specified by the connecting program
                when it calls QNewSession.  
    taglist   - A pointer to a tag list. For usable tags see .
                You can set this to NULL if you don't want to use any tags.

   TAGS
   Same tags as QNewSession().

   RESULTS
    On success, returns a pointer to a QSession struct that may be
    used with the other functions in this API.  The QSession struct
    also contains a pointer to an exec.library MsgPort that your program
    should Wait() on and GetMsg() from to receive QMessages from the
    TCP thread.  Returns NULL if a listening port could not be established
    (likely because another program was using the port you wanted!).

   EXAMPLE
    struct QSession * s;
    LONG port = 0;  /* Let the system choose a port for me */
    
    if (s = QNewHostSession("#?", &port, "#?",NULL))
       printf("Now listening for connections on port %li.\n",port);
    else
       printf("Could not open a new host session.\n");

   NOTE
   This function was modified in amarquee.library v.50. The v.49 version had the
   same function but without the last argument, struct TagItem *taglist. I.e tags
   could not be used. Use the AMarquee49 pragmas and protos if your program have
   to work with amarquee.library v.49, though it's not recommended.

   AREXX NOTES
    For ARexx, the return value of this method is a string representing
    two numbers:  A pointer to the session struct, and the port number
    that is being used.  The return value of a successful call might look
    like this:
    
      "1254115 1024"
      
    If the first number is zero, then the call failed.  
    Otherwise, use the return value as a handle to pass to other 
    amarquee.library functions.  You may read the port (e.g. second)
    number and use it as you see fit (e.g. send it to another client 
    so they know what port they can connect to you at).  You do not 
    need to remove the port number from the string before passing the
    string as a handle to subsequent amarquee.library calls--they
    will ignore the extra number.
    
    Note that instead of calling Wait() and GetMsg(), you will want
    to use amarquee.library's GetNextQMessage function to receive
    incoming QMessages.

   AREXX EXAMPLE
    session = QNewHostSession('example.server.com', 0, 'ExampleScript')
    if (session > 0) then say "Connection was successful!"
                     else say "Connection failed!"
       

   SEE ALSO
    QNewSession, QNewSessionAsync, QNewServerSession, QFreeSession