amarquee.library/QNewSessionAsync amarquee.library/QNewSessionAsync
NAME
QNewSessionAsync - Starts a TCP connection thread to AMarqueed, returns immediately. (V50)
SYNOPSIS
#include
struct QSession * QNewSessionAsync(char * hostname, LONG port, char * progname)
struct QSession * QNewSessionAsyncTags(char * hostname, LONG port, char * progname, ULONG tag1, ...)
FUNCTION
This function works the same as QNewSession, 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
your program's "home directory" as the qm_Path field
(e.g. "/serverhostname/yourprogname"), 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.
INPUTS
hostname - The IP name of the computer to connect to. (e.g.
foo.bar.com)
port - The port to connect on. Port 2957 is the "official"
AMarqueed port.
progname - A null-terminated string indicating the name
the client program wishes to use. If another
client from your host has already registered
progname, the server for that client will close
its connection and quit so that your client program
will still be uniquely addressable.
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 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 = QNewSessionAsync("example.server.com", 2957, "ExampleProgram",NULL))
{
printf("Connecting to example.server.com:2957 ....\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");
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 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.
Tags cannot be used.
AREXX EXAMPLE
session = QNewSessionAsync('example.server.com', 2957, 'ExampleScript')
if (session > 0) then say "Call was successful."
else say "Call failed!"
/* Now wait for QMessages with GetNextQMessage... */
SEE ALSO
QNewSession, QNewHostSession, QNewServerSession, QFreeSession
Converted on 24 Mar 2002 with RexxDoesAmigaGuide2HTML 2.1e(private) by Michael Ranner.