Ets_Obj_Attr_Get_Sized()
Abstract
Gets the value of a given ETS object’s attribute, using a sized buffer.
Syntax
Ets_Obj_Attr_Get_Sized (obj_hndl, attr_name, size_ptr, val_ptr)
| Argument | Type | Description |
|---|---|---|
obj_hndl |
EtsT_Obj_Handle |
Handle of object of interest. |
attr_name |
const char * |
Name of attribute of interest. |
size_ptr |
size_t * |
On call, the size of val_ptr.On return, the actual size of the attribute value (for strings, this includes the terminating null). |
val_ptr |
void * |
Buffer to be filled with the attribute value. |
Return Type
EtsT_Compcode
EtsC_Compcode_Success if the attribute exists and is valid. EtsC_Compcode_Failure otherwise.
Header
ets_api_obj.h
Details
This function is similar to Ets_Obj_Attr_Get(), except that it has a size argument and will not overrun the val_ptr buffer when returning the attribute value. (If size_ptr is NULL, the function acts identically to Ets_Obj_Attr_Get().)
For string attribute values that are larger than val_ptr, a truncated string is returned. For other data types, if the attribute value is too big, val_ptr remains unchanged.
The size_ptr argument allows you to detect buffer-size problems and reallocate the buffer to hold the requested attribute value. For example:
{
char buffer [1024];
char * buffer_ptr;
size_t size;
size_t buf_size;
buffer_ptr = buffer;
size = buf_size = 1024;
status = Ets_Obj_Attr_Get_Sized (obj_h, attr_name, &size, buffer_ptr);
if ((status == EtsC_Compcode_Failure) && (buf_size < size))
{
// size includes the terminating null
buffer_ptr = malloc (size);
status = Ets_Obj_Attr_Get_Sized (obj_h, attr_name, &size, buffer_ptr);
}
if (status == EtsC_Compcode_Failure)
{
// Error.
return;
}
// Use the value.
if (buffer_ptr != buffer)
free (buffer_ptr);
}