Function Name: Create Reference Symbol From UInt32

Definition

Creates a reference symbol from an SE_UINT32 passed in by the user.

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. 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_CreateReferenceSymbolFromUInt32() using the same SE_UINT32.

Returns

SE_NULL_REQUIRED_PARAMETER - and no changes are made, if 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_uint32_in

 an SE_UINT32, to be used as a unique identifier
    for the reference symbol being created.

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.