Solstice Enterprise Manager 4.1 C++ API Reference Doc Set ContentsPreviousNextIndex

Chapter 1

Application Programming Interface

This chapter describes how communication between applications can be achieved using Application Programming Interfaces (APIs).

This chapter comprises the following topics:

1.1 API Classes

The APIs addressed in this chapter are Enterprise Manager's Viewer, Grapher, and Application-to-Application APIs. TABLE 1-1 lists the classes described in this chapter.

TABLE 1-1   Application Programming Interface Classes 
Class API Description
AppInstComm Class
 Application-to-Application
Used to establish communication with the platform that communicates with another Solstice EM application
AppInstObj Class
 Application-to-Application
Used to identify the target application for sending message
AppRequest Class
 Application-to-Application
Used to request a single message
AppTarget Class
 Application-to-Application
Used to send messages to applications
EMdataset Class
 Grapher
Stores values or attributes
EMdynamicDataset Class
 Grapher
 Stores attributes of a dynamic dataset
EMgraph Class
 Grapher
Creates new graphs
EMstaticDataset Class
 Grapher
Stores values for graphing statically
Err Class
 Grapher
Provides error checking
ViewerApi Class
 Viewer
Used to communicate with applications running the Solstice EM Network Views tool


1.2 Viewer API

The Viewer API enables applications to communicate with and modify the Solstice EM Network Views tool. Platform developers can leverage both the functionality of the Network Views tool and integrate their applications with the tool. The Network Views tool, therefore, can serve as an application's central location for performing management tasks.

The Viewer API allows the application to do the following:

The Viewer API has only one class: ViewerApi, in AppInstComm, from the Application-to-Application API.

1.3 ViewerApi Class

This section describes the member functions for the ViewerApi class.

1.3.1 ViewerApi Member Functions

Communication is achieved by invoking actions on application instance objects, or targets, corresponding to one or more running Network Views applications. Individual applications are represented as the AppInstObj, which is a member of AppTarget class.

viewerapi_send_request 

static DU viewerapi_send_request(

	 AppInstObj & obj,

	  ViewerApiAction action,

	  DU & action_data =DU()

)

This function sends a synchronous confirmed request to a specified application object and returns data. Zero is returned if there is an error. The action is the operation for the Network Views tool to perform and action_data consists of all parameters to be passed to the Network Views tool. For example, if viewerSetCurrentZoomLevel is the action and action_data is 20 the Network Views tool's zoom level is set to 20%.

viewerapi_start_send_request 

static AppRequest viewerapi_start_send_request(

	 AppInstObj & obj,

	  ViewerApiAction action,

	  DU &action_data =DU()

)

This function sends an asynchronous confirmed request to a specified obj and returns handles for waiting. The action is the operation for the Network Views tool to perform and action_data contains all parameters to be passed to the Network Views tool.

viewerapi_send_request_unconfirmed 

static Result viewerapi_send_request_unconfirmed(

	 AppInstObj & obj,

	  ViewerApiAction action,

	  DU & action_data=DU()

)

This function sends an unconfirmed request to a specified obj, while action is the operation for the Network Views tool to perform and action_data contains all parameters to be passed to the Network Views tool.

viewerapi_build_target 

static AppTarget viewerapi_build_target(

	 Array(DU) & userid = Array(DU)()

)

This function builds the target set of viewer applications to whom API actions are sent. The userid is the system ID of the person running the application.

viewerapi_send_request 

static Array (AppRequest) viewerapi_send_request(

	 AppTarget & target, 

	 ViewerApiAction action,

	 DU & action_data=DU()

)

This function sends a synchronous confirmed request to one or more targets and returns with data. Zero is returned if there is an error. The action is the operation for the Network Views tool to perform and action_data contains all parameters to be passed to the Network Views tool.

viewerapi_start_send_request 

static Array(AppRequest)

ViewerApi::viewerapi_start_send_request(

	 AppTarget & target,

	 ViewerApiAction action,

	 DU & action_data=DU()

)

This function sends an asynchronous confirmed request to one or more targets and returns handles for waiting. The action is the operation for the Network Views tool to perform and action_data contains all parameters to be passed to the Network Views tool.

viewerapi_send_request_unconfirmed 

static Result viewerapi_send_request_unconfirmed(

	 AppTarget & target, 

	 ViewerApiAction action, 

	 DU & action_data=DU()

)

This function sends an unconfirmed request to one or more targets. The action is the operation for the Network Views tool to perform and action_data contains all parameters to be passed to the Network Views tool.

set_indication_handler 

static set_indication_handler(

	 AppEventHandler callback,

	 const DU & pmt

)

This function registers a specific callback function (handler) callback for the event specified by pmt, defined as one of the GDMO PARAMETER templates shown in CODE EXAMPLE 1-1 and CODE EXAMPLE 1-2 in this chapter.

1.3.2 Communication Protocol

Two modes of communication (with an em_viewer application) are supported: confirmed and unconfirmed.

In the confirmed mode, the sender of the request waits for confirmation of receipt from the receiver. After confirmation is received, control is returned to the sender. The sender can also pass data to the receiver with the request, and the receiver can pass data with the response. Both synchronous and asynchronous versions are provided for confirmed requests.

In the unconfirmed mode, the request is sent to the receiving Network Views instance(s). The sender of the request neither requires nor waits for a confirmation of receipt.

Communication with an em_viewer application occurs in a specific order:

  1. A program using ViewerApi sends a request to an em_viewer.

  2. The receiving instance(s) of the Network Views tool gets the notification and performs the action.

  3. The receiving instance of the Network Views tool sends a response to the sending program.

  4. The sending program receives confirmation.

1.3.3 ViewerApi Actions

An application written using the ViewerApi class can communicate with any running viewer applications. All the actions supported by the Viewer API are described by enum ViewerApiAction. For any action requested, each viewer application receiver responds with a reply. TABLE 1-2 summarizes the actions.

TABLE 1-2   ViewerApi Class Defined Actions 
Viewer API Action String Function Request Data Format Reply Data Format
viewerGetCurrentView
 Returns current view.
 N/A
 quoted string
viewerSetCurrentView
 Sets Network Views tool's view.
 quoted string
 status (TRUE or FALSE)
viewerSetFocusObject
 Selects object in Network Views tool.
 quoted string
 status
viewerSetZoomLevel
 Sets zoom level for view.
 int (%)
 status
viewerSetFooterContents
 Places a text string in the Network Views tool's footer.
 quoted string
 status
viewerSetViewCriteria
 Sets which status variable is being used for coloring objects.
 quoted string
 status (TRUE or FALSE)
viewerPopupMessage
 Displays a message box with the appropriate message in the Network Views tool.
 quoted string
 status (TRUE or FALSE)
ViewerPopupQuestion
 Displays a message box with appropriate message in the Network Views tool. Sends response back to the application.
 quoted string
 quoted string--a comma-separated string with 1st parameter TRUE/FALSE and reset the button number clicked beginning from 0)
viewerRegisterForEvents
 Registers interest in Network Views events. (See Section 1.3.4 Event Handling.)
 N/A
 status (TRUE or FALSE)
viewerMarkObject
 Add a mark to the display of listed icons.
 quoted string
 status (TRUE or FALSE)
viewerUnMarkObject
 Remove a mark from the display of listed icons.
 quoted string
 status (TRUE or FALSE)


Note – The viewerSetViewCriteria action is equivalent to selecting a status name in FileCustomizeDisplay Settings...ColorsUser-Defined. You can also pass the argument SEVERITY to select Alarm Severity instead of User-Defined.

You can set icon colors based on values set in topoNodeDisplayStatus attribute of topology nodes. This attribute contains a list of tags and value pairs, for example, {{"CPU", 4}, {"Diskload", 3}}. Use the MIS Objects tool to enable tags by adding them to the topoAllStatus attribute of the object topoNodeDB=NULL. For example, {"CPU", "Diskload"}.

The same color mapping used for severities is used for the user-defined values, so that means the values must be between 0 and 5. You can add additional color mappings by using the MIS Objects tool to expand the range of values.

Note – The request data of the viewerSetCurrentView action expects a view name in the format of system:id. For example, \"myhost:0\".

1.3.3.1 Inputs

The viewerPopupMessageDialog requires the following parameters:

  1. Modality: modal or modeless. [ MODAL | MODELESS ]

  2. Dialog-type: warning, error, information or question:

    [ WARNING | ERROR | INFO | QUESTION ]
    The dialog-type action determines the look of the dialog, including the title and the icon cue used.

  3. Message-text: The text of the message to be displayed in the dialog.

The viewerPopupQuestionDialog requires the same three parameters as the viewerPopupMessageDialog. In addition, the following parameters are required:

  1. num-buttons: The number of buttons in the dialog.

  2. button-labels: A sequence of num-buttons text labels for the buttons, from left to right.

  3. default-button: The position of the default button to activate if the user hits the return key in the dialog. The position is a 0-based integer with 0 being the left-most button.

    Note – A status of TRUE means that the action requested from the Network Views tool was completed successfully; a status of FALSE means that the action requested from the Network Views tool was not completed successfully.

1.3.4 Event Handling

Applications cannot affect only the Network Views tool; they can also listen for Network Views events, and, through callbacks, respond to those events. In this way, an application can use the Network Views tool as a central place for network management.

The general scheme is as follows:

  1. The application tells the Network Views tool of the events in which it has an interest.

    It does this with the AppInstComm:set_indication_handler() method, described in Section 1.3.1 ViewerApi Member Functions."
    For example, assume that the user has written a callback, obj_sel_cb, to do something when a person selects an object in the Network Views tool. set_indication_handler takes the callback as its first argument, and the Network Views event as its second:

    ViewerApi va;	 	 	 	 	 	
 // create ViewerApi object

    va = ViewrApi(em);	 	 	 	 	 	
 // em is the Platform

     // notify Network Views tool we have a callback
     // for object selection

    va.set_indication_handler(obj_sel_cb, duObjectSelectedEvent);

    ob_sel_cb is called when a Network Views tool object is selected.

  2. The application notifies the Network Views tool that it is interested in events.

    The application sets the ViewerAPIAction to viewerRegisterForEvents (described in TABLE 1-2), then calls send_request_unconfirmed() (Section 1.3.1 ViewerApi Member Functions"). The target is the set of viewer applications to which API actions are sent.

    //  set the action to send the Network Views tool to 

    // 'register for events'

    ViewerApiAction v_act = 
va.du2ViewerApiAction("viewerRegisterForEvent");

    //  send the register action to the Network Views tool

    va.viewerapi_send_request_unconfirmed(target, v_act, DU()));

    The syntax for AppEventHandler:set_indication_handler() is:

    typedef int (IAppEventHander)

    (

    	 DU  input_info, 

    	 DU & reply_action, 

    	 DU & reply_info, 

     AppInstObj sender

    )

    viewerRegisterForEvents notifies the Network Views tool that the application is interested in events in general; it becomes an On switch for event notification. The Network Views tool now informs the application of all events, not just the ones that the application has indicated an interest in (in Step1). Of course, the application ignores all events except the ones for which it has callbacks.

  3. The Network Views tool sends events to the application.

    TABLE 1-3 shows the messages that the Network Views tool sends to applications when an event occurs. See Section 1.3.5 Network Views Messages," for more information.

    TABLE 1-3   Network Views Event Messages 
    Network Views Message Data Format Event Described
    duObjectSelectedEvent
         		quoted string
    		 A user selected an object in the Network Views tool.
    duObjectDeselectedEvent
         		quoted string
    		 A user deselected an object in the Network Views tool.
    duPopupMenuEvent
    		 quoted string
    		 A user brought up a Popup menu over an object.
    duLayerChangeEvent
    		 quoted string
    		 The user moved a window onto another, changing the view.
    duToolsMenuEvent
    		 quoted string
    		 The user selected from the Tools menu.
    duObjectCreationEvent
         		quoted string
    		 An object is added to the view being displayed.
    duObjectDeletionEvent
         		quoted string
    		 An object is deselected from the current view.
    duViewChangeEvent
    		 quoted string
    		 The Network Views tool changes the current view.
    duRegisterForEvents
    		 quoted string
    		 Use this to tell the Network Views tool to send the calling application Network Views events.


  4. The registered callback for that event, if any, is called. Note that an application must both:


    1. Notify the Network Views tool of specific events for which the application has callbacks, using set_indication_handler() (Step1).
    2. Notify the Network Views tool that it is interested in receiving events, using ViewRegisterEvents (Step2).

      TABLE 1-4   Using ViewRegisterEvents
      Event Handlers Interest in Receiving Event Notification Registered Interest in Receiving Event Notification not Registered
      Event Handlers Registered
      		Network Views tool sends all events; registered callbacks called (non-registered callbacks ignored).
      		 Network Views tool does not send event messages.
      Event Handlers Not Registered
      		 Network Views tool notifies of all events; all events ignored.
      		 Network Views tool does not send event messages.


1.3.5 Network Views Messages

The following describes the Network Views messages shown in TABLE 1-3. These are messages sent to applications when a Network Views event occurs.

duObjectSelectedEvent

This message notifies the application that a user has selected an object in the Network Views tool.

Input: This message is generated by any form of selection that the user performs in the Network Views tool (including adding an object to the current selection -- that is, selecting a second object without deselecting the first). Also, when the Network Views tool changes back to a previous view that contains already selected objects, messages are sent as if the user had just selected those objects.

Processing: Whenever the Network Views tool performs a selection, it checks for any registered applications and sends them a message. If no applications have registered with the Network Views tool, no message is generated (follows the format: "system_name=unique_id").

Outputs: The action generated is viewerObjectSelection, and the parameter to the action is a quoted string containing the name(s) (format:'system_name:unique_id' ) of the selected objects, separated by commas (for example, "name:id1,name:id2,name:id3").

duObjectDeselectedEvent

This action informs applications when the user deselects objects in the Network Views tool.

Inputs: Any deselection action in the Network Views tool that causes objects to be deselected generates this message. This includes any new selection action that destroys the previous selection; it also includes deleting an object that is already selected. Additionally, it includes changing views. (The Network Views tool maintains selections across views, but the application listening for selection/deselection events doesn't need to do this.)

Processing: Whenever a deselection occurs, the Network Views tool checks for any registered applications and sends them a message. If no applications have registered with the Network Views tool, no message is generated.

Outputs: The action generated is viewerObjectDeselection. Its parameter is a quoted string containing a comma-separated list of the "system_name:unique_ids" of the objects being deselected.

duPopupMenuEvent

This event allows applications to be notified when the user brings up a popup menu item over an object.

Inputs: This message results from any selection, by a user, of an item on a popup menu in the Network Views tool canvas.

Processing: Whenever a popup menu is selected, the Network Views tool determines the object on which the popup menu was "popped," the menu item selected (the label, menu item number, and actual command associated with the popup) and generate a corresponding message. If no applications have registered with the Network Views tool, no message is generated.

Outputs: The action generated is viewerPopupMenu. The parameter accompanying it is a quoted string containing a comma separated list as follows: `topoNodeName,menu label,menu item #,menu command'.

duLayerChangeEvent

This event notifies applications when a user changes the layers currently being displayed in a view (that is, moves a window on top of or underneath another window).

Inputs: Any change of the currently selected layers (including the background image) in the current view via the Layers Dialog produces this message. (Note: this does not include the various "levels" within a geographic map.) Any view change also generates a viewerLayerChange message reflecting the layer flags for the new view.

Processing: When any layer change is detected, the Network Views tool generates a message that formulates a list of all the active layers and whether the background image is on/off and generates a message. If no applications have registered with the Network Views tool, no message is generated.

Outputs: The action generated is viewerLayerChange. The parameter to the message is a quoted string containing a comma-separated list of all of the layers currently being displayed. The first entry in the list always represents the background image and is either "on" or "off," depending on the current value in the Network Views tool.

duToolsMenuEvent

This event notifies applications when the user has selected something from the Tools Menu.

Inputs: The user makes a selection from the Tools menu.

Processing: When the user chooses something from the Tools Menu, the Network Views tool generates a message based on the user's selection. If no applications have registered with the Network Views tool, no message is generated

Outputs: The action generated is viewerToolsMenu. The parameter accompanying the message is a quoted string containing a comma-separated list as follows: `menu label,menu item,menu command'.

duObjectCreationEvent

This event notifies when any new object is added to the current view, either by the Network Views tool or from an alternative source (such as discover). These objects include links.

Inputs: This message is generated when a user creates an object within a view using

Processing: When an object is added to the view being displayed by the Network Views tool, the Network Views tool generates a message. If no applications have registered with the Network Views tool, no message is generated.

Outputs: The action generated is viewerObjectCreationEvent. The parameter accompanying the message is a quoted string containing a comma-separated list as follows: "system_name:unique_id".

duObjectDeletionEvent

This event message informs registered applications when an object is deleted from the Network Views tool's current view.

Inputs: This message is engendered by any object-deletion event occurring from either

Processing: When an object deletion is seen by the Network Views tool, it checks to see if that object is the one currently being displayed by the Network Views tool. If it is, the Network Views tool issues a viewerObjectDeletionMessage.

Outputs: The action generated is a viewerObjectDeletionEvent. The parameter accompanying the messages is a quoted string containing a comma-separated list as follows: "system_name:unique_id".

duViewChangeEvent

This event notifies applications when the user (or another application) changes the view that the Network Views tool is currently displaying.

Inputs: A change of view causes this message to be generated. Either the user of the program can change the view.

Processing: When the Network Views tool successfully changes the view it displays, it generates a message containing the new view name. If no applications have registered with the Network Views tool, no message is generated.

Outputs: The action generated is viewerViewChange. The parameter accompanying the message is a quoted string containing the "system_name:unique_id" of the new view being displayed.

duRegisterForEvents

This message is never sent by the Network Views tool to any application. See event description in TABLE 1-3.

1.3.6 Sample Programs

Sample programs using methods provided by the ViewerApi class are located in the /opt/SUNWconn/em/src/viewer_api directory. For example, the program viewerapi_eventtester.cc gives an example of how to use event handling with the Network Views tool.

For an example of the application instance object of a running Network Views tool, refer to subsystemId="EM-MIS"/emApplicationID=8. The example program, viewerapi_driver, uses the integer 8 to create a singular target ID. Requests can be sent to this target ID.

For more information on actions, refer to the GDMO and ASN.1 documents, em_apps_msg.gdmo and em_apps_msg.asn1.

1.4 Grapher API

A Grapher API is available with Enterprise Manager. It can be used by a client application to send data to the Graphs tool. If the Graphs tool is not running, the API will start it automatically. A grapher library (libemgraphapi.so) by default is located in $EM_HOME/lib, and the header files (EMdataset.hh, EMerror.hh, EMgraph.hh and emgraphrpc.h) are located (by default) in
$EM_HOME/include/grapher.

A graph contains one or more datasets. There are two types of datasets: static and dynamic. The contents of a static dataset cannot be changed after it is created. A dynamic dataset is one which can be updated after it is created. A dynamic dataset can be used to plot a variable that changes with time.

Each dataset is plotted as a three dimensional bar chart by default. The X-axis represents ticks that increase in a linear fashion. Each tick on the Y-axis represents a dataset. The Z-axis represents the variable value for each dataset.

Each graph that is created has a graph name and the name of the client application associated with it. A dataset is registered only once with the Graphs tool when dynamic plotting is used. If you do not intend to use the Graphs tool for dynamic plotting, you can register the same dataset more than once. For example, you might want to do this to display graphs with the same data but with different colors or plot methods (such as absolute, cumulative, and delta) at the same time. The color of a dataset and the plot method can be changed with the Graphs tool. You can define a blank spot in a graph, called a "hole," by specifying a large double value as the Z-value for that point. This value must be set when the dataset is created.

A sample program using the Grapher API is included with the Solstice EM product. The default directory for the sample program is $EM_HOME/src/grapher_api. This directory includes a README file that discusses the sample program as well as the Grapher API.

The Grapher API section includes the following classes:

1.5 EMdataset Class

The EMdataset is a common base class for both EMStaticDataset and EMdynamicDataset.

1.6 EMdynamicDataset Class

An object of the class EMdynamicDataset represents a dataset whose variable value changes with time. A dynamic dataset can be updated with new values.

1.6.1 Constructor

EMdynamicDataset(

	 RWCString  name, //Name of the dataset

	 DynamicMode  mode, //Mode of dynamic display

Where mode is EM_DYN_ABSOLUTE, EM_DYN_CUMULATIVE, or EM_DYN_DELTA for a dataset with absolute, cumulative, or delta values.

This constructor function creates a new dynamic dataset in the Grapher API.

1.6.2 Destructor

~EMdynamicDataset()

1.7 EMstaticDataset Class

The EMstaticDataset class is for storing values to be graphed statically. The values of a static dataset cannot be updated after the dataset is created.

1.7.1 Constructor

EMstaticDataset(

	RWCString  name,	//Name of the dataset

	int  numx,	//Number of X values

	double * xgrid,	//Array of X values

	double * zgrid,	//Array of Z values

	double * zvalues,	//Data values for numx grid points

This constructor function creates a new static dataset in the Grapher.

1.7.2 Destructor

~EMstaticDataset()

1.8 EMgraph Class

The EMgraph class is for creating a new graph. The graph can consist of one or more datasets.

1.8.1 Constructor

EMgraph(

	 char * graph_title, //Title of the graph

	 char * client_name) //Name of the client creating the graph


EMgraph(

	 RWCString  graph_title, //Title of the graph

	 RWCString  client_name) //client creating the graph

These constructor functions create a new graph in the Grapher.

1.8.2 Destructor

~EMgraph()

1.8.3 EMgraph Member Functions

The following are member functions for the EMgraph class.

add_dataset 

EMhandle

add_dataset(EMdataset * 
dataset) //Add a dataset

This function adds a dataset to the graph and returns a handle to the added dataset. The handle is necessary to add new values to the dataset.

Note – To update the dataset, it must be of the class EMdynamicDataset.

add_values 

void add_values(

	 EMhandle  handle  //Handle of the dataset obtained when

	// dataset is added to the graph

	 double  xval,     //X value

	 double  zval,     //Z value

This function adds a new value to a dataset.

draw 

void draw()

This function draws a new graph in the Grapher.

1.9 Err Class

The Err class provides error checking capability. Both EMgraph and EMdataset are inherited from it.

1.9.1 Member Functions

The following are member functions for the Err class.

GetErrType 

ErrType GetErrType() const

This function returns an error type. Error types are listed in EMerror.hh. The sample program under $EM_HOME/src/grapher_api illustrates how to check error conditions.

GetErrStr 

char* GetErrStr() const

This function returns an error string that can be printed or copied.

SetErrType 

void SetErrType(ErrType)

This function sets an error type. The GetErrType function returns the set error type. Error types are listed in EMerror.hh. The sample program under $EM_HOME/src/grapher_api illustrates how to check error conditions.

1.10 Application-to-Application API

The Application-to-Application API uses the following classes to aid communication with the emApplicationInstance object.

The emApplicationInstance object is created for any application that connects to the MIS. An application can send a message to another Solstice EM application through this object using the actions emSendApplicationMessage and emSendApplicationReply.

When an action has been sent to an application instance, the application represented by that particular emApplicationInstance object is notified by either an emApplicationMessage or emApplicationReply event. The emitting of the events to the applications is achieved through the behavior of the emApplicationInstance object.

1.11 AppInstComm Class

This class is used to establish communication with the platform that communicates with another Solstice EM application. All messages are sent and received through an instance of this class.

1.11.1 Constructors

AppInstComm(Platform & platform)

In addition to the default constructor, the above constructor is also available. It constructs an instance that maintains a connection to platform. The platform instance must be in the connected state.

1.11.2 Destructor

~AppInstComm()

1.11.3 AppInstComm Member Functions

The following are member functions for the AppInstComm class.

build_target 

static AppTarget

build_target (

	 DU & apptype,
Array(DU) &  userid = Array(DU)(),
Array(DU) & display = Array(DU)());

This function builds the target set of applications.

DataFormatter

A DataFormatter function can be defined for post- and pre-processing of message data. The function defined as DataFormatter takes the arguments data and action, does some processing, and returns new data.

The action is the PARAMETER defined in GDMO, while data is the string representation of the ASN.1 syntax defined for the PARAMETER. 

typedef DU (*DataFormatter)(DU & data,DU & action)

reply_data_formatter 

static DataFormatter reply_data_formatter

Allows the sender to pre-process the reply data before the sender's callback is executed.

request_data_formatter 

static DataFormatter request_data_formatter

Allows the sender to pre-process the data of the message before sending it to the target application.

indication_data_formatter 

static DataFormatter indication_data_formatter

Allows receiver of a message indication to pre-process the message before the receivers callback is executed.

response_data_formatter 

static DataFormatter response_data_formatter

Allows the receiver of a message to pre-process the message before the reply is sent back to the caller.

send_request 

static DU send_request(

	 AppInstObj & to, 

	 DU & action,

	 DU & info=DU())

Sends the action with data info to the application represented by the AppInstObj class.

send_request_unconfirmed 

static Result 

send_request_unconfirmed(

	 AppInstObj & to,

	 DU & action, 

	 DU & info=DU())

Same as send_request but there is no reply to the message.

start_send_request 

static AppRequest 

start_send_request(

	 AppInstObj & to, 

	 DU & action, 

	 DU & info=DU())

Same as send_request, but the response is asynchronous. Use the AppRequest member functions begin(), wait(), and get_reply_data() with this call.

send_request for multiple targets 

static Array(AppRequest) 

send_request(

	 AppTarget & target, 

	 DU & action, 

	 DU & 
info=DU()

) 

 

static Array(AppRequest) 

 

start_send_request(

 

	 AppTarget & target, 

 

	 DU & action,

 

	 DU & info=DU()

 

)

 

 

static Result 

 

send_request_unconfirmed(

 

	 AppTarget & target, 

 

	 DU & action, 

 

	 DU & info=DU())


  














   These member functions are the same as the 
previous ones, except they are used for sending requests to 
multiple target applications. This is achieved by using the 
AppTarget class instead of the 
AppInstObj class.






   set_indication_handler 



  
  

     

static AppEventHandler 

 

set_indication_handler(

 

	 AppEventHandler callback, 

 

	 const DU & pmt
 

)


  














   This function calls the handler defined by callback when an 
indication of type pmt is received. The 
pmt parameter 
must be defined as one of the GDMO PARAMETER 
templates.






   set_default_indication_handler 




  
  

     

static AppAllEventsHandler

 

set_default_indication_handler(

 

	 AppAllEventsHandler callback)


  














   This function calls the handler callback for any 
application message that is not handled.






   send_response 



  
  

     

static Result 

 

send_response(

 

	 AppInstObj & whosent, 

 

	 int  id,

 

	 DU & reply_action, 

 

	 DU & reply_data)


  














   This member function is called after a successful 
return from an indication handler. This function is not 
called when the sender sends the request in unconfirmed mode. 







   1.12	 AppInstObj Class






   This class is used to identify the application to 
which the predefined messages are sent, and inherits 
properties and methods from the Image class. One instance of this class 
represents one application. 






   This is the class which is used to represent the 
target application for sending messages. If you want to send 
messages to multiple applications at once, use the AppTarget class.






   1.12.1	 Constructors



  
  

     

AppInstObj()


  














   In addition to the above constructor, the 
following also applies to this class.



  
  

     

AppInstObj(int  id)


  














   Constructs an instance of AppInstObj, which represents a 
Solstice EM application. The argument id is the naming 
attribute of the emApplicationInstance object that this 
instance represents.



  
  

     

AppInstObj(DU & fdn)


  














   Constructs an instance of AppInstObj which represents a 
Solstice EM application. The argument fdn is the fully 
distinguished name of the emApplicationInstance object which this 
instance represents. 



  
  

     

AppInstObj( platform&)


  














   Constructs an instance of AppInstObj which represents the current 
application. 



  
  

     

AppInstObj(Image & im)


  














   Constructs an instance of AppInstObj, which represents a 
Solstice EM application. The argument im is an Image that contains the find of the 
emApplicationInstance object, 
which this instance represents. 






   1.12.2	 Destructor



  
  

     

~AppInstObj()


  














   1.12.3	 AppInstObj Member Functions






   get_objname 



  
  

     

DU get_objname() 


  







 






   Returns the fully distinguished name of the 
application object instance represented by this instance of 
AppInstObj. This function is 
inherited from the Image 
class.






   get_oi 



  
  

     

Asn1Value get_oi()


  







 






   Returns the fully distinguished name of the 
application object instance represented by this instance of 
AppInstObj. This function is 
inherited from the Image 
class.






   Note – Other inherited functions like 
get_error, set_error, and reset_error are found in the Image class listings under the 
High-Level PMI classes. Source code references for this class 
and others of the AppInst type are found in the app_com.hh file. 






   1.13	 AppRequest Class






   This class represents one message. The message 
can be synchronous or can be asynchronous waiting to 
complete. 






   1.13.1	  Constructor



  
  

     

AppRequest(AppInstObj & to, DU & action,DU & info,int  id=0)


  














   Destructor



  
  

     

~AppRequest()


  














   1.13.2	 AppRequest Member Functions






   begin 



  
  

     

Result begin() 

 

Result wait(Timeout  
api_timeout = API_DEFAULT_TIMEOUT)


  







 






   begin() and wait() are used in conjunction with 
asynchronous send_request 
functions. begin() calls the 
request function and wait() 
blocks until the reply has been received for the 
message.






   get_reply_data 



  
  

     

DU get_reply_data()


  














   After a wait() has 
returned from an asynchronous send_request, get_reply_data() is used to get the 
message data.






   get_receiver 



  
  

     

AppInstObj get_receiver()


  














   Gets the AppInstObj 
that represents this AppRequest. 
This can be used when multiple replies are received.






   get_action 



  
  

     

DU get_action()


  














   Gets the name of the message type which 
corresponds to this AppRequest. 
The DU returned contains a GDMO PARAMETER template 
name.






   is_complete 



  
  

     

int is_complete()


  














   Returns 1 means the 
AppRequest is completed, a reply 
has been received. Returns 0 
means the reply has not been received. This can be used in 
conjunction with the asynchronous send_request methods. 






   1.14	 Actions






   The emSendApplicationMessage action is used 
to send a message to an Solstice EM application 
represented by the emApplicationInstance object to which 
the action is sent.






   Syntax:



  
  

     

EMSendApplicationMessage ::= SEQUENCE {

 

messageId       EMMessageID,

 

messageType     EMMessageType,

 

message         ANYDEFINEDBY messageType

 

}


  














   messageId EMMessageID 
(INTEGER): Agreed-upon identifier for message.






   messageType (OBJECT 
IDENTIFIER): This parameter is an OID for a PARAMETER type defined in GDMO. The 
parameter defines what the ASN.1 syntax is for the specified 
message type.






   emSendApplicationReply: This action 
allows a Solstice EM application to send a reply to the 
Solstice EM application represented by this 
emApplicationInstance object.






   The syntax is the same as for emSendApplicationMessage.



  
  

     

emSendApplicationReply ::= SEQUENCE

 

messageId       EMMessageID,

 

messageType     EMMessageType,

 

reply           ANYDEFINEDBY messageType

 

}


  














   The messageType, 
message, and reply fields for these actions must be 
agreed upon between applications.






   1.15	 Notifications






   The emApplicationMessage notification is 
emitted when another application performs an emSendApplicationMessage action on an 
emApplicationInstance object. 



  
  

     

EMApplicationMessage ::= SEQUENCE {

 

sender              EMApplicationOI,

 

COMPONENTS OF               EMSendApplicationMessage

 

}


  














   sender OBJECT INSTANCE: The fdn of the 
emApplicationInstance of the 
application which triggered the action.






   COMPONENTS OF EMSendApplicationMessage: This contains 
the messageID, messageType, and message data that was part of 
the original action. 






   emApplicationReply: 
This notification is emitted when another application 
performs an emSendApplicationReply action on an 
emApplicationInstance object. 







   Syntax:



  
  

     

EMApplicationReply ::= SEQUENCE { 

 

sender              EMApplicationOI,

 

COMPONENTS OF               EMSendApplicationReply

 

} 


  














   Both of these notifications contain the same 
information from the original action, and also identify the 
application that sent the action.






   1.16	 Example






   Suppose you have two applications that want to 
keep track of each other. You have decided the best way to do 
this is to use an application-to-application "ping" 
function.(See CODE EXAMPLE 1-1 and 
CODE EXAMPLE 1-2 
for such an application.)






   You need two messages for the application: appHello and appAlive.






   Following are the steps to be followed.





 	1.	 Define the GDMO PARAMETER 
templates for these messages.


  

     
  The sample below indicates how you can 
define these templates.



  
  

     

MODULE "EM APP PING"

 

 

appHello PARAMETER

 

	 CONTEXT  ACTION-INFO;

 

	 WITH SYNTAX  FORUM-ASN1-1.GraphicString30;

 

	 BEHAVIOUR appHelloBehaviour;

 

 

REGISTERED AS { 1 2 3 4 5 6 90 };

 

 

appHelloBehavior BEHAVIOUR

 

 

DEFINED AS

 

	 !Ping hello message for app to app communication!;

 

 

appReply PARAMETER

 

	 CONTEXT  ACTION-INFO;

 

	 WITH SYNTAX FORUM-ASN1-1.GraphicString30;

 

	 BEHAVIOUR appReplyBehaviour;

 

 

REGISTERED AS { 1 2 3 4 5 6 91 };

 

 

appReplyBehaviour BEHAVIOUR

 

 

DEFINED AS   

 

	 !Ping reply message for app to app communication!;

 

 

END


  








  



 	2.	 Compile the GDMO into the 
MIS.



  
  

     

hostname% em_gdmo 
 
hostname app_ping.gdmo


  











 	3.	 Write a driver and a 
listener application. 


  

     
  The driver sends the appHello message with a GraphicString30 
string as data. The listener replies with an appReply message containing a 
GraphicString30 string as data. Make sure to link with libappapi.so.
  



 	4.	 Start the listener 
first.


  

     
  The listener prints out its 
application ID. Run the driver with the ID of the listener as 
arg1. 
  



  
  This is one way to identify what 
application you want to communicate with. You can also 
dynamically send messages to applications based on their 
names and what user started them. See the sample programs for 
more information.


 CODE EXAMPLE 1-1 	
  Listener Application



  
  

     

// Listener Application for App2App API

 

 

#include <hi.hh>

 

#include "app_comm.hh"

 

 

Platform plat;

 

int handler(DU,DU&,DU&);

 

 

main(int argc, char **argv)

 

{

 

        plat = Platform(duEM);

 

        char *host = "localhost";

 

        printf("Connecting to %s ... ",host);

 

        if (!plat.connect(host, "sample_app2app")) {

 

                printf("Connect failed\n")
                

 

", plat.get.error.string());

 

                exit(0);

 

        }

 

        printf("Connected. \n");

 

        AppInstComm app(plat);

 

        AppInstObj::appObj(plat);

 

        printf("ID %s\n",appObj.get_objname().chp());

 

        app.set_indication_handler( handler,"appHello");

 

        while (1)

 

                dispatch_recursive(TRUE);

 

}

 

 

int

 

AppEventHandler(

 

        DU input_info,

 

        DU &reply_action,

 

        DU &reply_info,
        AppInstObj sender 
)

 

{

 

        printf("Message Received %s\n",input_info.chp());

 

        reply_action = "appReply";

 

        reply_info = "\"I am alive\"";

 

        return 1;

 

}


  










   



 CODE EXAMPLE 1-2 	  Driver Program for Listener Application



  
  

     

//Driver Program for App2App API

 

 

#include <hi.hh>

 

#include "app_comm.hh"

 

 

Platform plat;

 

 

main(int argc, char **argv)

 

{

 

	 if (argc != 2) { 

 

                printf("Usage: <listener_id>\n"); 

 

                exit(1); 

 

        } 

 

        plat = Platform(duEM);

 

        char *host = "localhost";

 

        printf("Connecting to %s ... ",host);

 

        if (!plat.connect(host, "sample_app2app")) {

 

                printf("Connect failed\n");

 

                printf("Reason:%ln", plat.get.error.string());

 

                exit(0);

 

        }

 

        printf("Connected. \n");

 

        AppInstComm app(plat);

 

        char    action[500];

 

        char    info[500];

 

        strcpy(action , "appHello");

 

        strcpy(info , "\"Hello there\"");

 

        AppInstObj to(atoi(argv[1]));

 

        DU reply;

 

        reply = app.send_request(to,DU(action),DU(info));

 

        printf("Reply is %s\n",reply.chp());

 

}


  










   






   1.17	 AppTarget Class






   This class is used for sending messages to a set 
of applications based on the application name and user IDs, 
and inherits properties and methods from the Album class. An instance of this class 
can represent a group of applications or a single 
application.






   1.17.1	 Constructor



  
  

     

AppTarget(

 

	 int  id, 

 

	 DU & apptype, 

 

	 Array(DU) & userid = Array(DU)(), 

 

	 Array(DU) & display = Array(DU)()); 


  














   Constructs an AppTarget instance that represents a 
set of applications based on the apptype and userid. The apptype is the name of 
the application set in the Platform::connect() method. The userid is an array of the UNIX logins of 
the users who connect to the platform.






   1.17.2	 AppTarget Member Functions






   The following are member functions for the AppTarget class.






   num_objs 



  
  

     

int num_objs()


  














   Returns the number of applications represented in 
the AppTarget instance.






   first_obj 



  
  

     

AppInstObj first_obj()


  







 






   Returns the first AppInstObj in the AppTarget instance. The AppInstObj can then be used in a AppInstComm::send_request() 
method.






   next_obj 



  
  

     

AppInstObj next_obj()


  














   Returns the next AppInstObj in the AppTarget instance. The AppInstObj can then be used in a AppInstComm::send_request() 
method.






   Note – Other inherited functions like 
get_error, set_error, and reset_error are found in the Album class listings under the 
High-Level PMI classes. Source code references for this class 
and others of the App class type are found in the app_com.hh file. 






   

















Sun Microsystems, Inc.

Copyright information. All rights 
reserved.






Doc Set  |  
Contents
  |  
Previous
  |  
Next
  |  
Index