There are two types of public objects: service-generated objects and client-generated objects. The distinguished name object described in the previous topic is a client-generated public object because an application program (the client) created the data structure. As the creator of the public object, it is the responsibility of the application program to manage the memory resources allocated for it.
Service-generated public objects are created by the XOM service. Service-generated public objects may be generated as a result of an XOM request. An XOM API function, such as om_get( ), converts a private object into a service-generated public object. This is necessary because XDS may return a pointer to data in private format that can only be interpreted by XOM functions such as om_get( ).
For example, the following figure shows how the read request described in the previous example returns a pointer to an encoded data structure stored in result. This encoded data structure, referred to as a private object (described in the next topic) is one of the input parameters to om_get( ). The om_get( ) function provides a pointer to a public object (in this case, entry) as an output parameter. The public object is a data structure that has been interpreted by om_get( ) and is accessible by the application program (the client). The information requested by the application in the read request is contained in the output parameter entry.
Client-Generated and Service-Generated Objects
The application program is responsible for managing the storage (memory) for the service-generated public object. This is an important point because it requires that the application issue a series of om_delete( ) calls to delete the service-generated public object from memory. Because the data structures involved with directory service requests can be very large (often involving large subtrees of the DIT), it is imperative that the application programmer build into any application program the efficient management of memory resources.
The following code fragment from example.h demonstrates how storage for public and private objects is released by using a series of om_delete( ) function calls after they are no longer needed by the application program. The data (a list of phone numbers associated with the name Peter Piper required by the application program) has already been extracted by using a series of om_get( ) function calls, as follows:
/* We can now safely release all the private objects
* and the public objects we no longer need
*/
CHECK_OM_CALL(om_delete(session));
CHECK_OM_CALL(om_delete(result));
CHECK_OM_CALL(om_delete(entry));
CHECK_OM_CALL(om_delete(attributes));
CHECK_DS_CALL(ds_shutdown(workspace));