Function Name: Free Reference Symbol

Definition

Frees the memory directly associated with the specified reference symbol, if any, which was allocated by this API either

1. during an earlier call to a function that retrieved this reference symbol, e.g. SE_GetReferenceSymbol(),
2. during an earlier call to a function that created this reference symbol, e.g. SE_CreateReferenceSymbol(), SE_CreateReferenceSymbolFromUInt32()

Note that if a reference symbol has been retrieved more than once, then SE_FreeReferenceSymbol() will not actually release the memory for that reference symbol until the last reference to the reference symbol is freed; i.e., you must call SE_FreeReferenceSymbol() for a reference symbol as many times as you have retrieved that reference symbol with an API function.

Returns

1. While the actual reference symbol is not destroyed until its reference count becomes zero, this handle is no longer valid once SE_FreeReferenceSymbol() has been called.
2. Once the final handle to a reference symbol is freed, the reference symbol is destroyed.
3. If a reference symbol is destroyed before being assigned to an object, then any symbolic relationships created with that reference symbol will cease to exist, since they can never be resolved at that point.

SE_INVALID_OR_NULL_REFERENCE_SYMBOL - and no changes are made, if ref_symbol is not a handle to a valid, active (i.e., not freed) SE_REFERENCE_SYMBOL created by one of the create-reference-symbol functions.

SE_FAILURE - and no changes are made, if

1. ref_symbol does not have an assigned object, but has been used to create symbolic association and/or composition relationships.
2. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

ref_symbol

 the reference symbol to be freed.