SEDRIS Reference Manual
APPENDIX B - LEVEL 1 READ and WRITE API
Functions
SE AllocDataTableData
extern SE_Status_Code
SE_AllocDataTableData
(
constSE_Data_Table_Sub_Extent *extents_ptr, (notes)
SE_Integer_Positive element_count, (notes)
SE_Integer_Unsigned *byte_count_out_ptr, (notes)
SE_Property_Data_Value **data_out_ptr (notes)
);

Definition

Allocates memory for a <Data Table> instance, where the memory is organized like that retrieved with SE_GetDataTable(). This function is provided to support applications that intend to make an "application-owned" copy of the <Data Table> cell data, as well as data provider applications.

Memory allocated by SE_AllocDataTableData() should be freed in 2 stages.

  1. Call SE_FreeDataTableDataStrings() to free any strings within the data (these are allocated by SE_GetDataTable()).
  2. Call SE_FreeDataTableData().


Returns

SE_STAT_CODE_SUCCESS and
  1. a block of memory is allocated to hold the specified subtable of the given extents,
  2. a pointer to that block is copied into *data_out_ptr, and
  3. * byte_count_out_ptr is set to the number of bytes allocated to that block,
if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER and the output parameter values remain unaltered, if
  1. extents_ptr is NULL,
  2. element_count is zero (0),
  3. byte_count_out_ptr is NULL, or
  4. data_out_ptr is NULL.
SE_STAT_CODE_OUT_OF_MEMORY and data_out_ptr is set to NULL and * byte_count_out_ptr is set to zero, if memory allocation failed.
SE_STAT_CODE_FAILURE and the output parameters are set as for SE_STAT_CODE_OUT_OF_MEMORY, if *extents_ptr is invalid.

Parameters Notes


extents_ptr

 specifies the cells requested by the user
    (used to determine the number of cells to be allocated)

element_count

 the number of elements per cell to allocate

byte_count_out_ptr

 pointer to a variable in the user's memory space
    that will be set to the number of bytes used to store the
    specified subtable of the specified <Data Table>.

data_out_ptr

 pointer to a pointer to a block of memory allocated by
    this function to hold the <Data Table>. Freeing this block
    of memory is the caller's (i.e., ultimately the user's)
    responsibility.

Prev: SE_AddObjectToAggregate. Next: SE_AllocElementOfDataTableData. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™