amarquee.library/QNewSocketSession           amarquee.library/QNewSocketSession

   NAME
    QNewSocketSession - Creates a new raw socket connection to a remote host.

   SYNOPSIS
    #include 

    struct QSession * QNewSocketSession(char * hostname, LONG port, struct TagItem *taglist)
    struct QSession * QNewSocketSessionTags(char * hostname, LONG port, ULONG Tag1, ...)

   FUNCTION
    Creates a new TCP-handling thread and attempts to connect it
    to the specified remote host.

    The difference to QNewSession is that the remote host doesn't need to use AMarquee.
    This lets you connect to web-servers, ftp-servers and any other standard TCP-servers
    in the same simple way as with QNewSession. It's a little more complicated than QNewSession
    so you should be experienced with QNewSession before you try to use this function.

   NOTE
    This function is synchronous--it will not return until either
    a TCP connection has been made to the remote host, or the attempt 
    has failed.  If the connection fails, this function will return
    NULL with no side effects.

    If a non-NULL QSession is returned, it must be QFreeSession'd 
    before you close the 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
    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 to connect to a web-server
               located at the standard 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
   In addition to the tags of QNewSession(), the following is available:
   QRAWSESSION_MAXBUFFERSIZE - Can optionally be used to specify the maximum size of the QMessages
   which is returned. This is the same as the QSetMaxRawBufSize() function.
   Note if you are using a QProtocolStopMarkerHook, this can automatically be increased by
   amarquee.library if it detect it's to small for a user defined object. (V50)
   
   QRAWSESSION_PROTOCOLSTOPHOOK - Can optionally be used to specify a pointer to a struct Hook.
   The hook function receive a pointer to the Hook in A0, the QSession pointer in A2 and a pointer
   to a QProtocolStopMarkerMessage in A1. Return the length of the buffer to send to the client.
   Return a length of 0 if not enough data is present. With this function it's easy to make sure
   that no structs or other datatypes get stripped. It can be used in two ways as follow:

   With 'object' below I mean a transfer object, e. g. a structure:
                    struct {
                        int dataid;
                        char str1[40];
                        char str2[70];
                    };

   There are two alternatives:
   Common for both is that you must return zero and set ID to zero if the size of the
   given data buffer is not large enough to contain an entire object, e. g. if it is only
   big enough to contain half the 'str1' array above.

   Alternative 1:
   Return the size of the data that contain one object.
   Set ID to a number bigger than zero and lower than 2147483648.
   The QMessage which is sent to the application will have the qm_ID set to the ID
   you give here. See example named GetURL_Hook1.c.

   Alternative 2:
   You don't care to indentify the objects here, the application will take care of that later.
   Return the total size of the data which contain one or more full objects.
   Set ID to zero. It is set to zero by default. See example named GetURL_Hook2.c. (V51)

   QRAWSESSION_RECEIVE_EXCEEDING_DATA - Can optionally be used to specify if the application
   shall receive exceeding data, i.e. data which is left when the connection is closed by
   the remote host, while the QProtocolStopMarkerHook above says it's not enough for a full
   object. Default is TRUE. (V51)

   QRAWSESSION_PROTOCOLSTOPHOOK_USERDATA - Can optionally be used to specify the initial value
   of the userdata field in the QProtocolStopMarkerMessage sent to the QProtocolStopMarkerHook
   above. Default is 0. (V51)
    
   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 could not be established.

    
   EXAMPLE
    struct QSession * s;
    
    if (s = QNewSocketSession("example.server.com", 80, NULL))
       printf("Connection to example.server.com:80 was successful\n");
    else
       printf("Connection 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 = QNewSocketSession('example.server.com', 80, 0)
    if (session > 0) then say "Connection was successful!"
                     else say "Connection failed!"
       
   SEE ALSO
    QNewSocketSessionAsync, QNewSocketServerSession, QSendRawOp, QFreeSession