Global SockHop Functions

While most of the SockHop API is implemented through C++ classes and BMessage parsing, there are a few global, "C style" functions exported by libsockhop.so.  They are all defined in (sockhop/SockHopFunctions.h) as follows:



BLooper * SHCreateRootNode(const BMessenger & repliesTo, SHAccessPolicy * optPolicy = NULL)

This function is used by almost all SockHop programs.  It returns a BLooper object that you can send BMessages to to set up and control the SockHop node tree.  Whenever the SockHop tree has something to say back to you, it will send a BMessage using a copy of the BMessenger you specify in (repliesTo).

Note that the returned BLooper acts just like a regular, freshly created BLooper--you must call Run() on it before it will do anything on its own (such as responding to BMessages you send it), and you should call Lock() and Quit() on it when you are done with it.  Note that calling Quit() on this BLooper will cause the automatic destruction of any node tree you created by sending BMessages to the BLooper.

If (optPolicy) is specified, it should point to an SHAccessPolicy object that has been allocated with SHCreateDistributableObject(), or with the new operator.  This SHAccessPolicy object then becomes property of the root node--other code should not reference it after this call returns.  This policy object will be used to make various access capability decisions during the lifetime of the root node.  If no SHAccessPolicy object is specified, then an SHDefaultAccessPolicy object is created internally and used.

Note:  This function may return NULL if an error occurs.



SHDistributableObject * SHCreateDistributableObject(const BMessage & archive)

This method is a SockHop-friendly way of manually loading SockHop add-ons.  If your add-on derives from SHDistributableObject (as all SockHop add-ons should), you can load an instance of your class into memory by calling this method.  The object will be created based on the BMessage you supply (which is passed to the Instantiate() method of your SHDistributableObject subclass).  Your BMessage may be one that was produced by an SHDistributableObject's Archive() method, or you can fake it by hand-creating a BMessage with the appropriate class name in the "class" field, and the appropriate SHFileSpec flattened into the SH_NAME_ADDONSPEC field.  Note that this function does not attempt to download the necessary add-on file onto your machine--if the add-on isn't available locally (in the file specified by the SH_NAME_ADDONSPEC field of (archive)), this function will fail and return NULL.

It's better to use this function than the bare load_add_on() and unload_add_on() functions that Be provides, for two reasons:  first, this function is a little easier to use, but more importantly, because it is safer.  Here's why:  if you ever run any SockHop nodes in your local process space, they may be loading or unloading your add-on at various times.  Since add-on images are visible to the entire process, loading or unloading an add-on will affect other threads if they are using that add-on.  That is, you might be executing code from the add-on when the SockHop node thread decides to unload it!  But if you use SHCreateDistributableObject() and SHDeleteDistributableObject() to manage your SockHop add-ons, the add-on images will be reference-counted correctly, and you won't crash and burn mysteriously....



void SHDeleteDistributableObject(SHDistributableObject * deleteMe)

This is the destructive counterpart to SHCreateDistributableObject().  Whenever you are done with an object you created using SHCreateDistributableObject(), you should call this function to dispose of the object.  DON'T just delete the object with the delete operator--that will destroy the object, all right, but the reference count won't be decremented, and you will end up wasting memory on add-on images that could have been unloaded.

Note that the opposite case is acceptable:  if you have allocated an SHDistributableObject using the new operator, it is legal to delete it with SHDeleteDistributableObject() (which will just call the delete operator for you in this case).



uint32 SHGetArchitectureBits()

Simply returns the SH_ARCH_* constant for the architecture that this code is currently running on.
 

Back to Top