SHDirectConnection API
 
The SHDirectConnection class is a utility class for creating BMessage pathways directly between two programs.  In most cases, creating an SHDirectConnection isn't necessary, because you can use SockHop's regular message routing services or symlinking to send BMessages down the tree to your code.  In a few cases, however, an SHDirectConnection can come in handy.  For example, if you want to be able to communicate with the SockHop tree from SockHop-based programs that aren't actually part of the tree, then an SHDirectConnection is a good way to do it.

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:



SHDirectConnection(const BMessenger & target, const SHNodeSpec & connectTo, bool startThreadsNow, int32 threadPriority = B_NORMAL_PRIORITY, int32 encoding = SH_ENCODING_NONE);

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.



SHDirectConnection(const BMessenger & target, SHAccessPolicy * policy, bool startThreadsNow);

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).



virtual ~SHDirectConnection()

The destructor closes the TCP connection (if it was open) and destroys the SHDirectConnection object.



bool Start()

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.



BMessenger GetMessenger() const

If you want to send BMessages over the SHDirectConnection, you can do so by sending them to the BMessenger that this method returns.



int32 GetId() const

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..
 



SHNodeSpec GetNodeSpec() const

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)
 



BMessage & GetUserMessage()

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.



void SetTagMessage(const char * fieldName, const BMessage & msg)

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.



void SetTarget(const BMessenger & target)

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.