SHSessionAcceptor API

The SHSessionAcceptor class is another specialized utility class.  This one provides a quick and easy way to set up a "server thread", that can accept an arbitrary number of SHDirectConnections for you.  It operates as a factory object--it listens on a specified port for incoming connections, and whenever it receives one, it creates a new SHDirectConnection object.  By default, the SHSessionAcceptor object will keep track of the SHDirectConnection objects for you, but if you prefer, you can detach the SHDirectConnection objects from the SHSessionAcceptor and handle them yourself.

Whenever a new connection is accepted, the SHSessionAcceptor object will send an SH_CODE_CONNECTIONOPEN BMessage to the (target) specified in the BMessenger constructor.  When a session ends, an SH_CODE_CONNECTIONCLOSED BMessage will be sent.  Also, by default any BMessages that the remote client of the session sends will be forwarded to (target) also--but a custom SHAccessPolicy could change this behavior by calling SHDirectConnection::SetTarget() in its OnSessionAccepted() method.

The SHSessionAcceptor API is as follows:


SHSessionAcceptor(const BMessenger & target, SHAccessPolicy * policy, bool startImmediately)

This constructor creates an SHSessionAcceptor using the given SHAccessPolicy, that will send messages to the given (target).  (policy) determines which port this SHSessionAcceptor will listen on, and which connections it will accept.  For most purposes, an SHDefaultAccessPolicy object will suffice.  Note that (policy) becomes property of the SHSessionAcceptor object, and should not be touched by any other code after this constructor returns.

If you specify (startImmediately) to be false, then that this SHSessionAcceptor won't become active until its Start() method is called (see below).



~SHSessionAcceptor();

Destroys the SHSessionAcceptor object, and any SHDirectConnections that are attached to it.



bool Start();

Causes the SHSessionAcceptor to bind to the port specified by its policy object, and fire off an acceptor thread to begin accepting connections.  Returns true on success, false if there was an error setting up.  If the SHSessionAcceptor is already accepting connections, this method will return true with no side effects.



SHNodeSpec GetAcceptSpec() const;

Returns the SHNodeSpec that the SHSessionAcceptor is listening on (as determined by the policy object given to the constructor).  If anyone wants to know how to connect to your SHSessionAcceptor, tell them to create an "active" SHDirectConnection that connects to this SHNodeSpec!  Note that the return value of this method is only valid after the Start() method has been called.  If the port number of the SHNodeSpec this method returns is zero, then there was an error setting up the accepting socket/port--most likely, the requested port was already in use by another program.



status_t CloseSession(int32 sessionID)

Closes the held session that has the given ID.  Returns B_NO_ERROR if the session was found and closed, B_ERROR if it could not be found.



void CloseAllSessions()

Closes all sessions held by this SHSessionAcceptor.
 



status_t SendMessageToAllSessions(const BMessage & message)

Broadcasts the given BMessage to all held sessions.  Returns B_NO_ERROR if everything goes okay, B_ERROR if there were problems sending the message (in which some of the sessions may not have got the message)
 



status_t SendMessageToSession(int32 messageID, const BMessage & message)

Sends the given BMessage to the session with the given (messageID).  Returns B_NO_ERROR if the message send succeeded, B_ERROR if a session with the given (messageID) was not found, or some other error code if the SendMessage() call failed.



SHDirectConnection * DetachSession(int32 messageID)

Removes the session with the given (messageID) from the SHSessionAcceptor's control, and returns it to the calling code as an SHDirectConnection.  Returns NULL if the session with the given (messageID) could not be found.

NOTE:  Once this method returns an SHDirectConnection, the SHSessionAcceptor is no longer associated with the SHDirectConnection in any way,  The calling code becomes sole owner of the SHDirectConnection object, and it becomes the calling code's responsibility to delete the SHDirectConnection when it is done with it.
 



void DetachAllSessions(BList & getConnectionObjects)

Calls DetachSession() on all current sessions, and adds pointers to the SHDirectConnection objects for all sessions as items in the passed-in BList.  By calling this method, the calling code accepts responsibility for deleting all the SHDirectConnection objects added to the passed-in BList.