The SHFileSpec class

The SHFileSpec class is what SockHop uses to specify groups of files that are to be distributed across the network and cached on different nodes.  An SHFileSpec can refer to a single file, a set of files, or even several sets of files (one set of files for each supported hardware architecture).  In this way, SHFileSpec objects offer a succinct method of describing all the files necessary to perform an operation (for example, to instantiate an object from an add-on).  SHFileSpec object are used by SockHop's file caching system to automagically manage the intelligent caching and distribution of your files and data over the different machines in your SockHop tree.
SHFileSpecs are containers for simpler objects known as SHFlavors, where each SHFlavor represents one file in the set.

Here is an example of creating a simple SHFileSpec that indicates some data files to be downloaded:

   SHFileSpec spec;
   spec.AddFlavor(SHFlavor("splash.jpg"));     // note:  This example doesn't check return values, but you should!
   spec.AddFlavor(SHFlavor("rocket.jpg"));
   spec.AddFlavor(SHFlavor("sound.wav"));

Sending this SHFileSpec as part of an SH_COMMAND_ADD_COMPONENTS BMessage would cause these files to be transferred to the current directory of every SockHop node that the BMessage specified.

Here's a somewhat fancier example:

   SHFileSpec spec;
   spec.AddFlavor(SHFlavor("my_program_x86", SH_ARCH_BEOS_X86));  // note:  This example doesn't check return values, but you should!
   spec.AddFlavor(SHFlavor("my_program_ppc", SH_ARCH_BEOS_PPC));
   spec.AddFlavor(SHFlavor("another_program_x86", SH_ARCH_BEOS_X86));
   spec.AddFlavor(SHFlavor("another_program_ppc", SH_ARCH_BEOS_PPC));
   spec.AddFlavor(SHFlavor("readme.txt", SH_ARCH_ANY));

As you might guess, this SHFileSpec specifies a different set of files to be downloaded to different computers.  All Intel-based machines that receive the download message would get copies of "my_program_x86" and "another_program_x86".  The PowerPC-based machines would get "my_program_ppc" and "another_program_ppc".  All the machines (PowerPC and Intel) would receive a copy of "readme.txt", since it is marked as usable by any architecture.

Note the the SH_ARCH_* constants are bitchords, which means that you can combine them to specify flavors that are acceptable on multiple types of hardware.  Of course, there are currently only two architectures defined, since SockHop only runs on BeOS, which only runs on PowerPC and Intel platforms.  The constant SH_ARCH_ANY (which is the flavor bitchord used when you don't specify an architecture) is just a chord with all the bits set, meaning that any type of hardware can use the file the SHFileSpec represents.
 



SHFileSpec()

Default constructor, creates an "empty" SHFileSpec object.



SHFileSpec(const SHFileSpec & copyMe)

Copy constructor.


SHFileSpec & operator =(const SHFileSpec & copyMe)

Assignment operator.



bool operator ==(const SHFileSpec & compareMe) const

Comparison operator.  Two SHFileSpecs are equal if they contains the same set of SHFlavors.  (Ordering of SHFlavors within the SHFileSpec is ignored)
 



bool operator !=(const SHFileSpec & compareMe) const

Comparison operator.  Returns the opposite of what '==' would have returned.
 



SHFileSpec operator + (const SHFileSpec & addee) const

Returns an SHFileSpec with the flavors of both (this) and (addee). Any duplicate flavors will have been removed.
 



SHFileSpec & operator += (const SHFileSpec & addee)

Adds the flavors of (addee) to this object.   Duplicate flavors will not be added.



SHFileSpec operator - (const SHFileSpec & that) const

Returns an SHFileSpec that contains all the SHFlavors in (this) SHFileSpec, except for the ones that are also in (that).



SHFileSpec & operator -= (const SHFileSpec & that)

Removes from (this) any SHFlavors that are present in (that).


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 SHFileSpec.  They work pretty much the way you would expect.



status_t AddFlavor(const SHFlavor & flavor)

Attempts to add (flavor) to this SHFileSpec object.  Note that (flavor) is copied; the calling code retains ownership of its copy of (flavor).   Returns B_NO_ERROR if the new SHFlavor was successfully added, or B_BAD_VALUE if the SHFlavor could not be added because it wasn't valid (i.e. its InitCheck() method didn't return B_NO_ERROR).  If (flavor) is a duplicate of an SHFlavor that is already in this SHFileSpec, it will not be added again (but B_NO_ERROR will be returned anyway).



status_t RemoveFlavor(const SHFlavor & flavor)

Attempts to remove an SHFlavor that is equal to (flavor) from our set.  Returns B_NO_ERROR if an SHFlavor was removed, or B_NAME_NOT_FOUND if no matching SHFlavor was present.



status_t RemoveFlavorAt(int32 index)

Attempts to remove the SHFlavor at the (index)'th position in our list, with the first position being position zero.  Returns B_NO_ERROR if an SHFlavor was successfully removed, or B_BAD_INDEX if not a valid index.



status_t GetFlavorAt(uint32 index, SHFlavor & setFlavor) const

Attempts to copy the SHFlavor at index (index) into (setFlavor).  Returns B_NO_ERROR on success, or B_BAD_INDEX if (index) was invalid.



int32 IndexOf(const SHFlavor & flavor) const

Returns the position index of the SHFlavor that is equal to (flavor) in the SHFileSpec's flavor list, or -1 if no flavor in the list matches (flavor).



uint32 CountFlavors() const

Returns the number of SHFlavors currently in this SHFileSpec's flavor list.



void MakeEmpty()

Removes all flavors from this object.



void Strip(uint32 whichArchs)

Removes all flavors from this SHFileSpec except for the ones that match the given architecture bitchord.  If no flavors match the architecture bitchord, the SHFileSpec becomes empty.



void PrintToStream() const

Dumps the state of the SHFileSpec to stdout.