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:
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:
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.
Default constructor, creates an "empty" SHFileSpec object.
Copy constructor.
Assignment operator.
Comparison operator. Two SHFileSpecs are equal if they contains
the same set of SHFlavors. (Ordering of SHFlavors
within the SHFileSpec is ignored)
Comparison operator. Returns the opposite of what '==' would have
returned.
Returns an SHFileSpec with the flavors of both (this) and (addee). Any
duplicate flavors will have been removed.
Adds the flavors of (addee) to this object. Duplicate flavors will not be added.
Returns an SHFileSpec that contains all the SHFlavors in (this) SHFileSpec, except for the ones that are also in (that).
Removes from (this) any SHFlavors that are present in (that).
These methods implement the BFlattenable interface for SHFileSpec. They work pretty much the way you would expect.
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).
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.
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.
Attempts to copy the SHFlavor at index (index) into (setFlavor). Returns B_NO_ERROR on success, or B_BAD_INDEX if (index) was invalid.
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).
Returns the number of SHFlavors currently in this SHFileSpec's flavor list.
Removes all flavors from this object.
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.
Dumps the state of the SHFileSpec to stdout.