The SHFlavor class is used by SockHop to specify a single file on disk for purposes of downloading and caching. The common usage of SHFlavors is to add them to an SHFileSpec object that specifies what files must be available on the local disk in order for an add-on to be instantiated. Each SHFlavor is a simple data container, storing the following information:
Default constructor, creates an invalid SHFlavor object. The only use for the created object is to copy another SHFlavor into it (using the '=' operator or one of the methods in SHFileSpec).
Copy constructor.
Creates an SHFlavor by reading the appropriate information out of the file specified by (fileName). (fileName) may include a relative or absolute file path. The file's architecture bits will be set to SH_ARCH_ANY, meaning the the file is appropriate for all hardware platforms BeOS runs on.
The other argument, isAddOn, must be specified manually. This flag determines whether or not the object instantiation system will attempt to call load_add_on() on this file before instantiating an SHDistributableObject that includes this SHFlavor. You should only set (isAddOn) to be true if this file is an add-on which contains some or all of the code for your SHDistributableObject subclass. Set (isAddOn) to false for other executables, shared libraries, data files, etc.
Note that errors can occur in this constructor, so the resulting object may not always be valid. To make sure everything went okay, call InitCheck() on this object, or check the result of AddFlavor() when you go to add this SHFlavor to its SHFileSpec(). (AddFlavor() will not accept invalid SHFlavors).
This constructor is the same as the previous one, with the addition of the (architectureBits) argument that lets you specify that this SHFlavor is apropos only to certain types of hardware. For example, if (fileName) specifies a PowerPC executable, you would want to set (architectureBits) to SH_ARCH_BEOS_PPC. If the file is usable by more than one hardware architecture, you may use the bit-wise OR operator ('|') to combine constants--i.e. a file usable on both PowerPC and Intel hardware would be signified by (SH_ARCH_BEOS_PPC | SH_ARCH_BEOS_X86).
This constructor is the same as the previous one, except that this one allows you to specify two locations for your file. The first location, specified by (cacheName), will be used by all SockHop nodes running on computers whose hardware architectures are not specified by (architectureBits). The second location, (nativeName) will be used by SockHop nodes whose hardware (architectureBits) does specify.
Why is this useful? Because in certain situations, it's necessary to keep the native flavor of a file in a well-know location. Take a shared library, for example. It is expected to be in a known spot ("/boot/home/config/lib/libfoo.so") on the hard drive, regardless of whether the system is PowerPC or Intel based. This could cause a problem, since even though an Intel system would never need to use a PowerPC library itself, it still may need to cache the PowerPC library on its local disk somewhere, so that its children can get the library quickly. For this and similar situations, you could use SHFlavors like this:
This way, your cached non-native files won't collide with your in-use,
native files.
These two constructors allow you to specify all data fields of the SHFlavor explicitely. Since these constructors (unlike all the others) do not actually look at any files on your hard disk, they are guaranteed always to produce "valid" SHFlavor objects (that is, InitCheck() will return B_NO_ERROR for them). However, if the information you give is not correct, then SockHop's caching mechanisms may not function correctly. (The most likely malfunction is that SockHop will re-download cached files unecessarily) Because of this, use of these constructors is discouraged unless absolutely necessary.
Assignment operator. All fields are copied verbatim.
Comparison operator. Two SHFlavors are considered equal if all of their fields are equal. The exception is the "isAddOn" property, which is ignored for this comparison.
Comparison operator. Returns the opposite of what '==' would return.
These methods implement the BFlattenable interface for SHFlavor. They work pretty much the way you would expect. Note that these methods will not work on an invalid SHFlavor object (they will return B_ERROR, etc).
Returns the filepath indicating the location where the file will be
cached, as was specified in the constructor. Returns NULL if the
SHFlavor object is invalid.
Returns a filepath indicating where the file will be cached on "native" platforms, as was indicated in the constructor. If (nativeName) was not specified in the constructor, then this method will return the same value as GetCacheName(). See the constructor documentation above for info on cached versus native locations. Returns NULL if the SHFlavor object is invalid.
A simple convenience function that returns the native name if the local hardware is "native", otherwise the cached name. Implemented with logic equivalent to "if (SupportsArchitecture(SHGetArchitectureBits()) then return GetNativeName() else return GetCacheName()".
Returns a bit-chord indicating which hardware architecture or architectures may make use of this SHFlavor's file (as was specified in the constructor). For example, an SHFlavor representing an Intel executable file might return SH_ARCH_BEOS_X86 from this method, whereas an SHFlavor representing a .JPEG file might return SH_ARCH_ANY.
Returns the size of the specified file, in bytes. Result undefined
if the SHFlavor is invalid.
Returns the modification timestamp of the file as was determined in the constructor. Result undefined if the SHFlavor is invalid.
Returns a boolean indicating whether or not the file is to be treated as an add-on file (as was specified in the constructor).
Dumps the state of the SHFlavor to stdout.
Returns true iff all the bits found in the bitchord returned by SHGetArchitectureBits() are also found in (bits)--that is, iff (bits) is a superset of SHGetArchitectureBits(). Calling this method with the current architecture's bits (as returned by SHGetArchitectureBits()) as an argument is how SockHop determines whether an SHFlavor is "native" (i.e. usable by the hardware of the local machine) or not.
Returns B_NO_ERROR if this SHFlavor object is valid, some other value if it's not. If an SHFlavor is invalid, it's usually because its constructor specified a file that did not exist on the local disk, or was not readable. Invalid SHFlavors are pretty useless, as SHFileSpecs will not accept them.