Object Services API

Solstice Enterprise Manager 4.1 C++ API Reference

Chapter 9

Object Services API

The Object Services API, or object development tools (ODT), allow developers who implement object classes to send CMIS requests in an ODT application. This API is useful for developing manager and agent network management applications. Developers can use it to customize behaviors for the GDMO classes, rather than accept the default behaviors.

The ODT do not allow users to extend or override any existing services or object behavior within the MIS, such as the NerveCenter or Event Service.

This chapter comprises the following topics:

Section 9.1 Operational Flow
Section 9.2 Service Request Function Parameters
Section 9.3 Service Response Callback Function Parameters
Section 9.4 Services Interface Descriptions and Examples
Section 9.5 Supporting Functions for Example Code

9.1 Operational Flow

The Object Services API provides a set of programming interfaces for use by an application developer when writing object behavior software. An application developer is not required to use the services functions. However, these functions make it easier to perform some common tasks related to inter-object communication from within.

The operational flow of a request issued using the Object Services API is based on the PMI Message and MessageSAP C++ classes on object behavior. The Message and MessageSAP C++ classes are used throughout the MIS and are also the basis for the low level PMI interface. The Object Services API hides the Message classes and the MessageSAP classes used by the low level PMI. The classes are hidden primarily to simplify this API and also for the following reasons:

Most messages sent through this API can use a number of default values. The Object Services API function calls provide default values for all parameters not specifically required for a particular operation.
Only a single well defined MessageSAP is required for these functions. The services function calls involve communication between the object access module (OAM) and the message routing module (MRM). The OAM contains both user-developed object behavior code and the generated object behavior code. The MRM handles routing for all message requests and responses.

9.2 Service Request Function Parameters

TABLE 9-1 provides detailed descriptions of the Service Request Function parameters defined for the Object Services API.

TABLE 9-1 Service Request Function Parameters
Parameter Description

const Asn1Value oc
Instance of the Asn1Value C++ class that contains an Object Identifier (OID) for a managed object class. For each of the Object Service API request functions, except the send_event_req function, this parameter can be the OID for Actual Class. Actual Class is an ISO defined OID that matches the class of any managed object on which an operation is performed. The oc parameter is used as follows:
Single Object Selection (Base Object Only Scoping):
The OID specifies the object class of the managed object from which attribute values are retrieved, using the Get operation.
Multiple Object Selection Using Scoping and Filtering:
The OID parameter specifies the object class of the managed object used as the starting point for the selection of managed objects from which attribute values are retrieved using the Get operation.

The CMIS and CMIP specifications refer to this parameter as either the base object class or managed object class, depending on the type of operation being performed.

const Asn1Value oi
Instance of the Asn1Value C++ class that contains either a distinguished name (context specific 2) or a local distinguished name (context specific 4) for a managed object instance. The oi parameter is used as follows:
Single Object Selection (Base Object Only Scoping):
The oi parameter specifies the name of the managed object instance from which the request operation is performed.
Multiple Object Selection Using Scoping and Filtering:
The oi parameter specifies the name of the managed object instance to be used as the starting point for the selection of managed objects on which the request operation is performed.

The CMIS and CMIP specifications refer to this parameter as either the base object class or managed object instance, depending on the type of operation being performed. Specify this parameter as a null Asn1Value (Asn1Value()) if a managed object instance name is specified by the superior_oi parameter.

const Callback cb
Instance of the Callback C++ class, which can contain two pointers. The first is a pointer of a callback function to be invoked when a response to an operation is received. The second is a pointer to application developer-specified data (commonly referred to as user data) to be passed to the callback function when it is invoked. The user data pointer is always optional. The cb parameter is required, or optional for service request functions that support it. If specified, a confirmed service request is issued. If not specified, an unconfirmed service request is issued.

const Asn1Value attr_list
Instance of the Asn1Value C++ class that contains a set of OIDs for attributes. Attributes are normally members of the object class specified by the oc parameter or members of the class of an object instance identified within a scoped operation.

const Asn1Value modify_list
A set of attribute ID and attribute value pairs that specify for a send_set_req service request operation which attributes are to be modified and new values for those attributes. The modify_list parameter is an instance of the Ans1Value C++ class and is typically a sequence of an OID that identifies an attribute, followed by a value for the attribute.

const Asn1Value action_type
Instance of the Asn1Value C++ class that contains an object identifier (OID) that specifies the type of action generated by the send_action_req function.

const Asn1Value action_info
Instance of the Asn1Value C++ class that contains any event information associated with the type of action specified by the action_type parameter. The action_info parameter typically contains a sequence or set of ASN.1-defined values. The action_info parameter is optional for the send_action_req service function but must be present if a WITH INFORMATION SYNTAX construct is specified as part of the GDMO definition for the action type specified by the action_type parameter.

const Asn1Value attr_value_list
A set of attribute ID and attribute value pairs that specify the attributes assigned new values by a send_create_req service request operation. The values specified in the send_create_req service function override the corresponding attributes from the reference object (if specified using the reference_oi parameter) or from the default value specified in the GDMO definition for the managed object class. The attr_value_list parameter is an instance of the Asn1Value C++ class and is typically a sequence of an OID that identifies an attribute, followed by a value for the attribute. The attr_value_list parameter is an optional parameter for the send_create_req service request, although values must be specified for all mandatory attributes defined in the GDMO managed object class definition for which an instance is being created. In other words, the mandatory attribute values must be specified in the GDMO definition in a default value clause, supplied from a reference object, or else specified in the attr_value_list.

const Asn1Value superior_oi
An instance of the Asn1Value C++ class, this parameter is used only with the send_create_req function. The parameter contains either a distinguished name (context specific 2) or a local distinguished name (context specific 4) for an existing managed object instance that is to be the superior--in the MIT--of the managed object instance created. This parameter should not be specified, or should be specified as a null Asn1Value, if a managed object instance name is specified by the oi parameter.

const Asn1Value reference_oi
An instance of the Asn1Value C++ class, this parameter is used only with the send_create_req function. It contains either a distinguished name (context specific 2) or a local distinguished name (context specific 4) for an existing managed object instance that is of the same class as the managed object instance created. Attribute values associated with the managed object specified by the reference_oi parameter become default values for those attributes not specified by the attr_value_list parameter of the send_create_req function.

const Asn1Value event_type
Instance of the Asn1Value C++ class that contains an OID specifying the type of notification to be generated by the send_event_req function.

const Asn1Value event_info
An Asn1Value C++ class that contains any event information associated with the type of notification specified by the event_type parameter. This parameter typically contains a sequence or set of ASN.1-defined values and is optional for the send_event_req service function. It must be present if a WITH INFORMATION SYNTAX construct is specified as part of the GDMO definition for the notification type specified by the event_type parameter.

const Asn1Value event_time
Instance of the Asn1Value C++ class containing a value for the time at which a notification is generated.

MessId id
Identifier that uniquely identifies a service request operation. If specified, the value for this parameter is generated and set by the service request function.

const MessScope scope
Specifies the type of scoping used for a service request operation. The possible types of scoping are BASE_OBJECT, NTH_LEVEL,BASE-TO-NTH_Level, and ALL_LEVELS. It is optional for all service request functions that support it. If not specified, it defaults to BASE_OBJECT.

const Asn1Value filter
Instance of the Asn1Value C++ class that contains a CMISFilter (refer to the ISO DMI for a definition of the CMIS filter). All objects selected by the scoping parameter are tested against a filter. The service request operation is performed only on those objects that pass the filter test. It is an optional parameter for all service request functions that support it. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.

const MessSync sync
Specifies the type of synchronization used for a service request operation. It is an enumerated type and can take on the value ATOMIC or BEST_EFFORT. It is an optional parameter for all service request functions that support it. If not specified, it defaults to BEST_EFFORT. The use of ATOMIC is rarely supported by remote objects.

const Asn1Value access
A reserved parameter not normally specified. The access parameter defines the access control that objects selected for a service request operation must pass. The service request operation is not performed by any managed object that does not pass the access control.

9.3 Service Response Callback Function Parameters

TABLE 9-2 describes the Service Response Callback Function Parameters.

TABLE 9-2 Service Response Callback Function Parameters
Parameter Description

Ptr userdata
Optional parameter intended for all service response callback functions. It is a void * pointer to data specified by the application developer in the callback parameter of a service request function.

Ptr message
Mandatory parameter for all service response callback functions. It is a void * pointer to the message generated in response to a service request function.

9.4 Services Interface Descriptions and Examples

The following service request functions and service indication functions are supported by the Object Services API. In general, the services interfaces specified here contain both mandatory and optional parameters. Mandatory parameters are typically passed by reference. Optional parameters are typically passed either by value or by a pointer to a value. Mandatory parameters are ordered prior to the optional parameters for each function. Optional parameters for each function are ordered by placing the most-likely-to-be-specified optional parameters first.

This section includes the following functions:

Get Request Service
Get Response Callback
Set Request Service
Set Response Callback
Action Request Service
Action Response Callback
Create Request Service
Create Response Callback
Delete Request Service
Delete Response Callback
Delete Response Callback Parameter Description
Event Report Request Service (Unconfirmed)
Event Report Response Callback

9.4.1 Get Request Service

Enables you to override GDMO restrictions that are related to managed object (MO) attribute getting.

The following subsections describe and provide examples of the Get Request Service.

9.4.1.1 Get Request Service

The rules for getting an MO's attributes are defined in the MO class definition in a GDMO document. The rules impose restrictions on getting attributes, and it is possible to override some of these restrictions when requesting the getting of an MO's attributes through the send_get_req() function. Specifically, the absence of a GET or GET-REPLACE modifier for an attribute is intended to have the effect of restricting the getting of an attribute by a management application.

To allow behavior internal to the MIS to override this restriction, this function is defined with a flags parameter. The relevant flag value is ReqMess::OVERRIDE_ATTR_CHECKS, which is defined in message.hh.

Note – In the case where a scope and filter are specified, the override capability only applies to the base object, and not to the scoped and filtered objects.
9.4.1.2 Interface Signature

Result send_get_req(
const Asn1Value &oc,
const Asn1Value &oi,
const Callback &cb, // Always confirmed
const Asn1Value attr_list = Asn1Value(),
// Default: Get all attributes
MessId *id =0,
const MessScope scope = MessScope(),
//Default: Base object only
const Asn1Value filter = Asn1Value(), //Default: Matches all
const MessSync sync = BEST_EFFORT,
const Asn1Value access = Asn1Value(),

Boolean sub_trans
); //Default: No access cntrl
9.4.1.3 send_get_request Parameter Descriptions

TABLE 9-3 describes the send_get_request parameters.

TABLE 9-3 send_get_request Parameters
Parameter Description Required/ Optional

const Asn1Value oc
Specifies the class of the base managed object.
Required

const Asn1Value oi
Distinguished name of local distinguished name for the base managed object.
Required

const Callback cb
Specifies the name of a callback function invoked when a response to the get request is received and can be used to specify user data that is passed to the callback function when it is invoked.
Required

const Asn1Value attr_list
List of attribute OIDs whose attribute values are to be returned in response to the get request operation. If not specified, all attributes defined for the managed object class are returned in the response.
Optional

MessId id
Provides a unique identifier for a particular Get request operation. If specified, the value for this parameter is generated and set by the send_get_req function.
Optional

const MessScope scope
Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.
Optional

const Asn1Value filter
Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.
Optional

const MessSync sync
Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.
Optional

Boolean sub_trans
Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.
Optional

const Asn1Value access
Reserved parameter that should not be used at this time.
Not available

9.4.1.4 send_get_request Examples
Get Request: Base Object Only

CODE EXAMPLE 9-1 Get Request: Base Object Only Example

Result

get_system_object_attributes(char *system_name)

{

Asn1Value actual_oc;

Asn1Value system_oi;

//******************************************

// (Confirmed) Get request

//******************************************

// Send a get request to an instance of the

// system managed object class. The system

// the request is sent to is identified by

// the system_name parameter.

VTRY {

// Encode oc OID. In this example, actualClass is used

// instead of the OID for the system managed object

// class.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(actual_oc.encode_oid(TAG_CONT(0),
Oid("2.9.3.4.3.42")));

// Encode the distinguished name for an instance of the

// system managed object class. Either the distinguished

// name form (TAG_CONT(2)) or the local distinguished name

// form (TAG_CONT(4)) can be used with the get operation.

// The distinguished name form is used in this example.

// The get_sys_dn function is included in Section 9.5.

TTRYRES(get_sys_dn(system_name, system_oi));

// In this example, all attributes from the system object class

// are retrieved. No attribute ID list is required.

// Send the get request (Always Confirmed). No user data is

// specified for the callback parameter. The get_req_cb function

// is included as part of the Object Services API examples.

objsvc_test.print("About to issue Get Request\n");

if (send_get_req(actual_oc, system_oi,

Callback(get_req_cb, 0)) != OK) {

objsvc_test.print("Error issuing Get Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued Get Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding Get Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
Get Request: Scoped Operation

CODE EXAMPLE 9-2 Get Request: Scoped Operation Example

Result

get_application_attributes(char *system_name)

{

Asn1Value actual_oc;

Asn1Value system_oi;

Asn1Value em_mis_rdn;

//************************************

// (Confirmed) Scoped get request

//************************************

// Get the emApplicationID, emApplicationType, and the

// emUserID attribute values for each application instance

// object under an emKernel object. The emKernel object

// is located under the system object in the MIT.

VTRY {

// Encode oc OID. In this example, actualClass is used

// instead of the OID for the system managed object

// class.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(actual_oc.encode_oid(TAG_CONT(0),
Oid("2.9.3.4.3.42")));

// Encode the distinguished name for an instance of the

// emKernel managed object class. Either the distinguished

// name form (TAG_CONT(2)) or the local distinguished name

// form (TAG_CONT(4)) can be used with the get operation.

// The distinguished name form is used in this example.

// The get_sys_dn and get_graphstr_rdn functions are included

// in Section 9.5.

TTRYRES(get_sys_dn(system_name, system_oi));

TTRYRES(get_graphstr_rdn(

"2.9.3.5.7.11","EM-MIS", em_mis_rdn));

TTRYRES(system_oi.add_component(em_mis_rdn));

// Encode the attribute list. The CMIP spec specifies

// TAG_CONT(12) as the tag for the attribute list.

Asn1Value attrlist;

Asn1Value enc_oid1, enc_oid2, enc_oid6;

Oid oid1("1.3.6.1.4.1.42.2.2.2.1.7.1"); // emApplicationID

Oid oid2("1.3.6.1.4.1.42.2.2.2.1.7.2"); // emApplicationType

Oid oid6("1.3.6.1.4.1.42.2.2.2.1.7.6"); // emUserID

TTRYRES(attrlist.start_construct(TAG_CONT(12)));

TTRYRES(enc_oid1.encode_oid(TAG_CONT(0), oid1));

TTRYRES(enc_oid2.encode_oid(TAG_CONT(0), oid2));

TTRYRES(enc_oid6.encode_oid(TAG_CONT(0), oid6));

TTRYRES(attrlist.add_component(enc_oid1));

TTRYRES(attrlist.add_component(enc_oid2));

TTRYRES(attrlist.add_component(enc_oid6));

// Send the scoped get request (Always Confirmed). No user data

// is specified for the callback parameter. The

// scoped_get_req_cb function is included as part of the

// Object Services API examples.

objsvc_test.print("About to issue Scoped Get Request\n");

if (send_get_req(actual_oc, system_oi,

Callback(scoped_get_req_cb, 0), attrlist,

0, MessScope(NTH_LEVEL, 1)) != OK) {

objsvc_test.print("Error issuing Scoped Get Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued Scoped Get Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding Get Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
9.4.2 Get Response Callback

The send_get_req service function requires a callback function. The name of the callback function provided by the application developer must match the name of the callback function specified in the Callback parameter of the send_get_req function.

9.4.2.1 Interface Signature
void user-provided-get-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to GetRes message
9.4.2.2 Get Response Callback Parameter Descriptions

TABLE 9-4 shows the Get response callback parameters.

TABLE 9-4 Get Response Callback Parameters
Parameter Description

userdata
A void * pointer to data specified by the application developer in the callback parameter of the send_get_req function.

message
A void * pointer to the GetRes message generated in response to the send_get_req function.

9.4.2.3 Get Response Callback Examples
Callback Function: Single Response (Base Object Only)

CODE EXAMPLE 9-3 Callback Function: Single Response

void

get_req_cb(Ptr, Ptr get_response_msg)

{

objsvc_test.print("Get Request callback\n");

Message *resp = (Message *)get_response_msg;

VTRY {

if ( resp->type() == GET_RES) {

GetRes *g_resp = (GetRes *)resp;

g_resp->print(objsvc_test);

// The Asn1Value decoding functions, including the

// member functions get_first_component and

// get_next_component can be used to examine the member data

// included in the response message at this point

// ...

}

else if ( resp->is_error() ) {

objsvc_test.print("Get response error received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

else {

objsvc_test.print(

"Unexpected or invalid response received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("Error processing response for Get\n");

resp->print(objsvc_error);

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
Callback Function: Multiple Responses (Scoped Operation)

CODE EXAMPLE 9-4 Callback Function: Multiple Responses

static int resp_count = 0;

static int err_count = 0;

static int unknown_count = 0;

void

scoped_get_req_cb(Ptr userdata, Ptr calldata)

{

objsvc_test.print("Scoped Get Request callback:");

Message *resp = (Message *)calldata;

VTRY {

if ( resp->type() == GET_RES) {

GetRes *sg_resp = (GetRes *)resp;

if (sg_resp->linked) {

objsvc_test.print("*** LINKED Response ***\n");

resp_count++;

sg_resp->print(objsvc_test);

// The Asn1Value decoding functions, including the

// member functions get_first_component and

// get_next_component can be used to examine the member

// data included in the response message here.

// ...

} else {

objsvc_test.print("**** Final Response ****\n");

sg_resp->print(objsvc_test);

objsvc_test.print("Valid: %d, Error: %d,Invalid: %d\n",

resp_count, err_count, unknown_count);

// Final response processing can be performed here. The

// final response message does not contain any attribute

// value data

// ...

}

}

else if ( resp->is_error() ) {

objsvc_test.print("Error Response\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

err_count++;

}

else {

objsvc_test.print("Invalid Message\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

unknown_count++;

}

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError processing response for Scoped Get\n");

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
9.4.3 Set Request Service

Enables you to override GDMO restrictions that are related to MO attribute setting.

This section describes the interface signature, send_set_request parameters, and provides an example of its use.

9.4.3.1 Set Request Service

The rules for setting an MO's attributes are defined in the MO class definition in a GDMO document. The rules impose restrictions on the setting of attributes, but it is possible to override some of these restrictions when requesting the setting of an MO's attributes through the send_set_req() function. Specifically, the absence of a REPLACE, GET-REPLACE, or ADD-REMOVE modifier for an attribute is intended to have the effect of restricting the setting of an attribute by a management application.

To allow behavior internal to the MIS to override this restriction, this function is defined with a flags parameter. The relevant flag value is ReqMess::OVERRIDE_ATTR_CHECKS, which is defined in message.hh.

Note – In the case where a scope and filter are specified the override capability only applies to the base object, and not to the scoped and filtered objects.
9.4.3.2 Interface Signature

CODE EXAMPLE 9-5 Set Request Interface Signature

const Asn1Value &oc,

const Asn1Value &oi,

const Asn1Value &modify_list,

const Callback cb = 0, // Default: Unconfirmed

MessId *id = 0,

const MessScope scope = MessScope(),
// Default: Is base object only

const Asn1Value filter = Asn1Value(), // Default: Matches all

const MessSync sync = BEST_EFFORT,

const Asn1Value access = Asn1Value(),

Boolean sub_trans); // Default: No access cntrl
9.4.3.3 send_set_request Parameter Descriptions

TABLE 9-5 provides descriptions of the send_set_request parameters.

TABLE 9-5 send_set_request Parameters
Parameter Description Required/ Optional

const Asn1Value oc
OID that specifies the class of the base managed object.
Required

const Asn1Value oi
Distinguished name or local distinguished name for the base managed object.
Required

const Ans1Value modify_list
List of attribute ID and attribute value pairs that specify which attributes are to be modified by the set request operation and what the new values are for the attributes.
Required

const Callback cb
Specifies the name of a callback function invoked when a response to the set request operation is received. Can also be used to specify user data passed to the callback function when it is invoked. If specified, a confirmed set request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed set request operation is issued and no response is generated.
Optional

MessId id
Provides a unique identifier for a particular set request operation. If specified, the value for this parameter is generated and set by the send_set_req function.
Optional

const MessScope scope
Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.
Optional

const Asn1Value filter
Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.
Optional

const MessSync sync
Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.
Optional

Boolean sub_trans
Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.
Optional

const Asn1Value access
This parameter is reserved at this time.
Not available
9.4.3.4 send_set_request Example

CODE EXAMPLE 9-6 send_set_request

Result

set_log_adminState(char *system_name)

{

Asn1Value actual_oc;

Asn1Value log_fdn;

Asn1Value log_rdn;

Asn1Value mod_list;

//******************************************

// Confirmed Set request

//******************************************

// Send a confirmed set request to an instance of the

// log managed object class. The log that

// the request is sent to is

// contained under the system identified by

// the system_name parameter.

VTRY {

// Encode oc OID. In this example, actualClass is used

// instead of the OID for the log managed object

// class.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(actual_oc.encode_oid(TAG_CONT(0),
Oid("2.9.3.4.3.42")));

// Encode the distinguished name for an instance of the

// log managed object class. The instance logId="AlarmLog"

// is used here. Either the distinguished name form

// (TAG_CONT(2)) or the local distinguished name form

// (TAG_CONT(4)) can be used with the set operation. The

// distinguished name form is used in this example.

// The get_sys_dn and get_graphstr_rdn functions are included

// in Section 9.5.

TTRYRES(get_sys_dn(system_name, log_fdn));

TTRYRES(get_graphstr_rdn(Oid("2.9.3.2.7.2"), "AlarmLog",
log_rdn));

TTRYRES(log_fdn.add_component(log_rdn));

// Encode the modification list for the set operation.

// The administrativeState of the log object is set to

// locked in this example.

// The CMIP spec specifies TAG_CONT(12) as the tag for

// the attribute modification list.

TTRYRES(modlist.start_construct(TAG_CONT(12)));

Asn1Value av;

TTRYRES(av.encode_enum(TAG_ENUM, 0)); // Set to LOCKED

Asn1Value set; //1 is unlocked

Asn1Value comp; //set the sequence of attr. ID and value pair

Oid oid("2.9.3.2.7.31"); // Set administrativeState

TTRYRES(set.start_construct(TAG_SEQ));

TTRYRES(comp.encode_oid(TAG_CONT(0), oid));

TTRYRES(set.add_component(comp));

TTRYRES(set.add_component(av));

TTRYRES(modlist.add_component(set));

// Send the confirmed set request. No user data is

// specified for the callback parameter. The set_req_cb function

// is included as part of the Object Services API examples.

oamsvc_test.print("About to issue Confirmed Set Request\n");

if (send_set_req(actual_oc, log_fdn, modlist,

Callback(set_req_cb, userdata)) != OK)

objsvc_test.print("Error issuing Confirmed Set Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued Confirmed Set Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding Set Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
9.4.4 Set Response Callback

This callback function is used only in conjunction with confirmed Set requests. The name of the callback function must match the name of the callback function specified in the callback parameter of the send_set_req function.
9.4.4.1 Interface Signature

void user-provided-set-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to SetRes message
9.4.4.2 Set Response Callback Parameter Description

TABLE 9-6 describes the Set Response Callback parameters.

TABLE 9-6 Set Response Callback Parameters
Parameter Description

Ptr userdata
A void * pointer to data specified by the application developer in the callback parameter of the send_set_req function.

Ptr message
A void * pointer to the SetRes message generated in response to the send_set_req function.
9.4.4.3 Set Response Callback Example

CODE EXAMPLE 9-7 Set Response Example

set_req_cb(Ptr, Ptr set_response_msg)

{

objsvc_test.print("Set Request callback\n");

Message *resp = (Message *)set_response_msg;

VTRY {

if ( resp->type() == SET_RES) {

SetRes *s_resp = (SetRes *)resp;

s_resp->print(objsvc_test);

// The Asn1Value decoding functions, including the

// member functions get_first_component and

// get_next_component can be used to examine the member data

// included in the response message at this point

// ...

}

else if ( resp->is_error() ) {

objsvc_test.print("Set response error received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

else {

objsvc_test.print(

"Unexpected or invalid response received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

}

VBEGHANDLERS

VCATCHALL {

oamsvc_test.print("Error processing response for Set\n");

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
9.4.5 Action Request Service
9.4.5.1 Interface Signature

CODE EXAMPLE 9-8 Interface Signature for Action Request Service

const Asn1Value &oc,

const Asn1Value &oi,

const Asn1Value &action_type,

const Asn1Value action_info = Asn1Value(), // Default: No action Info

const Callback cb = 0, // Default: Unconfirmed

MessId *id = 0,

const MessScope scope = MessScope(), // Default: Base object Only

const Asn1Value filter = Asn1Value(), // Default: Matches all

const MessSync sync = BEST_EFFORT,

const Asn1Value access = Asn1Value()); // Default: No access Cntrl
9.4.5.2 send_action_req Parameter Descriptions

TABLE 9-7 describes the send_action_req parameters.

TABLE 9-7 send_action_req Parameters
Parameter Description Required/ Optional

const Asn1Value oc
OID that specifies the class of the base managed object.
Required

const Asn1Value oi
Distinguished name or local distinguished name for the base managed object.
Required

const Asn1Value action_type
OID that specifies the type of action to be performed by the send_action_req function.
Required

const Asn1Value action_info
Contains information associated with the type of action specified by the action_type parameter. This option must be specified if a WITH INFORMATION SYNTAX construct is part of the GDMO definition for the action type specified by the action_type parameter.
Optional

const Callback cb
Specifies the name of a callback function invoked when a response to the action request operation is received and can be used to specify user data that is passed to the callback function when it is invoked. The callback parameter is optional for the send_action_req function. If specified, a confirmed action request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed action request operation is issued and no response is generated.
Optional

MessId id
Provides a unique identifier for a particular action request operation. If specified, the value for this parameter is generated and set by the send_action_req function.
Optional

const MessScope scope
Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.
Optional

const Asn1Value filter
Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.
Optional

const MessSync sync
Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.
Optional

const Asn1Value access
Reserved parameter that should not be used at this time.
Not available
9.4.5.3 send_action_req Example

CODE EXAMPLE 9-9 send_action_req

Result

send_registerLocal_action(char *local_sys, char *remote_sys)

{

Asn1Value actual_oc;

Asn1Value dalarm_fdn;

Asn1Value em_mis_rdn;

Asn1Value dalarm_rdn;

Asn1Value act_type;

Asn1Value act_info;

char local_sys_id[100];

char remote_sys_id[100];

Asn1Value local_id;

Asn1Value remote_id;

Asn1Value log_id;

//******************************************

// Confirmed Action request

//******************************************

// Send a confirmed registerLocal action request to an

// instance of the distributed alarm manager object class.

// The distributed alarm log manager that the request

// is sent to is contained under the system identified

// by the remote_sys parameter. The local_sys parameter

// is the name of the system that contains the distributed

// alarm log manager issuing this request.

VTRY {

// Encode oc OID. In this example, actualClass is used

// instead of the OID for the log managed object

// class.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(actual_oc.encode_oid(TAG_CONT(0),

Oid("2.9.3.4.3.42")));

// Encode the distinguished name for an instance of the

// distributed alarm log manager managed object class. The

// distributed alarm log manager is always named

// "Distrib_AlarmLog"

// Either the distinguished name form (TAG_CONT(2))

// or the local distinguished name form (TAG_CONT(4)) can be

// used with the action operation. The distinguished name form

// is used in this example.

// The get_sys_dn and get_graphstr_rdn functions are included

// in Section 9.5.

TTRYRES(get_sys_dn(remote_sys, dalarm_fdn));

TTRYRES(get_graphstr_rdn("2.9.3.5.7.11",

"EM-MIS", em_mis_rdn));

TTRYRES(get_graphstr_rdn(

Oid("1.3.6.1.4.1.42.2.2.2.300.7.1", "Distrib-AlarmLog",

dalarm_rdn));

TTRYRES(dalarm_fdn.add_component(em_mis_rdn));

TTRYRES(dalarm_fdn.add_component(dalarm_rdn));

// Encode the action type and action info parameters

// for the action operation. The ASN.1 for the registerLocal

// action_info is:

// LocalRegistrar ::= SEQUENCE

// {

// receiverMIS SystemId,

// senderMIS SystemId,

// logId SimpleNameType

// }

// The SystemIds for each of the systems also include

// a port number -- 5555 in this example. Port 5555

// is the default CMIP/LPP port used by the MIS.

// The CMIP spec specifies TAG_CONT(2) as the Tag for

// the action type.

TTRYRES(act_type.encode_oid(TAG_CONT(2),

Oid("1.3.6.1.4.1.42.2.2.2.300.9.4")));

sprintf(local_sys_id, "%s:%s", local_sys, "5555");

TTRYRES(local_id.encode_octets(TAG_GRAPHSTR,

DataUnit((char *)&local_sys_id)));

sprintf(remote_sys_id,"%s:%s", remote_sys, "5555");

TTRYRES(remote_id.encode_octets(TAG_GRAPHSTR,

DataUnit((char *)&remote_sys_id)));

TTRYRES(log_id.encode_octets(TAG_GRAPHSTR, "AlarmLog"));

TTRYRES(act_info.start_construct(TAG_SEQ));

TTRYRES(act_info.add_component(remote_id));

TTRYRES(act_info.add_component(local_id));

TTRYRES(act_info.add_component(log_id));

// Send the confirmed action request. No user data is

// specified for the callback parameter. The action_req_cb

// function is included as part of the services

// API examples.

oamsvc_test.print("About to issue Confirmed Action

Request\n");

if (send_action_req(actual_oc, dalarm_fdn, act_type,

act_info, Callback(action_req_cb, 0)) != OK)

objsvc_test.print("Error issuing Confirmed Action

Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued Confirmed Action Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding Action Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
9.4.6 Action Response Callback

This callback function is used only in conjunction with confirmed action requests. The name of the callback function must match the name of the callback function specified in the callback parameter of the send_action_req function.
9.4.6.1 Interface Signature

void user-provided-action-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to ActionRes message
9.4.6.2 Action Response Callback Parameter Description

TABLE 9-8 describes the action response callback parameters.

TABLE 9-8 Action Response Callback Parameters
Parameter Description

Ptr userdata
A void * pointer to data specified by the application developer in the callback parameter of the send_action_req function.

Ptr message
A void * pointer to the ActionRes message generated in response to the send_action_req function.

9.4.6.3 Action Response Callback Example

The header file dalarm.hh is needed to successfully compile and link this example. The header file is needed to obtain the type definition for the RegState data type.
CODE EXAMPLE 9-10 Action Response Callback

void

action_req_cb(Ptr, Ptr action_response_msg)

{

objsvc_test.print("Action Request callback\n");

Message *resp = (Message *)action_response_msg;

VTRY {

if ( resp->type() == Action_RES) {

ActionRes *a_resp = (ActionRes *)resp;

a_resp->print(objsvc_test);

// Decode the action reply field

// LocalRegistrarReply ::= SEQUENCE

// {

// senderMIS SystemId,

// logId SimpleNameType,

// regStatus RegistrationState

// }

Asn1Value remote_id, log_id, reg_state;

DataUnit sndr_du, log_du;

I32 reg_val;

RegState reg;

TTRYRES(a_resp->action_reply.

first_component(remote_id));

TTRYRES(remote_id.decode_octets(sndr_du));

TTRYRES(a_resp->action_reply.next_component(

remote_id, log_id));

TTRYRES(log.decode_octets(log_du));

TTRYRES(a_resp->action_reply.next_component(

log_id, reg_state));

TTRYRES(reg_state.decode_enum(reg_val));

reg = (RegState)reg_val;

// Now do any other action response processing.

// ...

}

else if ( resp->is_error() ) {

objsvc_test.print("Action response error received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

else {

objsvc_test.print(

"Unexpected or invalid response received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

}

VBEGHANDLERS

VCATCHALL {

oamsvc_test.print("Error processing response for Action\n");

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
9.4.7 Create Request Service

Enables you to override GDMO restrictions that are related to MO creation.

9.4.7.1 Create Request Service

The rules for creating an MO are defined in the MO class definition and the name bindings in a GDMO document. The rules which are defined in the name bindings impose restrictions on the creation of MOs, but it is possible to override some of these restrictions when requesting creation of an MO through the function send_create_req(). Specifically, the absence of a CREATE construct in the name binding is intended to have the effect of restricting the creation of an MO by a management application.

To allow behavior internal to the MIS to override this restriction, this function is defined with a flags parameter. The relevant flag value is ReqMess::OVERRIDE_NAME_BINDING, which is defined in message.hh.
9.4.7.2 Interface Signature

Result send_create_req(

const Asn1Value &oc,

const Asn1Value &oi,

const Asn1Value attr_value_list = Asn1Value(),

const Callback cb = 0, // Default: Unconfirmed

MessId *id = 0,

const Asn1Value superior_oi = Asn1Value(),

const Asn1Value reference_oi = Asn1Value(),

const Asn1Value access = Asn1Value(),

Boolean sub_trans

); / Default: No access ctrl
9.4.7.3 send_create_req Parameter Descriptions

TABLE 9-9 describes the send_create_req parameters.

TABLE 9-9 send_create_req Parameters
Parameter Description Required/ Optional

const Asn1Value oc
OID that specifies the class of the managed object.
Required

const Asn1Value oi
Distinguished name or local distinguished name for the managed object.
Required

const Asn1Value attr_value_list
Set of attribute ID and attribute value pairs that specify the attributes assigned new values by a send_create_req service request operation. The values specified in the send_create_req service function override the corresponding attributes from the reference object (if specified) or from the default value specified in the GDMO definition for the managed object class. Although this is an optional parameter, attribute values must be specified for all mandatory attributes defined for a GDMO managed object class, specified by a default value, by a reference object, or by this parameter.
Optional

const Callback cb
Specifies the name of a callback function invoked when a response to the create request operation is received. Can be used to specify user data passed to the callback function when it is invoked. Callback parameter is optional for the send_create_req function. If specified, a confirmed create request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed create request operation is issued and no response is generated.
Optional

MessId id
Provides a unique identifier for a particular create request operation. If specified, the value for this parameter is generated and set by the send_create_req function.
Optional

const Asn1Value superior_oi
Distinguished name or local distinguished name for an existing superior object under which a managed object is to be created. This optional parameter should not be specified if a value is specified for the oi parameter. The managed object created is contained under the superior object in the MIT.
Optional

const Asn1Value reference_oi
Distinguished name or local distinguished name for a reference object. If this parameter is specified, it must specify the name of a managed object of the same class as the managed object to be created. The attribute values of the reference object become default values for the new managed object for any attributes not specified in the value for the attr_value_list parameter.
Optional

Boolean sub_trans
Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.
Optional

const Asn1Value access
Reserved parameter, not to be used at this time.
Not available

9.4.7.4 send_create_req Example

CODE EXAMPLE 9-11 shows how to override restrictions on creating an MO.

The mysystem.gdmo and mysystem.asn1 files must be loaded into the MDR for this example to work properly. The mysystem files are located at /opt/SUNWconn/em/src/scenario/example1. The README file in this directory also describes how to load the mysystem files.
< tr>
CODE EXAMPLE 9-11 send_create_req

Result

create_mySystem_object(char *system_name, char *mySystem_name)

{

Asn1Value mySystem_oc;

Asn1Value mySystem_fdn;

Asn1Value mySystem_rdn;

//******************************************

// Confirmed create request

//******************************************

// Send a confirmed create request for an

// instance of the mySystem manager object class.

// Instances of the mySystem class are contained by

// instances of the System class. The system_name

// parameter specifies the name of the system to contain

// the new instance. The mySystem_name parameter is used

// to specify the name of the instance to be created.

VTRY {

// Encode oc OID. In this example, the OID for the

// mySystem class is used.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(mySystem_oc.encode_oid(

TAG_CONT(0),Oid("1.2.3.4.5.6.3.10")));

// Encode the distinguished name for an instance of the

// mySystem managed object class. Instances of the mySystem

// class are named using the systemId attribute in the class.

// Either the distinguished name form (TAG_CONT(2))

// or the local distinguished name form (TAG_CONT(4)) can be

// used with the create operation. The distinguished name form

// is used in this example.

// The get_sys_dn and get_graphstr_rdn functions are included

// in Section 9.5. The definition for the sys_id (systemId) OID

// is included in Section 9.5.

TTRYRES(get_sys_dn(system_name, mySystem_fdn));

TTRYRES(get_graphstr_rdn(sys_id, // systemId OID

mySystem_name, mySystem_rdn));

TTRYRES(mySystem_fdn.add_component(mySystem_rdn));

// Encode the attribute list for the create request

// All mandatory attributes must be specified as part

// of the create request (unless the GDMO defines a

// initial value sub-clause for the attribute, or

// specifies a reference object that contains the

// attribute).

// Note: CMIP requires a TAG_CONT(7) encoding for the

// attribute list rather than TAG_SEQ (refer to x711.asn1

// for encoding spec).

Asn1Value attrlist;

Asn1Value opState;

Asn1Value usState;

Asn1Value sysTitle;

Asn1Value wInt;

Asn1Value rString;

Asn1Value sysIdO;

Asn1Value opStateO;

Asn1Value usStateO;

Asn1Value sysTitleO;

Asn1Value wIntO;

Asn1Value rStringO;

Asn1Value opStateV;

Asn1Value usStateV;

Asn1Value sysTitleV;

Asn1Value wIntV;

Asn1Value rStringV;

// Initialize the OIDs.

Oid sysIdOid("2.9.3.2.7.4"); // systemId

Oid opStateOid("2.9.3.2.7.35"); // operationalState

Oid usStateOid("2.9.3.2.7.39"); // usageState

Oid sysTitleOid("2.9.3.2.7.5"); // systemTitle

Oid wIntOid("1.2.3.4.5.6.7.10"); // writeableInteger

Oid rStringOid("1.2.3.4.5.6.7.11"); // readableString

// Initialize the five mandatory attributes

// in the mySystem class.

TTRYRES(opStateO.encode_oid(TAG_CONT(0), opStateOid));

TTRYRES(opStateV.encode_enum(TAG_ENUM, 1)); // enabled

TTRYRES(opState.start_construct(TAG_SEQ));

TTRYRES(opState.add_component(opStateO));

TTRYRES(opState.add_component(opStateV));

TTRYRES(usStateO.encode_oid(TAG_CONT(0), usStateOid));

TTRYRES(usStateV.encode_enum(TAG_ENUM, 1)); // active

TTRYRES(usState.start_construct(TAG_SEQ));

TTRYRES(usState.add_component(usStateO));

TTRYRES(usState.add_component(usStateV));

TTRYRES(sysTitleO.encode_oid(TAG_CONT(0), sysTitleOid));

TTRYRES(sysTitleV.encode_null(TAG_NULL));

TTRYRES(sysTitle.start_construct(TAG_SEQ));

TTRYRES(sysTitle.add_component(sysTitleO));

TTRYRES(sysTitle.add_component(sysTitleV));

TTRYRES(wIntO.encode_oid(TAG_CONT(0), wIntOid));

TTRYRES(wIntV.encode_int(TAG_INT, 5));

TTRYRES(wInt.start_construct(TAG_SEQ));

TTRYRES(wInt.add_component(wIntO));

TTRYRES(wInt.add_component(wIntV));

TTRYRES(rStringO.encode_oid(TAG_CONT(0), rStringOid));

TTRYRES(rStringV.encode_octets(TAG_GRAPHSTR,DataUnit

("test1")));

TTRYRES(rString.start_construct(TAG_SEQ));

TTRYRES(rString.add_component(rStringO));

TTRYRES(rString.add_component(rStringV));

// Create the attribute list.

TTRYRES(attrlist.start_construct(TAG_CONT(7)));//Implicit

set of

TTRYRES(attrlist.add_component(opState));

TTRYRES(attrlist.add_component(usState));

TTRYRES(attrlist.add_component(sysTitle));

TTRYRES(attrlist.add_component(wInt));

TTRYRES(attrlist.add_component(rString));

// Send the confirmed create request. No user data is

// specified for the callback parameter. The create_req_cb

// function is included as part of the Object Services

// API examples.

oamsvc_test.print("About to issue Confirmed Create

Request\n");

if (send_action_req(mySystem_oc, mySystem_fdn, attrlist,

Callback(create_req_cb, 0)) != OK)

objsvc_test.print("Error issuing Confirmed Create

Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued Confirmed Create Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding Create Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
9.4.8 Create Response Callback

This function is used only in conjunction with confirmed create requests. The name of the callback function must match the name of the callback function specified in the callback parameter of the send_create_req function.
9.4.8.1 Interface Signature

void user-provided-create-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to CreateRes message
9.4.8.2 Create Response Callback Parameter Descriptions

TABLE 9-10 describes the Create Response Callback parameters.

TABLE 9-10 Create Response Callback Parameters
Parameter Description

Ptr userdata
A void * pointer to data specified by the application developer in the callback parameter of the send_create_req function.

Ptr message
A void * pointer to the CreateRes message generated in response to the send_create_req function.

9.4.8.3 Create Response Callback Example

The mysystem.gdmo and mysystem.asn1 files must be loaded into the MDR for this example to work properly. The mysystem files can be found in /opt/SUNWconn/em/src/scenario/example1. The README file in this directory also describes how to load the mysystem files.
CODE EXAMPLE 9-12 Create Response Callback

void

create_req_cb(Ptr, Ptr create_response_msg)

{

objsvc_test.print("Create Request callback\n");

Message *resp = (Message *)create_response_msg;

VTRY {

if ( resp->type() == CREATE_RES) {

CreateRes *cr_resp = (CreateRes *)resp;

cr_resp->print(objsvc_test);

// The Asn1Value decoding functions, including the

// member functions get_first_component and

// get_next_component can be used to examine the member data

// included in the response message at this point

// ...

}

else if ( resp->is_error() ) {

objsvc_test.print("Action response error received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

else {

objsvc_test.print(

"Unexpected or invalid response received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

}

VBEGHANDLERS

VCATCHALL {

oamsvc_test.print("Error processing response for Action\n");

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
9.4.9 Delete Request Service

send_delete_req enables you to override GDMO restrictions that are related to MO deletion operations.

This section includes the interface signature, send_delete_req parameters, and examples.

9.4.9.1 Delete Request Service

The rules for deleting an MO are defined in the MO class definition and the name bindings in a GDMO document. The rules which are defined in the name bindings impose restrictions on the deletion of MOs, but it is possible to override some of these restrictions when requesting deletion of an MO through the function send_delete_req(). Specifically, the absence of a DELETE construct in the name binding is intended to have the effect of restricting the deletion of an MO by a management application.

To allow behavior internal to the MIS to override this restriction, this function is defined with a flags parameter. The relevant flag value is ReqMess::OVERRIDE_NAME_BINDING, which is defined in message.hh.

Note that:

The ONLY-IF-NO-CONTAINED-OBJECTS construct cannot be overridden.
The MIS imposes a restriction on object deletion if an object contains other objects, irrespective of whether the ONLY-IF-NO-CONTAINED-OBJECTS construct appears in the name binding.
If the DELETES-CONTAINED-OBJECTS construct appears in the name binding, the override capability only applies to the base object, and not to contained objects.
If a delete request specifies a scope and a filter, the override capability only applies to the base object, and not to the scoped and filtered objects.
9.4.9.2 Interface Signature

CODE EXAMPLE 9-13 Delete Request Service: Interface Signature

const Asn1Value &oc,

const Asn1Value &oi,

const Callback cb = 0, // Default: Unconfirmed

MessId *id = 0,

const MessScope scope = MessScope(),
// Default: Base object only

const Asn1Value filter = Asn1Value(),
// Default: Matches all

const MessSync sync = BEST_EFFORT,

const Asn1Value access = Asn1Value(),

Boolean sub_trans
); // Default: No access cntrl
9.4.9.3 send_delete_req Parameter Descriptions

TABLE 9-11 describes the send_delete_req parameters.

TABLE 9-11 send_delete_req Parameters
Parameter Description Required/ Optional

const Asn1Value oc
OID that specifies the class of the managed object.
Required

const Asn1Value oi
Distinguished name or local distinguished name for the managed object.
Required

const Callback cb
Specifies the name of a callback function invoked when a response to the delete request operation is received. Can also be used to specify user data passed to the callback function when it is invoked. The callback parameter is optional for the send_delete_req function. If specified, a confirmed delete request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed delete request operation is issued and no response is generated.
Optional

MessId id
Provides a unique identifier for a particular delete request operation. If specified, the value for this parameter is generated and set by the send_delete_req function.
Optional

const MessScope scope
Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.
Optional

const Asn1Value filter
Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.
Optional

const MessSync sync
Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.
Optional

Boolean sub_trans
Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.
Optional

const Asn1Value access
Reserved parameter. Do not use now.
Not available

9.4.9.4 send_delete_req Examples

CODE EXAMPLE 9-14 shows how to override restrictions on deleting an MO.

The mysystem.gdmo and mysystem.asn1 files must be loaded into the MDR for this example to work properly. The mysystem files are located at /opt/SUNWconn/em/src/scenario/example1. The README file in this directory also describes how to load the mysystem files.

Delete Request: Base Object Only
CODE EXAMPLE 9-14 Delete Request: Base Object Only

Result

delete_mySystem_object(char *system_name, char *mySystem_name)

{

Asn1Value mySystem_oc;

Asn1Value mySystem_fdn;

Asn1Value mySystem_rdn;

//******************************************

// Confirmed delete request

//******************************************

// Send a delete request to an instance of the

// mySystem managed object class. The mySystem

// instance to be deleted is contained by the system

// object specified by system_name. The name of the

// instance of the mySystem class to delete is specified

// by the mySystem_name parameter.

VTRY {

// Encode oc OID. In this example, the OID for the

// mySystem class is used.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(mySystem_oc.encode_oid(

TAG_CONT(0),Oid("1.2.3.4.5.6.3.10")));

// Encode the distinguished name for an instance of the

// mySystem managed object class. Instances of the mySystem

// class are named using the systemId attribute in the class.

// Either the distinguished name form (TAG_CONT(2))

// or the local distinguished name form (TAG_CONT(4)) can be

// used with the action operation. The distinguished name form

// is used in this example.

// The get_sys_dn and get_graphstr_rdn functions are included

// in Section 9.5. The definition for the sys_id (systemId) OID

// is included in Section 9.5.

TTRYRES(get_sys_dn(system_name, mySystem_fdn));

TTRYRES(get_graphstr_rdn(sys_id, // systemId OID

mySystem_name, mySystem_rdn));

TTRYRES(mySystem_fdn.add_component(mySystem_rdn));

// Send the confirmed Delete Request. No user data is

// specified for the callback parameter. The delete_req_cb

// function is included as part of the Object Services API examples.

objsvc_test.print("About to issue confirmed Delete

Request\n");

if (send_delete_req(mySystem_oc, mySystem_fdn,

Callback(delete_req_cb, 0)) != OK) {

objsvc_test.print("Error issuing confirmed Delete Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued confirmed Delete Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding Delete Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
Delete Request: Scoped Operation

CODE EXAMPLE 9-15 Delete Request: Scoped Operation

Result

delete_mySystem_object(char *system_name)

{

Asn1Value actual_oc;

Asn1Value system_fdn;

//******************************************

// Confirmed delete request

//******************************************

// Send a delete request to delete all instances

// of the mySystem managed object class below a

// system object. The system "base" object is

// specified by the system_name parameter.

// A CMIS filter is used to select only instances

// of the mySystem class.

VTRY {

// Encode oc OID. In this example, actualClass is used

// instead of the OID for the log managed object class.

// Note: CMIP requires a TAG_CONT(0) encoding for the

// object class rather than TAG_OID (refer to x711.asn1

// for encoding spec).

TTRYRES(actual_oc.encode_oid(TAG_CONT(0),

Oid("2.9.3.4.3.42")));

// Encode the distinguished name for the instance of the

// system managed object class that is the base object for

// the scoped operation.

// Either the distinguished name form (TAG_CONT(2))

// or the local distinguished name form (TAG_CONT(4)) can be

// used with the delete operation. The distinguished name form

// is used in this example.

// The get_sys_dn and get_graphstr_rdn functions are included

// in Section 9.5. The definition for the sys_id (systemId) OID

// is included in Section 9.5.

TTRYRES(get_sys_dn(system_name, system_fdn));

// Encode the CMIS Filter. This filter checks for

// "managedObjectClass == mySystem"

Asn1Value cmis_filter;

Asn1Value filter_item;

Asn1Value mOC_OID;

Asn1Value mySystem_oc_OID;

TTRYRES(cmis_filter.start_construct(TAG_CONT(8));

TTRYRES(filter_item.start_construct(TAG_CONT(0));

TTRYRES(mOC_OID.encode_oid( // ISO DMI

TAG_CONT(0),Oid("2.9.3.2.7.60"))); // managedObjectClass

TTRYRES(mySystem_oc_OID.encode_oid(

TAG_CONT(0),Oid("1.2.3.4.5.6.3.10")));

TTRYRES(filter_item.add_component(mOC_OID));

TTRYRES(filter_item.add_component(mySystem_oc_OID));

TTRYRES(cmis_filter.add_component(filter_item));

// Send the confirmed scoped Delete Request. No user data is

// specified for the callback parameter. The delete_req_cb

// function is included as part of the Object Services API examples.

objsvc_test.print(

"About to issue confirmed scoped Delete Request\n");

if (send_delete_req(mySystem_oc, mySystem_fdn,

Callback(scoped_del_req_cb, 0),

MessScope(NTH_LEVEL, 1), cmis_filter) != OK) {

objsvc_test.print(

"Error issuing confirmed scoped Delete Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued confirmed scoped Delete

Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding scoped Delete

Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
9.4.10 Delete Response Callback

This callback function is used only in conjunction with the confirmed delete request service. The name of the callback function must match the name of the callback function specified in the callback parameter of the send_delete_req function.
9.4.10.1 Interface Signature

void user-provided-delete-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to DeleteRes message
9.4.11 Delete Response Callback Parameter Description

TABLE 9-12 describes the Delete Response Callback parameters.

TABLE 9-12 Delete Response Callback Parameters
Parameter Description

Ptr userdata
A void * pointer to data specified by the application developer in the callback parameter of the send_delete_req function.

Ptr message
A void * pointer to the DeleteRes message generated in response to the send_delete_req function.

9.4.11.1 Delete Response Callback Examples

The mySystem.gdmo and mySystem.asn1 files must be loaded into the MDR for these examples to work properly. The mySystem files are located at /opt/SUNWconn/em/src/scenario/example1. The README file in this directory also describes how to load the mySystem files.
Delete Response Callback Function: Single Response (Base Object Only)

CODE EXAMPLE 9-16 Delete Response Callback Function: Single Response

void

del_req_cb(Ptr, Ptr delete_response_msg)

{

objsvc_test.print("Get Request callback\n");

Message *resp = (Message *)delete_response_msg;

VTRY {

if ( resp->type() == DELETE_RES) {

DeleteRes *d_resp = (DeleteRes *)resp;

d_resp->print(objsvc_test);

// The Asn1Value decoding functions, including the

// member functions get_first_component and

// get_next_component can be used to examine the member data

// included in the response message at this point

// ...

}

else if ( resp->is_error() ) {

objsvc_test.print("Delete response error received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

else {

objsvc_test.print(

"Unexpected or invalid response received\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

}

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("Error processing response for Delete\n");

resp->print(objsvc_error);

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
Delete Response Callback Function: Multiple Responses (Scoped Operation)

CODE EXAMPLE 9-17 Delete Response Callback Function: Multiple Responses

static int d_resp_count = 0;

static int d_err_count = 0;

static int d_unknown_count = 0;

void

scoped_del_req_cb(Ptr userdata, Ptr delete_response_msg)

{

objsvc_test.print("Scoped Delete Request callback:");

Message *resp = (Message *)delete_response_msg;

VTRY {

if ( resp->type() == DELETE_RES) {

DeleteRes *sd_resp = (DeleteRes *)resp;

if (sd_resp->linked) {

objsvc_test.print("*** LINKED Response ***\n");

resp_count++;

sd_resp->print(objsvc_test);

// The Asn1Value decoding functions, including the

// member functions get_first_component and

// get_next_component can be used to examine the member

// data included in the response message at this point

// ...

} else {

objsvc_test.print("**** Final Response ****\n");

sd_resp->print(objsvc_test);

objsvc_test.print("Valid: %d, Error: %d, Invalid:

%d\n",

resp_count, err_count, unknown_count);

// Final response processing can be performed here. The

// final response message does not contain any attribute

// value data.

// ...

}

}

else if ( resp->is_error() ) {

objsvc_test.print("Error Response\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

err_count++;

}

else {

objsvc_test.print("Invalid Message\n");

objsvc_test.print( "message type = %s\n",

MessType_fmt(resp->type()));

resp->print(objsvc_error);

unknown_count++;

}

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print(

"\nError processing response for Scoped Delete\n");

}

VENDHANDLERS

if ( resp )

Message:: delete_message(resp);

}
9.4.12 Event Report Request Service (Unconfirmed)

This section includes the interface signature, send_event_req parameters, and examples.
9.4.12.1 Interface Signature

CODE EXAMPLE 9-18 Event Report Request: Interface Signature

const Asn1Value &oc,

const Asn1Value &oi,

const Asn1Value &event_type,

const Asn1Value event_info = ACEGlobals::null_asn1_value,
// Default: No event info

const Asn1Value event_time = ACEGlobals::null_asn1_value,
// Default: No value

const Callback cb = null_callback, // Default: Unconfirmed

MessId *id = 0);
Note – The send_event_req service supports only unconfirmed operations. Specifying a callback generates a runtime error.

9.4.12.2 send_event_req Parameter Descriptions

TABLE 9-13 describes the send_event_req parameters.

TABLE 9-13 send_event_req Parameters
Parameter Description Required/ Optional

const Asn1Value oc
OID that specifies the class of the base managed object.
Required

const Asn1Value oi
Distinguished name or local distinguished name for the base managed object.
Required

const Asn1Value event_type
OID that specifies the type of notification generated by the send_event_req function.
Required

const Asn1Value event_info
Specifies any event information associated with the type of notification generated. This is an optional parameter but must be present if a WITH INFORMATION SYNTAX construct is specified as part of the GDMO definition for the notification type.
Optional

const Asn1Value event_time
The time at which the notification is generated.
Optional

const Callback cb
An optional reserved parameter for the event report request operation and should not be specified. Only unconfirmed (no callback function) event request operations are currently supported using this function call. If a value for this parameter is specified (in order to specify an id parameter, the cb parameter needs to be specified), it must either be set to Callback() or Callback(0,0). Any other value generates an error when the send_event_req function is invoked.
Optional reserved

MessId id
Message identifier that uniquely identifies this request operation. If specified, the value for this parameter is generated and set by the send_event_req function.
Optional

9.4.12.3 send_event_req Example

The GDMO and definition for the notification generated by this example is as follows:
CODE EXAMPLE 9-19 send_event_req

connectivityChange NOTIFICATION

BEHAVIOUR connectivityChangeBehaviour BEHAVIOUR DEFINED AS

!Generated by an instance of the connectMgr object

when the state of a connection between two MISs

changes.!;

;

WITH INFORMATION SYNTAX ConnectMgr-ASN1.ConnectivityChangeInfo

REGISTERED AS { connectivityMgmt 10 1 };

The corresponding ASN.1 definitions are as follows:

ConnectMgr-ASN1 { 6 2 3 4 5 6 7 2 1 }

...

ConnectState ::= ENUMERATED

{

notConnected(0),

connected(1),

errorDisconnect(2),

resyncDisconnect(3),

badapplicationId(4)

}

...

ConnectivityChangeDefinition ::= SEQUENCE

{

remoteMIS SystemId,

previousState ConnectState,

currentState ConnectState

}

ConnectivityChangeInfo ::= ConnectivityChangeDefinition

Example code to generate notification using send_event_req function is:

Result

send_conn_change_event(char *from_sys, char *remote_sys)

{

Asn1Value conn_oc;

Asn1Value conn_oi;

Asn1Value em_mis_rdn;

Asn1Value conn_rdn;

Asn1Value conn_evt_type;

Asn1Value conn_evt_info;

Asn1Value rmt_id;

Asn1Value rmt_prev;

Asn1Value rmt_curr;

//******************************************

// Unconfirmed event report request

//******************************************

// Issue a connectivity change notification

// This notification is defined by the connection

// manager object (refer to connmgr.gdmo/connmgr.asn1)

// and is issued when the connectivity state between

// two MISs changes. In this example, the two MISs

// are from_sys (which generates the notification) and

// remote_sys.

VTRY {

// Encode oc OID for connection manager object class

// which is defined in connmgr.gdmo. Note: CMIP requires

// a TAG_CONT(0) encoding for the object class rather

// than TAG_OID (refer to x711.asn1 for encoding spec).

TTRYRES(conn_oc.encode_oid(

TAG_CONT(0),Oid("1.3.6.1.4.1.42.2.2.2.201.3.1")));

// Encode the distinguished name for the connection manager

// managed object that generates the notification.

// The send_event_req function requires the distinguished

// name form (TAG_CONT(2)) for the object instance.

TTRYRES(get_sys_dn(from_sys, conn_oi));

TTRYRES(get_graphstr_rdn(

"2.9.3.5.7.11","EM-MIS", em_mis_rdn));

TTRYRES(get_graphstr_rdn(

"1.3.6.1.4.1.42.2.2.2.201.7.3","ConnectMgr",

conn_rdn));

TTRYRES(conn_oi.add_component(em_mis_rdn));

TTRYRES(conn_oi.add_component(conn_rdn));

// Encode the connectivityChange event type and event info

// The connectivityChange OID is defined in connmgr.gdmo.

// The format of the corresponding event info is defined

// in connmgr.asn1.

// Note: CMIP requires a TAG_CONT(6) for the event type OID

// rather than a TAG_OID and also requires a TAG_CONT(8)

// encoding for the event info rather than a TAG_SEQ.

TTRYRES(conn_evt_type.encode_oid(

TAG_CONT(6),Oid("1.3.6.1.4.1.42.2.2.2.201.10.1")));

TTRYRES(conn_evt_info.start_construct(TAG_CONT(8)));

TTRYRES(rmt_id.encode_octets(

TAG_GRAPHSTR, DataUnit(remote_sys)));

TTRYRES(rmt_prev.encode_enum(TAG_ENUM, 0)); // notConnected

TTRYRES(rmt_curr.encode_enum(TAG_ENUM, 1)); // connected

TTRYRES(conn_evt_info.add_component(rmt_id));

TTRYRES(conn_evt_info.add_component(rmt_prev));

TTRYRES(conn_evt_info.add_component(rmt_curr));

// Send the Event Report Request

objsvc_test.print(

"About to issue Unconfirmed EVENT REPORT Request\n");

if (send_event_req(conn_oc, conn_oi, conn_evt_type,

conn_evt_info) != OK) {

objsvc_test.print(

"Error issuing Unconfirmed EVENT REPORT Request\n");

return NOT_OK;

}

else

objsvc_test.print("Issued Unconfirmed EVENT REPORT

Request\n");

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding EVENT REPORT

Request\n");

return NOT_OK;

}

VENDHANDLERS

return OK;

}
9.4.13 Event Report Response Callback

This callback function is not supported for the Solstice EM services interface.

9.5 Supporting Functions for Example Code

This section includes the following information:

Debugging flags
get_sys_dn function
get_graphstr_rdn function

9.5.1 Debugging Flags

The following code lines must be included in the file that contains the example functions.
Debug_on(objsvc_test)

Debug_on(objsvc_error)

// Note: Do not include a semicolon after these two lines.
If the example functions are spread across multiple files, the above definitions must only be included in one file. The other files need to contain the following code lines:
extern Debug objsvc_test;

extern Debug objsvc_error;
The debug flags can be enabled using the following commands:
/opt/SUNWconn/em/bin/em_debug "on objsvc_test"

/opt/SUNWconn/em/bin/em_debug "on objsvc_error"
or alternatively using the following command:
/opt/SUNWconn/em/bin/em_debug "on objsvc_*"
9.5.2 get_sys_dn Function

The get_sys_dn function encodes a distinguished name for an instance of the system managed object class.
CODE EXAMPLE 9-20 get_sys_dn Function

// an instance of the system managed object class. The encoding

// assumes that the instance is contained directly under root

Oid sys_id((char *)"2.9.3.2.7.4"); // ISO DMI systemId OID

Result

get_sys_dn(const char *sys_nm, Asn1Value &sys_fdn)

{

Asn1Value sys_rdn;

Asn1Value sys_ava;

Asn1Value sys_name;

Asn1Value sys_oid;

if (!sys_nm)

return NOT_OK;

VTRY{

TTRYRES(sys_fdn.start_construct(TAG_CONT(2)));

TTRYRES(sys_rdn.start_construct(TAG_SET));

TTRYRES(sys_ava.start_construct(TAG_SEQ));

TTRYRES(sys_oid.encode_oid(TAG_OID, sys_id));

TTRYRES(sys_name.encode_octets(TAG_GRAPHSTR, sys_nm));

TTRYRES(sys_ava.add_component(sys_oid));

TTRYRES(sys_ava.add_component(sys_name));

TTRYRES(sys_rdn.add_component(sys_ava));

TTRYRES(sys_fdn.add_component(sys_rdn));

}

VBEGHANDLERS

VCATCHALL

objsvc_test.print("get_sys_dn: error encoding DN\n");

return NOT_OK;

VENDHANDLERS

return OK;

}
9.5.3 get_graphstr_rdn Function

The get_graphstr_rdn function are described in CODE EXAMPLE 9-21.
CODE EXAMPLE 9-21 get_graphstr_rdn Function

// Function to encode an RDN consisting of an
// object identifier (OID) and an ASN.1 GraphicString

Result

get_graphstr_rdn(const char *a_oidstr, const char *a_str, Asn1Value &a_rdn)

{

Asn1Value a_ava;

Asn1Value a_oid;

Asn1Value a_val;

if (!a_oidstr || !a_str)

return NOT_OK;

TRY {

TTRYRES(a_rdn.start_construct(TAG_SET));

TTRYRES(a_ava.start_construct(TAG_SEQ));

TTRYRES(a_oid.encode_oid(TAG_OID, Oid(a_oidstr)));

TTRYRES(a_val.encode_octets(TAG_GRAPHSTR,

DataUnit(a_str)));

TTRYRES(a_ava.add_component(a_oid));

TTRYRES(a_ava.add_component(a_val));

TTRYRES(a_rdn.add_component(a_ava));

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding RDN for %s\n", a_val);

return NOT_OK;

}

VENDHANDLERS

return OK;

}

// Function to encode an RDN consisting of an object identifier (OID)

// and an ASN.1 GraphicString

Result

get_graphstr_rdn(const Oid &a_oidval, const char *a_str, Asn1Value

&a_rdn)

{

Asn1Value a_ava;

Asn1Value a_oid;

Asn1Value a_val;

if (!a_str)

return NOT_OK;

TRY {

TTRYRES(a_rdn.start_construct(TAG_SET));

TTRYRES(a_ava.start_construct(TAG_SEQ));

TTRYRES(a_oid.encode_oid(TAG_OID, a_oidval));

TTRYRES(a_val.encode_octets(TAG_GRAPHSTR,

DataUnit(a_str)));

TTRYRES(a_ava.add_component(a_oid));

TTRYRES(a_ava.add_component(a_val));

TTRYRES(a_rdn.add_component(a_ava));

}

VBEGHANDLERS

VCATCHALL {

objsvc_test.print("\nError encoding RDN for %s\n", a_val);

return NOT_OK;

}

VENDHANDLERS

return OK;

}

**TABLE 9-1** Service Request Function Parameters
Parameter	Description
const Asn1Value oc	Instance of the Asn1Value C++ class that contains an Object Identifier (OID) for a managed object class. For each of the Object Service API request functions, except the send_event_req function, this parameter can be the OID for Actual Class. Actual Class is an ISO defined OID that matches the class of any managed object on which an operation is performed. The oc parameter is used as follows: Single Object Selection (Base Object Only Scoping): The OID specifies the object class of the managed object from which attribute values are retrieved, using the Get operation. Multiple Object Selection Using Scoping and Filtering: The OID parameter specifies the object class of the managed object used as the starting point for the selection of managed objects from which attribute values are retrieved using the Get operation. The CMIS and CMIP specifications refer to this parameter as either the base object class or managed object class, depending on the type of operation being performed.
const Asn1Value oi	Instance of the Asn1Value C++ class that contains either a distinguished name (context specific 2) or a local distinguished name (context specific 4) for a managed object instance. The oi parameter is used as follows: Single Object Selection (Base Object Only Scoping): The oi parameter specifies the name of the managed object instance from which the request operation is performed. Multiple Object Selection Using Scoping and Filtering: The oi parameter specifies the name of the managed object instance to be used as the starting point for the selection of managed objects on which the request operation is performed. The CMIS and CMIP specifications refer to this parameter as either the base object class or managed object instance, depending on the type of operation being performed. Specify this parameter as a null Asn1Value (Asn1Value()) if a managed object instance name is specified by the superior_oi parameter.
const Callback cb	Instance of the Callback C++ class, which can contain two pointers. The first is a pointer of a callback function to be invoked when a response to an operation is received. The second is a pointer to application developer-specified data (commonly referred to as user data) to be passed to the callback function when it is invoked. The user data pointer is always optional. The cb parameter is required, or optional for service request functions that support it. If specified, a confirmed service request is issued. If not specified, an unconfirmed service request is issued.
const Asn1Value attr_list	Instance of the Asn1Value C++ class that contains a set of OIDs for attributes. Attributes are normally members of the object class specified by the oc parameter or members of the class of an object instance identified within a scoped operation.
const Asn1Value modify_list	A set of attribute ID and attribute value pairs that specify for a send_set_req service request operation which attributes are to be modified and new values for those attributes. The modify_list parameter is an instance of the Ans1Value C++ class and is typically a sequence of an OID that identifies an attribute, followed by a value for the attribute.
const Asn1Value action_type	Instance of the Asn1Value C++ class that contains an object identifier (OID) that specifies the type of action generated by the send_action_req function.
const Asn1Value action_info	Instance of the Asn1Value C++ class that contains any event information associated with the type of action specified by the action_type parameter. The action_info parameter typically contains a sequence or set of ASN.1-defined values. The action_info parameter is optional for the send_action_req service function but must be present if a WITH INFORMATION SYNTAX construct is specified as part of the GDMO definition for the action type specified by the action_type parameter.
const Asn1Value attr_value_list	A set of attribute ID and attribute value pairs that specify the attributes assigned new values by a send_create_req service request operation. The values specified in the send_create_req service function override the corresponding attributes from the reference object (if specified using the reference_oi parameter) or from the default value specified in the GDMO definition for the managed object class. The attr_value_list parameter is an instance of the Asn1Value C++ class and is typically a sequence of an OID that identifies an attribute, followed by a value for the attribute. The attr_value_list parameter is an optional parameter for the send_create_req service request, although values must be specified for all mandatory attributes defined in the GDMO managed object class definition for which an instance is being created. In other words, the mandatory attribute values must be specified in the GDMO definition in a default value clause, supplied from a reference object, or else specified in the attr_value_list.
const Asn1Value superior_oi	An instance of the Asn1Value C++ class, this parameter is used only with the send_create_req function. The parameter contains either a distinguished name (context specific 2) or a local distinguished name (context specific 4) for an existing managed object instance that is to be the superior--in the MIT--of the managed object instance created. This parameter should not be specified, or should be specified as a null Asn1Value, if a managed object instance name is specified by the oi parameter.
const Asn1Value reference_oi	An instance of the Asn1Value C++ class, this parameter is used only with the send_create_req function. It contains either a distinguished name (context specific 2) or a local distinguished name (context specific 4) for an existing managed object instance that is of the same class as the managed object instance created. Attribute values associated with the managed object specified by the reference_oi parameter become default values for those attributes not specified by the attr_value_list parameter of the send_create_req function.
const Asn1Value event_type	Instance of the Asn1Value C++ class that contains an OID specifying the type of notification to be generated by the send_event_req function.
const Asn1Value event_info	An Asn1Value C++ class that contains any event information associated with the type of notification specified by the event_type parameter. This parameter typically contains a sequence or set of ASN.1-defined values and is optional for the send_event_req service function. It must be present if a WITH INFORMATION SYNTAX construct is specified as part of the GDMO definition for the notification type specified by the event_type parameter.
const Asn1Value event_time	Instance of the Asn1Value C++ class containing a value for the time at which a notification is generated.
MessId id	Identifier that uniquely identifies a service request operation. If specified, the value for this parameter is generated and set by the service request function.
const MessScope scope	Specifies the type of scoping used for a service request operation. The possible types of scoping are BASE_OBJECT, NTH_LEVEL,BASE-TO-NTH_Level, and ALL_LEVELS. It is optional for all service request functions that support it. If not specified, it defaults to BASE_OBJECT.
const Asn1Value filter	Instance of the Asn1Value C++ class that contains a CMISFilter (refer to the ISO DMI for a definition of the CMIS filter). All objects selected by the scoping parameter are tested against a filter. The service request operation is performed only on those objects that pass the filter test. It is an optional parameter for all service request functions that support it. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.
const MessSync sync	Specifies the type of synchronization used for a service request operation. It is an enumerated type and can take on the value ATOMIC or BEST_EFFORT. It is an optional parameter for all service request functions that support it. If not specified, it defaults to BEST_EFFORT. The use of ATOMIC is rarely supported by remote objects.
const Asn1Value access	A reserved parameter not normally specified. The access parameter defines the access control that objects selected for a service request operation must pass. The service request operation is not performed by any managed object that does not pass the access control.

**TABLE 9-2** Service Response Callback Function Parameters
Parameter	Description
Ptr userdata	Optional parameter intended for all service response callback functions. It is a void * pointer to data specified by the application developer in the callback parameter of a service request function.
Ptr message	Mandatory parameter for all service response callback functions. It is a void * pointer to the message generated in response to a service request function.

Result send_get_req( const Asn1Value &oc, const Asn1Value &oi, const Callback &cb, // Always confirmed const Asn1Value attr_list = Asn1Value(), // Default: Get all attributes MessId *id =0, const MessScope scope = MessScope(), //Default: Base object only const Asn1Value filter = Asn1Value(), //Default: Matches all const MessSync sync = BEST_EFFORT, const Asn1Value access = Asn1Value(), Boolean sub_trans ); //Default: No access cntrl

**TABLE 9-3** send_get_request Parameters
Parameter	Description	Required/ Optional
const Asn1Value oc	Specifies the class of the base managed object.	Required
const Asn1Value oi	Distinguished name of local distinguished name for the base managed object.	Required
const Callback cb	Specifies the name of a callback function invoked when a response to the get request is received and can be used to specify user data that is passed to the callback function when it is invoked.	Required
const Asn1Value attr_list	List of attribute OIDs whose attribute values are to be returned in response to the get request operation. If not specified, all attributes defined for the managed object class are returned in the response.	Optional
MessId id	Provides a unique identifier for a particular Get request operation. If specified, the value for this parameter is generated and set by the send_get_req function.	Optional
const MessScope scope	Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.	Optional
const Asn1Value filter	Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.	Optional
const MessSync sync	Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.	Optional
Boolean sub_trans	Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.	Optional
const Asn1Value access	Reserved parameter that should not be used at this time.	Not available

void user-provided-get-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to GetRes message

**TABLE 9-4** Get Response Callback Parameters
Parameter	Description
userdata	A void * pointer to data specified by the application developer in the callback parameter of the send_get_req function.
message	A void * pointer to the GetRes message generated in response to the send_get_req function.

**TABLE 9-5** send_set_request Parameters
Parameter	Description	Required/ Optional
const Asn1Value oc	OID that specifies the class of the base managed object.	Required
const Asn1Value oi	Distinguished name or local distinguished name for the base managed object.	Required
const Ans1Value modify_list	List of attribute ID and attribute value pairs that specify which attributes are to be modified by the set request operation and what the new values are for the attributes.	Required
const Callback cb	Specifies the name of a callback function invoked when a response to the set request operation is received. Can also be used to specify user data passed to the callback function when it is invoked. If specified, a confirmed set request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed set request operation is issued and no response is generated.	Optional
MessId id	Provides a unique identifier for a particular set request operation. If specified, the value for this parameter is generated and set by the send_set_req function.	Optional
const MessScope scope	Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.	Optional
const Asn1Value filter	Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.	Optional
const MessSync sync	Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.	Optional
Boolean sub_trans	Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.	Optional
const Asn1Value access	This parameter is reserved at this time.	Not available

void user-provided-set-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to SetRes message

**TABLE 9-6** Set Response Callback Parameters
Parameter	Description
Ptr userdata	A void * pointer to data specified by the application developer in the callback parameter of the send_set_req function.
Ptr message	A void * pointer to the SetRes message generated in response to the send_set_req function.

**TABLE 9-7** send_action_req Parameters
Parameter	Description	Required/ Optional
const Asn1Value oc	OID that specifies the class of the base managed object.	Required
const Asn1Value oi	Distinguished name or local distinguished name for the base managed object.	Required
const Asn1Value action_type	OID that specifies the type of action to be performed by the send_action_req function.	Required
const Asn1Value action_info	Contains information associated with the type of action specified by the action_type parameter. This option must be specified if a WITH INFORMATION SYNTAX construct is part of the GDMO definition for the action type specified by the action_type parameter.	Optional
const Callback cb	Specifies the name of a callback function invoked when a response to the action request operation is received and can be used to specify user data that is passed to the callback function when it is invoked. The callback parameter is optional for the send_action_req function. If specified, a confirmed action request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed action request operation is issued and no response is generated.	Optional
MessId id	Provides a unique identifier for a particular action request operation. If specified, the value for this parameter is generated and set by the send_action_req function.	Optional
const MessScope scope	Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.	Optional
const Asn1Value filter	Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.	Optional
const MessSync sync	Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.	Optional
const Asn1Value access	Reserved parameter that should not be used at this time.	Not available

void user-provided-action-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to ActionRes message

**TABLE 9-8** Action Response Callback Parameters
Parameter	Description
Ptr userdata	A void * pointer to data specified by the application developer in the callback parameter of the send_action_req function.
Ptr message	A void * pointer to the ActionRes message generated in response to the send_action_req function.

Result send_create_req( const Asn1Value &oc, const Asn1Value &oi, const Asn1Value attr_value_list = Asn1Value(), const Callback cb = 0, // Default: Unconfirmed MessId id = 0, const Asn1Value superior_oi* = Asn1Value(), const Asn1Value reference_oi = Asn1Value(), const Asn1Value access = Asn1Value(), Boolean sub_trans ); / Default: No access ctrl

**TABLE 9-9** send_create_req Parameters
Parameter	Description	Required/ Optional
const Asn1Value oc	OID that specifies the class of the managed object.	Required
const Asn1Value oi	Distinguished name or local distinguished name for the managed object.	Required
const Asn1Value attr_value_list	Set of attribute ID and attribute value pairs that specify the attributes assigned new values by a send_create_req service request operation. The values specified in the send_create_req service function override the corresponding attributes from the reference object (if specified) or from the default value specified in the GDMO definition for the managed object class. Although this is an optional parameter, attribute values must be specified for all mandatory attributes defined for a GDMO managed object class, specified by a default value, by a reference object, or by this parameter.	Optional
const Callback cb	Specifies the name of a callback function invoked when a response to the create request operation is received. Can be used to specify user data passed to the callback function when it is invoked. Callback parameter is optional for the send_create_req function. If specified, a confirmed create request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed create request operation is issued and no response is generated.	Optional
MessId id	Provides a unique identifier for a particular create request operation. If specified, the value for this parameter is generated and set by the send_create_req function.	Optional
const Asn1Value superior_oi	Distinguished name or local distinguished name for an existing superior object under which a managed object is to be created. This optional parameter should not be specified if a value is specified for the oi parameter. The managed object created is contained under the superior object in the MIT.	Optional
const Asn1Value reference_oi	Distinguished name or local distinguished name for a reference object. If this parameter is specified, it must specify the name of a managed object of the same class as the managed object to be created. The attribute values of the reference object become default values for the new managed object for any attributes not specified in the value for the attr_value_list parameter.	Optional
Boolean sub_trans	Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.	Optional
const Asn1Value access	Reserved parameter, not to be used at this time.	Not available

void user-provided-create-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to CreateRes message

**TABLE 9-10** Create Response Callback Parameters
Parameter	Description
Ptr userdata	A void * pointer to data specified by the application developer in the callback parameter of the send_create_req function.
Ptr message	A void * pointer to the CreateRes message generated in response to the send_create_req function.

**TABLE 9-11** send_delete_req Parameters
Parameter	Description	Required/ Optional
const Asn1Value oc	OID that specifies the class of the managed object.	Required
const Asn1Value oi	Distinguished name or local distinguished name for the managed object.	Required
const Callback cb	Specifies the name of a callback function invoked when a response to the delete request operation is received. Can also be used to specify user data passed to the callback function when it is invoked. The callback parameter is optional for the send_delete_req function. If specified, a confirmed delete request operation is issued and the callback function is invoked when the response is received. If not specified, an unconfirmed delete request operation is issued and no response is generated.	Optional
MessId id	Provides a unique identifier for a particular delete request operation. If specified, the value for this parameter is generated and set by the send_delete_req function.	Optional
const MessScope scope	Defines the type of scoping used for this request operation. If not specified, it defaults to BASE_OBJECT_ONLY.	Optional
const Asn1Value filter	Defines a filter to be passed by all objects selected by the scoping parameter. If not specified, it defaults to a filter that matches all managed objects selected by the scope parameter.	Optional
const MessSync sync	Defines the type of synchronization used for this request operation. If not specified, it defaults to BEST_EFFORT.	Optional
Boolean sub_trans	Spawn subtransactions instead of creating new transactions. If sub_trans is not specified, the default behavior is to create a new transaction for the operation.	Optional
const Asn1Value access	Reserved parameter. Do not use now.	Not available

void user-provided-delete-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to DeleteRes message

**TABLE 9-12** Delete Response Callback Parameters
Parameter	Description
Ptr userdata	A void * pointer to data specified by the application developer in the callback parameter of the send_delete_req function.
Ptr message	A void * pointer to the DeleteRes message generated in response to the send_delete_req function.

Doc Set | Contents | Previous | Index

Chapter 9

Object Services API

9.1 Operational Flow

9.2 Service Request Function Parameters

9.3 Service Response Callback Function Parameters

9.4 Services Interface Descriptions and Examples

9.4.1 Get Request Service

9.4.1.1 Get Request Service

9.4.1.3 send_get_request Parameter Descriptions

9.4.1.4 send_get_request Examples

9.4.2 Get Response Callback

9.4.2.1 Interface Signature

9.4.2.2 Get Response Callback Parameter Descriptions

9.4.2.3 Get Response Callback Examples

9.4.3 Set Request Service

9.4.3.1 Set Request Service

9.4.3.3 send_set_request Parameter Descriptions

9.4.4 Set Response Callback

9.4.4.1 Interface Signature void user-provided-set-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to SetRes message

9.4.4.2 Set Response Callback Parameter Description

9.4.5 Action Request Service

9.4.5.2 send_action_req Parameter Descriptions

9.4.6 Action Response Callback

9.4.6.1 Interface Signature void user-provided-action-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to ActionRes message

9.4.6.2 Action Response Callback Parameter Description

9.4.6.3 Action Response Callback Example

9.4.7 Create Request Service

9.4.7.1 Create Request Service

9.4.7.3 send_create_req Parameter Descriptions

9.4.7.4 send_create_req Example

9.4.8 Create Response Callback

9.4.8.1 Interface Signature void user-provided-create-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to CreateRes message

9.4.8.2 Create Response Callback Parameter Descriptions

9.4.8.3 Create Response Callback Example

9.4.9 Delete Request Service

9.4.9.1 Delete Request Service

9.4.9.3 send_delete_req Parameter Descriptions

9.4.9.4 send_delete_req Examples

Delete Request: Base Object Only

9.4.10 Delete Response Callback

9.4.10.1 Interface Signature void user-provided-delete-response-callback( Ptr userdata, // Pointer to user supplied data Ptr message); // Pointer to DeleteRes message

9.4.11 Delete Response Callback Parameter Description

9.4.11.1 Delete Response Callback Examples

9.4.12 Event Report Request Service (Unconfirmed)

9.4.12.2 send_event_req Parameter Descriptions

9.4.12.3 send_event_req Example

9.4.13 Event Report Response Callback

9.5 Supporting Functions for Example Code

9.5.1 Debugging Flags

9.5.2 get_sys_dn Function

9.5.3 get_graphstr_rdn Function

9.4.4.1 Interface Signature

void user-provided-set-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to SetRes message

9.4.6.1 Interface Signature

void user-provided-action-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to ActionRes message

9.4.8.1 Interface Signature

void user-provided-create-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to CreateRes message

9.4.10.1 Interface Signature

void user-provided-delete-response-callback(

Ptr userdata, // Pointer to user supplied data

Ptr message); // Pointer to DeleteRes message