amarquee.library/QNewSocketSessionAsync           amarquee.library/QNewSocketSessionAsync

   NAME
    QNewSocketSessionAsync - Starts a new raw socket TCP connection thread, returns immediately.

   SYNOPSIS
    #include 

    struct QSession * QNewSocketSessionAsync(char * hostname, LONG port, struct TagItem *taglist)
    struct QSession * QNewSocketSessionAsyncTags(char * hostname, LONG port, ULONG Tag1, ...)

   FUNCTION
    This function works the same as QNewSocketSession, except that instead
    of waiting for the TCP connection to be fully established, it returns
    immediately.

    When (and if) the TCP connection does connect to the target
    computer, your program will be notified via a QMessage.  This
    QMessage will have a qm_ID of zero, contain 
    the remote host's domain name as the qm_Path field 
    (e.g. "amicomsys.hostile.cx"), and have "" as the qm_Data 
    field.

    If the TCP connection fails, you will be sent a QMessage
    with the qm_Status field set to QERROR_NO_CONNECTION.

   NOTE
    If a non-NULL QSession is returned, it must be QFreeSession'd before
    you close the amarquee.library.
    
    You may call QFreeSession() at any time, whether the returned QSession
    has connected or not.

    Any transactions (Q*Op(), QGo(), etc) that you send to a QSession 
    that is still connecting will not be processed until after the 
    TCP connection has been established.
    
    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
    hostname - The IP name of the computer to connect to.  (e.g.
               foo.bar.com)
    port     - The port to connect on.  E.g. Port 80 is the standard web-
               server port.
    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 should be
    passed to 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 connection thread could not be established.

   EXAMPLE
    struct QSession * s;
    
    /* demonstrates how you can Wait() on both the pending connection,
       and other events (here, a CTRL-C) at the same time */
    if (s = QNewSocketSessionAsync("example.server.com", 80, NULL))
    {
       printf("Connecting to example.server.com:80 ....\n");
 
       while(1)
       {
         struct QMessage * qMsg;
         ULONG signals = (1L << s->qMsgPort->mp_SigBit) | (SIGBREAKF_CTRL_C);

         /* Wait for next message from the server */
         signals = Wait(signals);
    
         if (signals & (1L << s->qMsgPort->mp_SigBit))
         {
           while(qMsg = (struct QMessage *) GetMsg(s->qMsgPort))
           {
             if (qMsg->qm_Status == QERROR_NO_ERROR) printf("Connection established!\n");
             if (qMsg->qm_Status == QERROR_NO_CONNECTION) printf("Connection failed.\n");
           }
         }
         if (signals & SIGBREAKF_CTRL_C)
         {
           printf("User aborted.\n");
           break;
         }
       }
       QFreeSession(s);
    }
    else
       printf("Connection thread failed.\n");

   AREXX NOTES
    For ARexx, the return value of this method is a string representation 
    of the pointer to the session struct.  If the returned value is equal 
    to zero, then the call failed.  Otherwise, use the return value as a 
    handle to pass to other amarquee.library functions.
    
    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 = QNewSocketSessionAsync('example.server.com', 80,0)
    if (session > 0) then say "Call was successful."
                     else say "Call failed!"
    /* Now wait for QMessages with GetNextQMessage... */
    
   SEE ALSO
    QNewSocketSession, QNewSocketServerSession, QSendRawOp, QFreeSession