[Top] [Prev] [Next] [Bottom]

2 - Registering for Data, Event, and Trap Reports

A management application can receive data, event, and trap reports from agents. It does not have to be able to send agent requests to receive reports from them. For data reports, the application sending the request to the agent has to specify your application as the recipient of the report. For event reports, the manager application always specifies an event dispatcher as the recipient of the report. Your application registers with the event dispatcher for specific kinds of event reports or traps. When the event dispatcher gets a report, it redistributes the event report or traps to all the applications it knows are interested.

NOTE - Agents do not know data reporting from event reporting; the facility is handled by the Agent Services library.

2.1 Background

To register for data, event, or trap reports, you must register your application's RPC service with the local portmapper, the porting utility described in the portmap (8) man page. This requires an RPC program/version number pair to identify the service. While it is possible for a manager application to have a static RPC program/version number pair, usually the application gets a temporary (or transient) RPC program/version number by calling netmgt_register_callback (3n). This function will obtain a transient service pair and register it with the portmapper.

NOTE - In the example program in Section 2.7, "Sample Code," on page 2-6 , you see that the protocol parameter for netmgt_register_callback() is set (correctly) to IPPROTO_UDP|IPPROTO_TCP. As a result of this, UDP transport is used for messages of 6144 bytes or less; TCP transport is used for messages longer than 6144 bytes. Because of this feature, if you registered, for example, only with UDP, you would not receive any large reports. If there is a possibility that you will receive reports larger than 6144 bytes, you should register with both TCP and UDP.
This "registration" is called the RPC program number, and is the basis for communication.

It is possible to register more than one function per process. For instance, you might have one function to handle data reports, another function to handle high priority event reports from the ping agent, and a third function to handle all other event reports. Because you register with a particular event dispatcher, it is possible to register with more than one at a time. You do this by calling netmgt_register_callback (3n) once for each callback function or for each event dispatcher.

NOTE - Error reports can be returned for any report request. You do not need to register for error reports. However, your manager application must be able to handle incoming error reports. See Chapter 3, "Getting Data, Event, and Trap Reports ," and Chapter 6, "Handling Error Reports ," for more information.

2.2 Data Reports

As described above, your application needs an RPC program number to get reports. When a manager application sends a request to an agent, it must specify your application as the rendezvous for you to get the resulting data report. Generally applications either direct their data reports to a cooperating rendezvous or to a general-purpose logger facility. Figure 2-1 illustrates this model.

Your application only need call svc_run (3n) (discussed below) to get data reports.

Figure  2-1 Data Reporting

2.3 Event Reports

Because manager applications are in general more interested in event reports, it is useful to have a central rendezvous for receiving them. The event dispatcher acts as a clearinghouse for event reports. When manager applications ask agents to send event reports, they should direct them to the local event dispatcher--an agent with a a known RPC program number--who will redistribute the reports to all interested processes.

To register with the event dispatcher, call netmgt_register_rendez (3n) with the appropriate parameters to describe the type of event reports you are interested in getting. Figure 2-2 illustrates several applications registered with the event dispatcher.

Figure  2-2 Event Reporting

2.4 Trap Reports

Traps are asynchronous or unrequested reports. Trap reports are sent to the event dispatcher, which then forwards traps and event reports to any registered manager application.

Trap reports can be generated by agents. For example, the SNMP trap daemon (na.snmp-trap) receives SNMP traps and sends them to the event dispatcher. Trap reports can also be generated by applications that use the database API functions to add, change, or delete elements in the database. In this case, low-priority trap reports are sent to the event dispatcher.

To register with the event dispatcher, call netmgt_register_rendez (3n) as you would to register your application to receive event reports. Figure 2-3 illustrates several applications registered with the event dispatcher for trap reports.

NOTE - If you only want to receive trap reports from changes in the database, specify NETMGT_DBMGR_PROG for the agent_prog argument in the netmgt_register_rendez (3n) call. No other event or trap reports will be sent from the event dispatcher.

Figure  2-3 Trap Reporting

2.5 Waiting for Reports

Once you have registered as a rendezvous, you should call the RPC function svc_run (3n), which never returns. It causes your registered callback function to be called when a report arrives for your application.

2.6 Summary


1. Call netmgt_register_callback (3n) to get and register a transient callback RPC program/version number pair.


2. Call netmgt_register_rendez (3n) if you are interested in receiving event reports from the event dispatcher.


3. Call svc_run (3n) to wait for reports.

2.7 Sample Code

The following code fragment shows an example of registering a single function to handle both data and event reports. The complete program example from which this fragment is taken is included in the product structure in the following file event_display.c in the API_examples directory. 




main(int argc, char *argv[])
 
{
 
        (void) signal(SIGINT, sigint);
 
        (void) signal(SIGTERM, sigint);
 
 
        /* get my hostname */
 
        gethostname(myname, MAXHOSTNAMELEN);
 
        /* Create a transient RPC program number using any UDP and TCP socket*/
 
        sock_udp = RPC_ANYSOCK;
 
        sock_tcp = RPC_ANYSOCK;
 
        /* Register the function "report_handler " as the function to be called
 
         * for any report sent to the RPC program number returned in variable
 
         * "rendez"
 
         */
 
        if (!(rendez = netmgt_register_callback(report_handler, &sock_udp,
 
                &sock_tcp, NETMGT_VERS, IPPROTO_UDP | IPPROTO_TCP))) {
 
                (void) fprintf(stderr, "Can't register callback: %s\n",
 
                                netmgt_sperror());
 
                exit(CALLBACK_ERR);
 
        }
 
        /* Register the program identified by "rendez" with the local
 
         * event dispatcher in so the function "report_handler" will get
 
         * event reports too
 
         */
 
        if (!netmgt_register_rendez(myname, myname, rendez, NETMGT_VERS,
 
                NETMGT_ANY_AGENT, NETMGT_LOW_PRIORITY, timeout)) {
 
                (void) fprintf(stderr,
 
                        "Can't register with the event dispatcher: %s\n",
 
                        netmgt_sperror());
 
                netmgt_unregister_callback(rendez, NETMGT_VERS);
 
                exit(RENDEZ_ERR);
 
        }
 
        printf("%s: starting\n", argv[0]);
 
        /* wait for the reports to come in */
 
        svc_run();
  


[Top] [Prev] [Next] [Bottom]

Copyright 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All Rights Reserved