The SHNodeSpec class (derives from BFlattenable)

To easily specify the characteristics of a node in the tree, SockHop defines the class SHNodeSpec.  Note that an SHNodeSpec is not necessarily a reference to any particular existing node in the tree; rather, it is a set of values that specify how a node or connection can be made.  Each SHNodeSpec object holds the following information:

SHNodeSpecs are subclasses of BFlattenable, so it is easy to add them to a BMessage:

     BMessage myMessage(SH_NODE_ADDCOMPONENTS);
     myMessage.AddFlat(SH_NAME_CHILDREN, &SHNodeSpec("child"));

       They also have some niceties defined like Gets and Sets for all the fields mentioned above, copy constructors, and some operators defined for them.  All of these features should be self-explanatory.
 



SHNodeSpec() 

Default constructor, creates object with all fields empty



SHNodeSpec(const SHNodeSpec & copyMe)

Copy constructor - creates a clone of (copyMe)
    



SHNodeSpec(const char * nodeName)
SHNodeSpec(const char * nodeName, const BMessage & specMsg)

Constructors that specify a child node that runs in the same process space as its parent.
  



SHNodeSpec(const char * nodeName, const char * hostName)
SHNodeSpec(const char * nodeName, const char * hostName, const BMessage & specMsg)
SHNodeSpec(const char * nodeName, const char * hostName, int portNum)
SHNodeSpec(const char * nodeName, const char * hostName, int portNum, const BMessage & specMsg)

Constructors that specify a child node that runs remotely, via TCP, on a specified host.
      



SHNodeSpec & operator =(const SHNodeSpec & copyMe)

Assignment operator.



bool operator ==(const SHNodeSpec & compareMe) const

Comparison operator.  Note:  The (specMsg) fields of the two objects are NOT examined as part of this comparison!
  



bool operator !=(const SHNodeSpec & compareMe) const

Comparison operator.  Note:  The (specMsg) fields of the two objects are NOT examined as part of this comparison!
  



virtual bool IsNodeNameValid() const

Returns true only if the node name field of this object is valid.  Validity means:  the node name may not be equal to "", "." or "..", and it may not have a '/' character in it, nor may it be longer than SH_MAX_NODENAME_LENGTH bytes.
  



virtual status_t Flatten(void * buf, ssize_t numBytes) const
virtual status_t Unflatten(type_code code, const void * buf, ssize_t numBytes)
virtual ssize_t FlattenedSize() const
virtual type_code TypeCode() const
virtual bool IsFixedSize() const

These methods implement the BFlattenable interface for SHNodeSpec.  They all work as you would expect.



void SetHostName(const char * newHostName)

Sets the hostname field of this object.  An internal copy of the string is created and retained.
  



const char * GetHostName() const

Returns a pointer to the host name string held by this SHNodeSpec.  String will be valid till this object is destroyed, or SetHostName() is called on it.  Guaranteed to never return NULL (returns "" if unset)
   



void SetNodeName(const char * newNodeName)

Sets the node name field of this object.  An internal copy of the string is created and retained.
  



const char * GetNodeName() const

Returns a pointer to the node name string held by this SHNodeSpec.  String will be valid till this object is destroyed, or SetNodeName() is called on it.  Guaranteed to never return NULL (returns "" if unset)
   



void SetPortNumber(uint32 newPortNum)

Sets the port number field of this SHNodeSpec to (newPortNum).
  



uint32 GetPortNumber() const

Returns the port number of this SHNodeSpec.  By default, this field is set to the value SH_DEFAULT_PORT, as defined in <sockhop/SockHopConstants.h>



BMessage & GetSpecMessage()

Returns a reference to the held BMessage.  User code may read or write this message any way it likes.
This BMessage may be used by the SHAccessPolicy objects running on the SockHop servers to decide whether or not your connection
is worthy of continuing.  For example, the SHDefaultAccessPolicy object often looks up the string field "password" in this BMessage.



const BMessage & GetConstSpecMessage() const

Same as GetSpecMessage(), but returned as a const reference, so you can't write to it.
  



void PrintToStream() const

Dump the state of the SHNodeSpec to stdout