OMret_str_array

OMret_str_array_val

Synopsis

char *OMret_str_array_val(
OMobj_id object_id,
int index,
char *buffer,
int buffer_size );

Description

OMret_str_array_val returns a string from an object that defines an array of strings. It is an easier alternative to using the OMget_str_array_val routine but provides access to the same value. AVS/Express currently only supports one-dimensional arrays of strings.

This routine is used in one of two modes:

• The string value is allocated with malloc and must be freed by the user

• The memory to store the string is supplied by the caller. If the string is too large to fit, it is truncated.

Arguments

object_id

The object id of an object that has a string value.

index

The index into the array of the desired string. This value should be between 0 and one less than the value provided by the routine OMget_array_size.

buffer

If the value is NULL (or if the buffer_size parameter is 0) space is allocated for the string. If this parameter is not NULL (and the buffer_size argument is greater than 0), this argument specifies a pointer to memory in which to store the string. This pointer is returned by the function in this case.

buffer_size

Specifies the size of the buffer argument. If this argument is 0, the buffer argument is ignored.

Returned value

A pointer to a NULL terminated string containing the specified string in the array of strings is returned. This value should be freed using the C routine free if the buffer argument is NULL or if buffer_size is 0.