SE GetFields

SEDRIS Reference Manual APPENDIX A - LEVEL 0 READ and WRITE API Functions SE GetFields

extern SE_Status_Code
SE_GetFields
(
SE_Object		object_in,	(notes)
SE_Store		store_in,	(notes)
SE_FIELDS_PTR	*	fields_out_ptr	(notes)
);

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_STAT_CODE_SUCCESS and

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,
if valid parameters were passed in and all operations succeeded.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER and *fields_out_ptr is left unaltered, if fields_out_ptr was NULL.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and *fields_out_ptr is set to NULL, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object.

SE_STAT_CODE_UNRESOLVED_OBJECT and *fields_out_ptr is set to NULL, if object_in is an unresolved object (see SE_Object's comments for details on how this condition occurs).

SE_STAT_CODE_INVALID_OR_NULL_STORE and *fields_out_ptr is set to NULL, if store_in is not a handle to a valid SE_Store created by SE_CreateStore().

SE_STAT_CODE_OUT_OF_MEMORY and *fields_out_ptr is set to NULL, if the API could not allocate the memory for the SE_Fields structure or any dynamically allocate memory it should refer to.

SE_STAT_CODE_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.

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.

SE_STAT_CODE_SUCCESS	and 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, if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *fields_out_ptr is left unaltered, if fields_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *fields_out_ptr is set to NULL, if object_in is not a handle to a valid, active (i.e., unfreed) SEDRIS object.
SE_STAT_CODE_UNRESOLVED_OBJECT	and *fields_out_ptr is set to NULL, if object_in is an unresolved object (see SE_Object's comments for details on how this condition occurs).
SE_STAT_CODE_INVALID_OR_NULL_STORE	and *fields_out_ptr is set to NULL, if store_in is not a handle to a valid SE_Store created by SE_CreateStore().
SE_STAT_CODE_OUT_OF_MEMORY	and *fields_out_ptr is set to NULL, if the API could not allocate the memory for the SE_Fields structure or any dynamically allocate memory it should refer to.
SE_STAT_CODE_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.