The following table describes standardized public I.F. protocols.
Protocol
| Author
| Description
|
constructhelp
| Christopher Allen
| This I.F. protocol indicates that documentation is present for individual construct types. This documentation can be accessed by calling "constructhelp" member functions on constructs that support them.
To support the protocol, declare any number of member functions with the syntax of "char *constructhelp()" or "char *constructhelp(long page)". The first syntax returns a pointer to the entire plain-text documentation. The second syntax returns a pointer to a single page of plain-text documentation.
The returned pointer represents a null-terminated ASCII string. For the "paged" syntax, the function must return a pointer consistent with the page number passed as a parameter. The page numbers can start at either 0 or 1.
It is not necessary to declare a "constructhelp" member function for every block or data structure in the I.F. Instead, methods should be present for only those constructs that warrant documentation.
|
detailedformat
| Christopher Allen
| The "detailedformat" I.F. protocol identifies an I.F. that characterizes data with a high level of detail. Many small components of the file, down to minutiae in some cases, are characterized.
As a natural consequence of detail level, this type of I.F. tends to require significantly more node handles than more general schemas. Make sure that enough node handles are free for use in the BAR_Services instance before attempting to deserialize using this type of I.F.
|
documentation
| Christopher Allen
| This I.F. protocol indicates that single-topic documentation is present for the I.F. This documentation can be accessed by calling the "documentation" global function.
To support the protocol, declare a global function with the syntax of "char *documentation()" or "char *documentation(long page)". The first syntax returns a pointer to the entire plain-text documentation. The second syntax returns a pointer to a single page of plain-text documentation.
The returned pointer represents a null-terminated ASCII string. For the "paged" syntax, the function must return a pointer consistent with the page number passed as a parameter. The page numbers can start at either 0 or 1.
|
flagpoll
| Christopher Allen
| The "flagpoll" I.F. protocol is used to query the results of flags fields in binary files. A flags field is typically an integer variable that breaks down further into individual one-bit or multi-bit portions.
Although bit field structures can be used to characterize flags fields in BAR, they are not always the best means of characterizing the values. Furthermore, in some cases, flags can take on different meanings based on specific combinations of flags.
To support this protocol, define a member function, named "flagpoll", of a structure or a block that contains one or more flags fields. There is no standard for the parameter format and internal operation of the function, but the return value must always be type char *. The function returns text information, typically enumerated constant names and/or values, representing the flags stored in the variable.
One way to represent file attribute flags would be to return the string "READONLY | ARCHIVE | HIDDEN".
|
forcebigendian
| Christopher Allen
| The "forcebigendian" I.F. protocol identifies a deserialized file as being in big-endian byte order or bit order. Parts of the file that do not start out in this order are converted to big-endian order during deserialization.
Note that fields characterized by enumerated constants do not need to abide by a particular endian order. As long as the field is enumerated correctly in BARfly, it needs not have big-endian representation.
|
forcelittleendian
| Christopher Allen
| The "forcelittleendian" I.F. protocol identifies a deserialized file as being in little-endian byte order or bit order. Parts of the file that do not start out in this order are converted to little-endian order during deserialization.
Note that fields characterized by enumerated constants do not need to abide by a particular endian order. As long as the field is enumerated correctly in BARfly, it needs not have little-endian representation.
|
lengthfinder
| Christopher Allen
| The "lengthfinder" I.F. protocol is typically found in implementation files that store block lengths or iteration counts in structured fields. In other words, most binary files.
What "lengthfinder" does is provide an empirical calculation scheme for block lengths and iteration counts in the deserialized file by examining its own deserialized contents. Existing values of lengths and counters are overwritten and set to correct values.
To support this protocol, define a single member function of the top-level node, called "lengthfinder." When run, navigation functions cycle through the existing nodes, counting sizes and child counts, and updating fields accordingly.
Calling this top-level member function will automatically update length fields. This can be an enormous time-saver: you don't need to manually edit all length-oriented fields before updating a data file.
|
modeselect
| Christopher Allen
| This I.F. protocol indicates one or more mode-selection features. Deserialization and/or serialization is directly affected by calls to I.F. functions, which "prime" the I.F. before an actual load or save takes place.
The protocol places no restrictions on the number or functionality of the mode-selection functions. A user must consult individual I.F. documentation to learn how to use these functions effectively.
|
proprietary
| Christopher Allen
| This I.F. protocol indicates that an I.F. is NOT free for general distribution, due to legal restrictions placed on the file contents (copyright) or algorithms used to conduct the deserialization and/or serialization process (patent).
If you have developed an I.F. on your own, mark the I.F. as proprietary unless and until you decide to release the file for general distribution.
If you have purchased an I.F. marked as proprietary, you must abide by additional legal restrictions as a condition for using the I.F.
|
strongvalidation
| Christopher Allen
| The "strongvalidation" I.F. protocol states that the I.F. conducts a very thorough type of validation of file contents as part of deserialization.
The bare-minimum requirements for file characterization include using Validation functions only to tell construct choices apart from each other. This is weak validation.
Strong validation goes a step further: an I.F. is used to examine data structures in a more agressive manner, checking boundary requirements, cross-checking multiple nodes for consistency, and performing any other technique deemed necessary to ensure validity, such as CRC calculations.
|
