The SHAccessPolicy inheritance API (derives from SHComponent -> SHDistributableObject -> BArchivable)

The SHAccessPolicy class gives you some amount of control over what actions clients that connect to your server or SHSessionAcceptor can tell SockHop to take.  It also is used to specify which TCP port a SockHop server or SHSessionAcceptor should listen on for incoming connections.  A SockHop node will call various methods in its SHAccessPolicy object to determine if it has permission to perform certain potentially dangerous actions.  Note that if your SHAccessPolicy object allows connecting clients to download and execute add-ons, then the added-on code will be able to circumvent any restrictions imposed (because the add-ons are full-fledged C++ code, and can make system calls (etc) directly).

Most of the methods in the SHAccessPolicy class are abstract, and must be defined by a subclass.  For many common purposes, however, you can use an SHDefaultAccessPolicy object, which defines all methods and is thus instantiatable.
 



SHAccessPolicy(BMessage * archive)

Rehydration constructor.  See the note regarding server command line arguments, under Archive().
 



virtual status_t Archive(BMessage * archive, bool deep = true) const

Dehydration method.  Subclasses should call this from their own Archive() method.
NOTE:  When libsockhop.so is executed to start a SockHop server, any parameters entered on the command line as "key=value" will be added as strings to a BMessage that will be used to create an SHAccessPolicy object.  So if you wish to allow users to specify a parameter in your SHAccessPolicy subclass from the command line when they start a SockHop server, be sure to store that parameter into (archive) as a string, under a documented field name.



virtual void OnServerStartup()

Called when the SockHop server starts.  Default version does nothing.
 



virtual void OnServerShutdown()

Called when the SockHop server exits.  Default version does nothing.  (Note: not currently called when shutdown is due to a CTRL-C)
 



virtual SHNodeSpec GetListeningLocation() = 0

Should return an SHNodeSpec with its port number field set to the port number the owning object should listen on for incoming connections.  If it returns an SHNodeSpec with a port number zero, the system will choose an available port number to listen on.  The other fields in the SHNodeSpec aren't used by SockHop, although your code can fill them in for its own use, if it wants.
 



virtual bool OkayToAcceptConnection(SHNodeSpec & connectingSpec) = 0

Should return true iff it's okay to accept a connection from the given host.   (connectingSpec) contains information about the potential connectee.  You can also modify (connectingSpec), if you feel the need to, although this isn't generally recommended unless you know what you're doing.
 



virtual bool OnSessionAccepted(SHDirectConnection & connection)

Called when an SHDirectConnection has been created for a new connection.  Default implementation calls connection.Start() so that the SHDirectConnection can begin operation. Should return true if the SHDirectConnection is to continue, or false if there was an error and the SHDirectConnection should be aborted.  If you override this method, be sure to call the OnSessionAccepted() of your parent class, so that the session will be Start()'d.
 



virtual void OnNodeStartup()

Called when a new SockHop node starts running.  Default version does nothing.  (Note that each new node gets its own copy of the SHSessionAcceptor--this is necessary since each new node may be running in a different address space!)
 



virtual void OnNodeShutdown()

Called when a new SockHop node quits.  Default version does nothing.
 



virtual bool OkayToWriteFile(const char * fileName) = 0

Should return true iff it's okay to write to the given file.
 



virtual bool OkayToReadFile(const char * fileName) = 0

Should return true iff it's okay to read from the given file.



virtual bool OkayToInstantiateObject(const BMessage & archive) = 0

Should return true iff it's okay to instantiate an SHDistributedObject from (archive).  This will be called whenever a new SHSorter, SHWorker, or SHAccessPolicy is to be instantiated by a node.



virtual SHAccessPolicy * MakeNodePolicy()

This method is called whenever a new SockHop node is created.  This method should return a new SHAccessPolicy object for the new node to use, or return NULL if you want the node to use a clone of this SHAccessPolicy.   This default implementation returns NULL.  When returning an SHAccessPolicy, make sure it was allocated either with SHCreateDistributableObject(), or the new operator.
 



virtual int GetDefaultDebugLevel()

Should return the initial debugging level for the server or node.  Currently, 0 means no debug printing, >0 means debug printing; more levels may be implemented in the future.  The default implementation of this method returns 0.
 



virtual int32 GetDefaultThreadPriority()

Should return the priority to be given to newly spawned SockHop threads.  The default implementation returns B_NORMAL_PRIORITY.



virtual int32 GetDefaultTransmissionEncoding()

Should return the default encoding method for BMessage data that is sent across TCP links.  The result should be one of the SH_ENCODING_* tokens listed in SockHopConstants.h.  The default implementation returns SH_ENCODING_NONE.