Describe interface

This method returns a sequence of descriptions of the objects contained within a specified Container object of the Interface Repository.

Syntax

Container                          receiver;
Environment                       *env;
InterfaceName                      limit_type;
boolean                            exclude_inherited;
long                               max_returned_objs;
sequence <ContainerDescription>    rc;

rc = describe_contents(receiver, env, limit_type, exclude_inherited, max_returned_objs);

Parameters

receiver (Container)

A pointer to a Container object whose contained object descriptions are needed.

env (Environment *)

A pointer to the Environment structure for the caller.

limit_type (InterfaceName)

The name of one interface type (see the valid list above) or "all", to specify what type of objects the describe_contents method should return.

exclude_inherited (boolean)

A boolean value: TRUE to exclude any inherited objects, or FALSE to include all objects.

max_returned_objs (long)

A long integer indicating the maximum number of objects to be returned by the method, or -1 to indicate no limit is set.

Returns

rc (sequence <ContainerDescription>)

Returns a sequence of ContainerDescription structures, one for each object contained within the specified Container object. Each ContainerDescription structure has a "contained_object" field, which points to the contained object, as well as "name" and "value" fields, which are the result of the describe method.

Remarks

The describe_contents method combines the operations of the contents method and the describe method. That is, for each object returned by the contents operation, the description of the object is returned by invoking its describe operation. Each object represents a component of an IDL interface (class) definition maintained within the Interface Repository.

If the "limit_type" is set to "all", objects of all interface types are returned; otherwise, only objects of the requested interface type are returned. Valid values for InterfaceName are limited to the following set: {"AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef", "ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"}

If "exclude_inherited" is set to TRUE, any inherited objects will not be returned.

The "max_returned_objs" argument is used to limit the number of objects that can be returned. If "max_returned_objs" is set to -1, the results for all contained objects will be returned.

When finished using the sequence returned by this method, the client code is responsible for freeing the "value._value" field in each description, releasing each of the objects in the sequence, and freeing the sequence buffer. In C, this can be accomplished as follows:

if (seq._length) {
    long i;
    for (i=0; i <seq._length;i++) {
        if (seq._buffer[i].value._value)
                                    /* Release each description */
            SOMFree (seq._buffer[i].value._value);
        SOMObject_somFree (seq._buffer[i].contained_object);
                                      /* Release each object */
    }
    SOMFree (seq._buffer);            /* Release the buffer  */
}

Original Class

Container

Example Code

#include <containr.h>

...

Container anObj;
Environment *ev;
sequence(ContainerDescription) sc;
long i;

...

sc = Container_describe_contents (anObj, ev, "all", FALSE, -1L);
printf ("%s defines or inherits the following objects:\n",
    SOMObject_somIsA (anObj, _Contained) ?
        Contained__get_name ((Contained) anObj, ev) :
        "The Interface Repository");
for (i=0; i
     printf ("\t%s\n", sc._buffer[i].name);
     if (sc._buffer[i].value._value)
         SOMFree (sc._buffer[i].value._value);
     SOMObject_somFree (sc._buffer[i].contained_object);
}
if (sc._length)
    SOMFree (sc._buffer);
else
    printf ("\t[none]\n");

Related Functions

• contents
• describe
• lookup_name