11.5.3 Event Stimuli and Attributes

char *get_stim_value(Ptr values, short which);
 

Ptr values; In - a set of stimulus values, as passed in from the IMSB to the ODEV via the OAlloc message.

short which; In - which stimulus value to get

This function returns a string representation of a stimulus value for a stimulus to be allocated with an OAlloc ODEV message. The values parameter should be considered a list of stimulus values in some IMSB internal format. The list elements are numbered starting with 0.

short get_attribs(Ptr attribs_source, short which, char *attribute, char *buffer);
 

Ptr attribs_source; In - source for attributes, passed in to OAlloc message as attribRef.

short which; In - which stimulus value to get the attribute for.

char *attribute; In - attribute name to look for.

char *buffer; Out - buffer in which to return the contents of the attribute.

This function takes an attributes source passed to an ODEV from the IMSB via the attribRef parameter of the OAlloc message, and tries to find the named attribute, and write its contents into buffer.

If the attribute is found get_attribs() will return TRUE and write the entire contents of the attribute into buffer. Buffer must be at least 256 bytes. If the attribute is not found, get_attribs() will return FALSE.

If the event being allocated has multiple stimuli, pass in which stimulus value to get attribs for in the which parameter. They are numbered starting with 0. Use 0 for events with just one stimulus.

short get_attribs_and_info(Ptr attribs_source, short which, char *lookFor, Ptr *subValues, Ptr *subAttribRef);
 

This function works much like get_attribs() above, except that instead of concatenating the content of the attribute into a buffer, it generates a new set of values in subValues, and a new set of attributes in subAttribRef, which can then be passed to get_stim_value() and get_attribs(), respectively, to get the tokens and sub-attribues of the attribute selected using attribs_source, which, and lookFor.

If *subValues and *subAttribRef are NULL, they will be initialized with new lists, otherwise they are assumed to be properly initialized lists and will be cleared and refilled. Thus they may be reused indefinitely by passing in NULL values on the first call to get_attribs_and_info() and then simply passing the same values back to it on subsequent calls to get new lists.

When the ODEV is finished using subValues and subAttribs, it must free them by passing them to done_with_stim_values() and done_with_source_list(), respectively.

Ptr append_value_to_list(Ptr orig_values, short which, Ptr new_value_list);
 

This function takes value from a list of stimulus values as passed in to OAlloc and appends it to a new list. If new_value_list is NULL, a new list will be created and passed back.

This function is useful for ODEVs that create stimuli that are made up of sub-stimuli of other types. The ODEV Manager routine AllocODEVItem() requires a list of stimulus values, so an ODEV which calls it should create the list using this routine.

New value lists created with this function must be freed with done_with_stim_value().

Ptr append_source_to_list(Ptr orig_sources, short which, Ptr new_source_list);
 

Like append_value_to_list except with attribute sources.

void done_with_stim_values(Ptr values);
 

This function frees the internal structures in an attribute source list.

DON'T call done_with_source_list on a list passed in to your ODEV by the builder. Only use it for lists you create by calls to get_attribs_and_info and append_value_to_list.

void done_with_source_list(Ptr sources);
 

This function can be called by the AttribAlloc procedure in an ODEV. It frees the internal structures in an attribute source list.

DON'T call done_with_source_list on a list passed in to your ODEV by the builder. Only use it for lists you create by calls to get_attribs_and_info and append_source_to_list.