---

User-level Format Functions

This is a set of functions related to handling "user formats". More...

Functions
IOContext	CMget_user_type_context (CManager cm)
void	CMfree_user_type_context (CManager cm, IOContext context)
IOFormat	CMregister_user_format (CManager cm, IOContext context, char *format_name, IOFieldList field_list, CMFormatList subformat_list)
IOFormat	CMlookup_user_format (CManager cm, IOFieldList field_list)
IOFormat	CMget_IOformat_by_name (CManager cm, IOContext context, char *name)
IOFormat	CMget_format_IOcontext (CManager cm, IOContext context, void *buffer)
IOFormat *	CMget_subformats_IOcontext (CManager cm, IOContext context, void *buffer)
void	CMset_conversion_IOcontext (CManager cm, IOContext context, IOFormat format, IOFieldList field_list, int native_struct_size)

---

Detailed Description

This is a set of functions related to handling "user formats".

I.E. PBIO formats that might be used by the application or higher level library, but which are *not* used for CM messages.

The formats registered using CMregister_format() are used to encode messages that go directly over the network connections, or to decode messages that come in over those connections. PBIO manages these formats, gathering formats that it needs and caching them for future use.

However, CM also has facilities to support a second class of PBIO formats, called user formats. Applications using these facilities can take advantage of CM's format management services to encode data that is not transmitted directly over the network links.

To understand when this might be appropriate, consider an remote procedure call library that allows its users to register procedure names and parameter type profiles and make them available for remote access. The library might be implemented in CM using a "RPC Request" message with a the procedure to call specified by a string name and the parameters to that procedure passed as a dynamically sized block of characters. This is a simple approach to library implementation, but how should the parameter block be encoded? Leaving the marshalling/unmarshalling to the application is simple, but unappealing. PBIO's IOContext routines were designed for precisely this sort of situation, allowing data to be encoded into an arbitrary memory block, transmitted elsewhere by any mechanism, and then decoded upon arrival. The RPC library could use PBIO for this task independently of CM, but then is loses out on the features that CM provides (such as each CM acting as its own format server instead of using a common format server).

CM's user formats support routines allow such a library to leverage CM's format services while still largely using PBIO without interference. Because these facilities are preliminary, subject to change, and unlikely to be required except for the most advanced uses of CM, they are not described here in detail. Instead we just list the current interface. Users requiring more information are encouraged to contact the author.

---

Function Documentation

IOContext CMget_user_type_context (  CManager    cm )

get a PBIO IOContext to be used for user format operations Parameters: cm  The CManager from which to acquire the user type context.

void CMfree_user_type_context (  CManager    cm, IOContext    context )

deallocate a PBIO IOContext acquired with CMget_user_type_context() Parameters: cm  The CManager from which the context was acquired. context  the IOContext to free.

IOFormat CMregister_user_format (  CManager    cm, IOContext    context, char *    format_name, IOFieldList    field_list, CMFormatList    subformat_list )

register a user format with CM. Parameters: cm  The CManager from which the IOContext was acquired. context  The IOContext with which to register the format. format_name  The textual name to associate with the structure format. field_list  The PBIO field list which describes the structure. subformat_list  A list of name/field_list pairs that specify the representation of any nested structures in the message. If the message field types are simple pre-defined PBIO types, subformat_list can be NULL. Otherwise it should contain the transitive closure of all data types necessary to specify the message representation. The list is terminated with a {NULL, NULL}<\tt> value.

IOFormat CMlookup_user_format (  CManager    cm, IOFieldList    field_list )

lookup a user format based on the field list. This call us the user-format analogue of CMlookup_format(). Parameters: cm  The CManager in which the format was registered. field_list  The field list which was used in the registration. Returns: a PBIO IOFormat value Note: The return type differs from CMlookup_format() because we expect the application to use PBIO directly for some calls. For example, after a format is registered, PBIO encode routines can be used directly. Warning: Using a PBIO-level calls and for which there is a corresponding CM call may result in race conditions and unpleasant consequences.

IOFormat CMget_IOformat_by_name (  CManager    cm, IOContext    context, char *    name )

get a registered IOformat based on its simple name. Parameters: cm  The CManager in which the format was registered. context  The IOContext in which the format was registered. name  The name that was given the format when it was registered. Returns: a PBIO IOFormat value. This call maps directly to the PBIO routine get_IOformat_by_name(). A CM version is provided so that CM can protect data structures for thread safety. Warning: Using a PBIO-level calls and for which there is a corresponding CM call may result in race conditions and unpleasant consequences.

IOFormat CMget_format_IOcontext (  CManager    cm, IOContext    context, void *    buffer )

determine the IOFormat of data in an encoded buffer. Parameters: cm  The CManager from which the context was acquired. context  The IOContext to be used for determining the format. buffer  The buffer holding the encoded data. Returns: The IOFormat value that describes the encoded data. This call maps directly to the PBIO routine get_format_IOcontext(). A CM version is provided so that CM can protect data structures for thread safety. Warning: Using a PBIO-level calls and for which there is a corresponding CM call may result in race conditions and unpleasant consequences.

IOFormat* CMget_subformats_IOcontext (  CManager    cm, IOContext    context, void *    buffer )

determine the transitive closure of IOFormats used in data in an encoded buffer. Parameters: cm  The CManager from which the context was acquired. context  The IOContext to be used for determining the format. buffer  The buffer holding the encoded data. Returns: A NULL-terminated list of IOFormat values that occur in the encoded data. The last entry will be the IOFormat that would be returned by CMget_format_IOcontext(). Conversions can be registered in the order they appear in the list. This call maps directly to the PBIO routine get_subformats_IOcontext(). A CM version is provided so that CM can protect data structures for thread safety. Note: The IOFormat* value returned should be released with CMfree(). Warning: Using a PBIO-level calls and for which there is a corresponding CM call may result in race conditions and unpleasant consequences.

void CMset_conversion_IOcontext (  CManager    cm, IOContext    context, IOFormat    format, IOFieldList    field_list, int    native_struct_size )

set a conversion (correspondence between wire and native formats) for an incoming IOFormat. Parameters: cm  The CManager from which the context was acquired. context  The IOContext in which to register the conversion. format  The IOFormat for which to register a conversion. field_list  The IOFieldList describing the native structure. native_struct_size  The sizeof() value for the native structure. Note: Once a conversion has been set, the PBIO decode routines can be used directly.

---