amarquee.library/QNewSocketServerSession           amarquee.library/QNewSocketServerSession

   NAME
    QNewSocketServerSession - Start a TCP thread waiting for connections 
                      on a port.

   SYNOPSIS
    #include 

    struct QSession * QNewSocketServerSession(LONG *port, struct TagItem *taglist)
    struct QSession * QNewSocketServerSessionTags(LONG *port, ULONG Tag1, ...)

   FUNCTION
    This function allows your AMarquee client to accept direct TCP 
    socket connections from other clients.  It will start a new
    execution thread, which will listen to the port you specify
    until a remote host attempts to connect to it.  When
    a host does connect to its port, 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 domain name
    of the connecting remote host. (e.g. "amicomsys.hostile.cx").
    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 QSendRawOp,
    and receive QMessages in the normal way.  Any other operations
    will cause the receiving client to get a QERROR_UNIMPLEMENTED error message. 

    The difference to QNewHostSession is that any standard tcp communication library
    may connect to your session. The other host doesn't need to use amarquee.library's
    QNewSession() function. If the other host will use amarquee.library the functions
    to connect to your session with are QNewSocketSession or QNewSocketSessionAsync.
    It is a little bit more complicated to use this one instead of QNewHostSession(), so
    you should be experienced with QNewHostSession() before you try to use this function.

   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 QNewSocketServerSession again.
    Note that you can reuse the port number.

    Don't forget to call QFreeSession'd on all allocated 
    QSessions before you close amarquee.library!
    
    Note that you must use the QSendRawOp() function to send data, QSetOp or
    QStreamOp won't work.

    Data sent from a remote host to you will return at your application's
    doorstep as a QMessage with a qm_ID of 0 and the
    qm_Path set to the remote host's domainname and the local port. The
    data is in the qm_Data. The data sent to you may be divided into several
    QMessages. AMarquee.library v.50 tries to keep the number of packets as
    small as possible. Use the QSetMaxRawBufSize() function or the tag named
    QRAWSESSION_MAXBUFFERSIZE to set the buffer size, i.e the maximum size of
    the QMessages.

    This function requires v49+ of amarquee.library.
    
   INPUTS
    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 QNewSocketSession
                or when they are using normal socket API's like bdssocket.library.
                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.
    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 QNewSocketSession().

   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 = QNewSocketServerSession(&port, NULL))
       printf("Now listening for connections on port %li.\n",port);
    else
       printf("Could not open a new host session.\n");

   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 = QNewSocketServerSession(0, NULL)
    if (session > 0) then say "Connection was successful!"
                     else say "Connection failed!"
       

   SEE ALSO
    QNewSocketSessionAsync, QNewSocketSession, QSendRawOp, QFreeSession