Function Name: Create Reference Symbol From User Data

Definition

Creates a reference symbol that uses a block of data in some user-defined structure as identifying symbolic information, and provides a comparison-function pointer for that type of user-defined data.

This reference symbol can be used in SE_AddSymbolicComponent() and/or SE_AddSymbolicAssociate() either before or after being assigned to an object with SE_AssignReferenceSymbolToObject(). This allows a user to create an object's relationships without keeping the object in memory for a prolonged period of time.

NOTES:

1. The memory for the user data is the user's responsibility. The user must NOT free or tamper with the "blob" of user data while the reference symbol is active, and the user is responsible for freeing the "blob" after the reference symbol itself has been freed via SE_FreeReferenceSymbol().

2. Once a user has begun creating reference symbols with a particular kind of user data, call it type A, with some compare function ACOMP, then all reference symbols created with SE_CreateReferenceSymbolFromUserData() by that user during that session must use the same underlying type A and compare function ACOMP.

3. While this reference symbol is active (i.e., between the time it is created by this function and the time it is freed by SE_FreeReferenceSymbol()), no other reference symbols may be created by SE_CreateReferenceSymbolFromUserData() using the same "blob" of user data (where "same" is defined by * comp_func_ptr).

4. This places no restrictions on reference symbols created using SE_CreateReferenceSymbolFromUInt32() or SE_CreateReferenceSymbolFromString()).

Returns

SE_NULL_REQUIRED_PARAMETER - and no changes are made, if symbol_ptr_in, comp_func_ptr, or ref_symbol_out_ptr is NULL.

SE_DUPLICATE_REFERENCE_SYMBOL - and *ref_symbol_out_ptr is set to NULL, if the reference symbol has been created previously.

SE_OUT_OF_MEMORY - and *ref_symbol_out_ptr is set to NULL, if the reference symbol could not be allocated.

SE_FAILURE - and *ref_symbol_out_ptr is set to NULL, if the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

implementation_identifier

 identifies the API implementation
    to use when creating this reference symbol.  If the specified API can't
    create the reference symbol, then the API will return a status code
    indicating why it could not be created.  If implementation_identifier is
    NULL, then the API implementation to be used must be statically bound at
    compile time.

    See also SE_GetImplementationIdentifier().

symbol_ptr_in

 a pointer to a block of data in some user-defined
    structure, to be used as a unique identifier for the reference symbol
    being created.

comp_func_ptr

 a pointer to a user-defined function that compares
    two blobs of user data (using whatever data structure was used for
    symbol_ptr_in).

ref_symbol_out_ptr

 pointer to a variable, passed in by the user,
    in which a handle to the reference symbol being created will be placed.