SE AllocElementOfDataTableData

SEDRIS Reference Manual APPENDIX B - LEVEL 1 READ and WRITE API Functions SE AllocElementOfDataTableData

extern SE_Status_Code
SE_AllocElementOfDataTableData
(
	SE_Object		data_table,	(notes)
const	SE_Data_Table_Sub_Extent	*	extents_ptr,	(notes)
	SE_Integer_Positive		table_prop_descript_number,	(notes)
	SE_Integer_Unsigned	*	byte_count_out_ptr,	(notes)
	SE_Property_Data_Value_Ptr	*	data_out_ptr	(notes)
);

Definition

Allocates memory for a <Data Table> like that retrieved with SE_GetElementOfDataTable(). This function is provided to support applications that must make an "application-owned" copy of a <Data Table>'s data.

Memory allocated by SE_AllocElementOfDataTableData() should be freed in 2 stages:

Call SE_FreeElementOfDataTableDataStrings() to free any strings within the data (these are allocated by SE_GetElementOfDataTable()).
Call SE_FreeElementOfDataTableData().

Returns

SE_STAT_CODE_SUCCESS and memory is allocated and the output parameter values are set appropriately, if valid parameters were passed in and allocation succeeded.

SE_STAT_CODE_NULL_REQUIRED_PARAMETER the output parameter values are left unaltered, if

extents_ptr is NULL,

table_prop_descript_number is zero (0),

byte_count_out_ptr is NULL, or

data_out_ptr is NULL.

SE_STAT_CODE_INVALID_OR_NULL_OBJECT and * byte_count_out_ptr is set to zero (0) and data_out_ptr is left unaltered, if data_table is not a handle to a valid, active (i.e., unfreed) <Data Table> instance.

SE_STAT_CODE_OUT_OF_MEMORY and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if memory allocation failed.

SE_STAT_CODE_FAILURE and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if

table_prop_descript_number is not valid for data_table's signature, or

* extents_ptr is invalid.

Parameters Notes

data_table

 the <Data Table> being allocated; needed (with
    table_prop_descript_number) to find the type of the element requested.

extents_ptr

 indicates the cells requested by the user
    (which 'region' of data_table to return).

table_prop_descript_number

 an index into the ordered list of
    <Table Property Descriptions> aggregated by data_table.

byte_count_out_ptr

 pointer to a variable in the user's memory space
    where the number of bytes used to store the specified sub-table
    of data_table will be stored.

data_out_ptr

 a pointer to a structure which will be set so
    that it contains a valid array of the correct size for
    the correct data type.

SE_STAT_CODE_SUCCESS	and memory is allocated and the output parameter values are set appropriately, if valid parameters were passed in and allocation succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	the output parameter values are left unaltered, if extents_ptr is NULL, table_prop_descript_number is zero (0), byte_count_out_ptr is NULL, or data_out_ptr is NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and * byte_count_out_ptr is set to zero (0) and data_out_ptr is left unaltered, if data_table is not a handle to a valid, active (i.e., unfreed) <Data Table> instance.
SE_STAT_CODE_OUT_OF_MEMORY	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if memory allocation failed.
SE_STAT_CODE_FAILURE	and the output parameters are set as for SE_STAT_CODE_INVALID_OR_NULL_OBJECT, if table_prop_descript_number is not valid for data_table's signature, or * extents_ptr is invalid.