IDL defines two template types not found in C and C++: sequences and strings. A sequence is a one-dimensional array with two characteristics: a maximum size (specified at compile time) and a length (determined at run time). Sequences permit passing unbounded arrays between objects. Sequences are specified as follows:
sequence < simple-type [, positive-integer-const] >
where "simple-type" specifies any valid IDL type, and the optional "positive-integer-const" is a constant expression that specifies the maximum size of the sequence (as a positive integer).
Note: The "simple-type" cannot have a '*' directly in the sequence statement. Instead, a typedef for the pointer type must be used. For example, instead of:
typedef sequence<long *> seq_longptr; // Error: '*' not allowed.
use:
typedef long * longptr; typedef sequence<longptr> seq_longptr; // Ok.
In SOM's C and C++ bindings, sequences are mapped onto structs with the following members:
unsigned long _maximum;
unsigned long _length;
simple-type *_buffer;
where "simple-type" is the specified type of the sequence. For example, the IDL declaration
typedef sequence<long, 10> vec10;
results in the following C struct:
#ifndef _IDL_SEQUENCE_long_defined
#define _IDL_SEQUENCE_long_defined
typedef struct {
unsigned long _maximum;
unsigned long _length;
long *_buffer;
} _IDL_SEQUENCE_long;
#endif /* _IDL_SEQUENCE_long_defined */
typedef _IDL_SEQUENCE_long vec10;
and an instance of this type is declared as follows:
vec10 v = {10L, 0L, (long *)NULL};
The "_maximum" member designates the actual size of storage allocated for the sequence, and the "_length" member designates the number of values contained in the "_buffer" member. For bounded sequences, it is an error to set the "_length" or "_maximum" member to a value larger than the specified bound of the sequence.
Before a sequence is passed as the value of an "in" or "inout" method parameter, the "_buffer" member must point to an array of elements of the appropriate type, and the "_length" member must contain the number of elements to be passed. (If the parameter is "inout" and the sequence is unbounded, the "_maximum" member must also be set to the actual size of the array. Upon return, "_length" will contain the number of values copied into "_buffer", which must be less than "_maximum".) When a sequence is passed as an "out" method parameter or received as the return value, the method procedure allocates storage for "_buffer" as needed, the "_length" member contains the number of elements returned, and the "_maximum" member contains the number of elements allocated. (The client is responsible for subsequently freeing the memory pointed to by "_buffer".)
C and C++ programs using SOM's language bindings can refer to sequence types as:
_IDL_SEQUENCE_type
where "type" is the effective type of the sequence members. For example, the IDL type sequence<long,10> is referred to in a C/C++ program by the type name _IDL_SEQUENCE_long. If longint is defined via a typedef to be type long, then the IDL type sequence<longint,10> is also referred to by the type name _IDL_SEQUENCE_long.
If the typedef is for a pointer type, then the effective type is the name of the pointer type. For example, the following statements define a C/C++ type _IDL_SEQUENCE_longptr and not _IDL_SEQUENCE_long:
typedef long * longptr; typedef sequence<longptr> seq_longptr;
A string is similar to a sequence of type char. It can contain all possible 8-bit quantities except NULL. Strings are specified as follows:
string [ < positive-integer-const > ]
where the optional "positive-integer-const" is a constant expression that specifies the maximum size of the string (as a positive integer, which does not include the extra byte to hold a NULL as required in C/C++). In SOM's C and C++ bindings, strings are mapped onto zero-byte terminated character arrays. The length of the string is encoded by the position of the zero-byte. For example, the following IDL declaration:
typedef string<10> foo;
is converted to the following C/C++ typedef:
typedef char *foo;
A variable of this type is then declared as follows:
foo s = (char *) NULL;
C and C++ programs using SOM's language bindings can refer to string types by the type name string.
When an unbounded string is passed as the value of an "inout" method parameter, the returned value is constrained to be no longer than the input value. Hence, using unbounded strings as "inout" parameters is not advised.