Function Name: Get Fields

Definition

Retrieves a pointer to the field data of an object. The SE_FIELDS data structure is a union of all the different field structures from all the different classes. This all-inclusive union and the structures that compose it are defined in the "sedris.h" file. The memory required to store the fields structure well as any memory referenced by pointers within the fields structure are allocated within a store that is provided by the caller. The returned data is valid until the store is used in another API call, or the store is freed with the SE_FreeStore() function. See the comments for the function SE_CreateStore() for details on the function and behavior of stores.

WARNING: Because some of the fields contained in the union portion of the SE_FIELDS structure are pointers to dynamically allocated memory, it is HIGHLY INADVISABLE to use a member-wise structure copy in order to duplicate the SE_FIELDS structure. In order to reliably duplicate this data, developers should use the SE_CloneFields() function.

Returns

SE_SUCCESS - if valid parameters were passed in. In this case, memory is allocated within the store associated with store_in to hold *fields_out_ptr, as well as to hold any dynamically allocated data within the SE_FIELDS structure, and appropriate values are then copied into *fields_out_ptr.

SE_NULL_REQUIRED_PARAMETER - if fields_out_ptr was NULL. In this case, *fields_out_ptr is left unaltered.

SE_INVALID_OR_NULL_OBJECT - if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object. In this case, *fields_out_ptr is set to NULL.

SE_UNRESOLVED_OBJECT - if object_in is an unresolved object (see SE_OBJECT's comments for details on how this condition occurs). In this case, *fields_out_ptr is set to NULL.

SE_INVALID_OR_NULL_STORE - if store_in is not a handle to a valid SE_STORE created by SE_CreateStore(). In this case, *fields_out_ptr is set to NULL.

SE_OUT_OF_MEMORY - if the API could not allocate the memory for the SE_FIELDS structure or any dynamically allocate memory it should refer to. In this case, *fields_out_ptr is set to NULL.

SE_FAILURE - and *fields_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


extern SE_STATUS_CODE_ENUM
SE_GetFields
(
SE_OBJECT object_in, (notes)
SE_STORE store_in, (notes)
SE_FIELDS_PTR *fields_out_ptr (notes)
);

Parameters Notes

object_in

 the object whose fields are desired.

store_in

 the store to be used to allocate the SE_FIELDS structure as
    well as any dynamically allocated data within it.

fields_out_ptr

 a pointer to the variable in the user's memory
    where an SE_FIELDS_PTR will be copied.  This SE_FIELDS_PTR
    will point to the fields of the object, in the API's memory space
    associates with store_in.  Do *not* free any data pointed to by this
    pointer.  Do *not* free this pointer.  Instead, call SE_FreeStore()
    for the store_in, or use the store_in in another function that returns
    data.
Prev: Get Element Of Data Table. Next: Get ID For Object. Up:Index.