SHDirectConnection objects can both initiate and receive TCP connections, based on the arguments you give to their constructor. Typically one program will create a "passive" SHDirectConnection, and then wait for the other program to create an "active" SHDirectConnection to connect to it. Note that SHDirectConnections can only connect to passive SHDirectConnections or SHSessionAcceptors; they cannot be used to connect directly to SockHop servers, Web servers, or anything else.
Methods in the SHDirectConnection API are:
This constructor creates an "active" SHDirectConnection, which will try to connect to an SHSessionAcceptor or passive SHDirectConnection that is running at the location specified by (connectTo). Once connected, an SH_CODE_CONNECTIONOPEN BMessage will be sent to (target). If the connectee sends any BMessages back across the connection, they will also be forwarded to (target). Finally, when the connection is closed, an SH_CODE_CONNECTIONCLOSED BMessage will be sent to (target) to notify it.
If (startThreadsNow) is specified to be false, the internal threads of the SHDirectConnection will not be spawned automatically. The SHDirectConnection object will thus not do anything until you call the Start() method on it.
(threadPriority) and (encoding) allow you to set the thread priority of the send and receive threads, and the encoding of outgoing BMessages, respectively. (encoding) should be one of the SH_ENCODING_* constants specified in SockHopConstants.h.
This constructor creates a "passive" SHDirectConnection, which will bind to a port and await a connection from another SHDirectConnection object. (policy) determines which port it will bind to, and which connections it will allow itself to receive. (target) and (startThreadsNow) have the same meanings as in the "active" SHDirectConnection constructor (see above).
The destructor closes the TCP connection (if it was open) and destroys the SHDirectConnection object.
Spawns the internal threads for this object. You only need to call this if you set (startThreadsNow) to false in the constructor. This method returns true on success, false if there was an error setting up.
If you want to send BMessages over the SHDirectConnection, you can do so by sending them to the BMessenger that this method returns.
Returns a unique (to the local address space, anyway) ID number for
this SHDirectConnection object. This ID number will be added to the
SH_NAME_CONNECTIONID field of each BMessage this SHDirectConnection sends
to the target you specified in the constructor, so that you can figure
out which SHDirectConnection the BMessage came from..
Returns the SHNodeSpec for thie SHDirectConnection.
For "active" connections, it will be the same as the (spec) that was passed
to the constructor. For passive connections, the port number may
have changed (to zero if there was an error, or to non-zero if it was passed
as zero, allowing the system to choose a port)
Returns a BMessage that is held by this SHDirectConnectionObject. This BMessage is entire for your own use; you can store information associated with the SHDirectConnectionObject in it, if you want.
This method allows you to specify a BMessage that will be added to every BMessage that this SHDirectConnection object forwards to its (target) BMessenger. This allows you to tag BMessages so that when your target code receives them, it knows they came from this SHDirectConnection. (Actually, the BMessages already contain an SH_NAME_CONNECTIONID field for this purpose, but adding a custom BMessage can be useful too)
If (fieldName) is non-NULL, it will be used as the field name of the tag BMessage. If it is NULL, then BMessage tagging is disabled.
This method allows you to change the target of this SHDirectConnection.
Once this method returns, all BMessages that are received over the TCP
connection will be forwarded to (target). This method is thread safe,
so it may be called at any stage of the SHDirectConnection's life.