i pc example

7/28/2019 i Pc Example

1/18


2/18

I PC Example

Table Of Contents

IPC REFERENCE IMPLEMENTATION ..................................................................... 2

Introduction.......................................................................................................................... 2

Requirements ...................................................................................................................... 3

Application Notes................................................................................................................. 4

IPC COM MIB...................................................................................................................... 6

Generated Code .................................................................................................................. 7

External Application............................................................................................................. 8

Instrumentation.................................................................................................................. 10

Request Processing........................................................................................................... 15

Running the Example ........................................................................................................ 17

AdventNet Inc . 1


3/18

I PC Example

IPC Reference Implementation

Introduction

This document explains the implementation of the Multi-Protocol Agent with No Storage option. In thisimplementation, the real data is maintained by an external application, which may be any userapplication. Since, the data is not held by the Agent when a request is made, the Agent has tocommunicate with the external application to get the data and send back the response to theManager.

You would like to implement a no storage Agent of a similar type. But you may not know how to makethis Agent communicate with the external application, send the request, and get back the responsefrom the external application. This document guides you to implement this process with the help of anexample.

Objectives of the Implementation

The main objective of this implementation is to provide you a clear understanding of thecommunication process between the no storage Agent and the external application. Hence, the focuswith reference to this implementation will be on the following areas:

Instrumentation of the No Storage Agent Request Processing Running the Example and Testing the Agent

Getting Started

To get started with this implementation, please go through the following sections in the order in whichthey are specified :

The Requirements topic lists down the basic requirements for working with thisimplementation.

The Appl ication Notes explains the application that is taken up for this referenceimplementation.

The Generated Code topic deals with the files that are generated by default for thisimplementation.

The External Appl ication topic explains the external application and the functions defined forimplementing this example.

Instrumentation explains the process of adding the actual functionality to the generatedcode, for implementing the ipc agent through sockets or through message queues. Request Processing explains how a get/get-next/set request is processed. Running the Example provides the basic steps involved in running this example.

AdventNet Inc . 2


4/18

I PC Example

Requirements The following are the basic requirements for this implementation:

Hardware

Memory: Minimum 128 MB RAM CPU: Minimum 266 MHz Pentium Processor Disk Space: Minimum of 100 Mega Bytes hard disk space

Software

Operating System: Any OS which supports sockets or Message queues. AdventNet Agent Toolk it C Edition, Release 6: Please download the same from our Web

site, www.adventnet.com and install it. Follow the instructions given for installation and setupof the toolkit, in the Release 6 P roduct Help documentation.

C/C++ Compil er: Supports Microsoft Visual C++4.0 onward or Borland C++4.0 onward forWindows. GNU C or C++compiler (any version) for UNIX platform.

Others Requirements

Refer to the section, "Generated Code Structure" under "Building Multi-Protocol Agent" in ourProduct Help Documentation to get an idea about the files generated, the methods present inthese files, and their functionality.

Knowledge in Socket programming.

AdventNet Inc . 3


5/18

I PC Example

Application NotesIn this application, the Agent is implemented as a "No Storage Agent" and the data are held by anexternal application. When any request is sent by the Manager, the Agent contacts the externalapplication, retrieves the data, and sends back the response to the Manager. Hence, theimplementation involves two modules: Agent application and External application.

The communication between the Agent and the resources in the external application are through InterProcess Communication (IPC). This is done through message queues or udp sockets. The Agentsends the request message to the external application through a UDP Socket or message queue. Theexternal application reads this message and sends the response to the agent application. Now theagent reads this response message and sends it back to the manager.

The architecture given below explains the communication between the Manager, Agent, and theExternal Application.

What Is a Socket?

A socket is an end point for communication. The IPC operations are based on socket pairs, onebelonging to a communication process. IPC is done by exchanging some data through transmittingthat data in a message between a socket in one process and another socket in another process.When messages are sent, the messages are queued at the sending socket until the underlying

network protocol has transmitted them. When they arrive, the messages are queued at the receivingsocket until the receiving process makes the necessary calls to receive them. A call to the socket()system routine returns the socket descriptor, and you can communicate through it using thespecialized send() and recv() socket calls.

What Is a Message Queue?

Message queues can be best described as an internal linked list within the kernel's addressing space.Messages can be sent to the queue in order and retrieved from the queue in several different ways.Each message queue (of course) is uniquely identified by an IPC identifier.

Note: In this example, we are using IPC for communication between the agent and the userapplication. Other modes of communication, such as Serial port communication, devicedriver communication, or proprietary methods can also be used.

AdventNet Inc . 4


6/18

I PC Example

Agent Appl icat ion

The following are the important features of the Agent application : It acts only as an interface and does not contain any data. It contains the source files for SNMP/HTTP/TL1 operations and functionality. It contains generated code for the IPCCOM.Mib MIB. It contains the modified code to support UDP communication.

External Appl ication

The following are the important features of the External Application :

The external application may be any existing software which is designed to perform someprocessing for the system (device/printer).

The Real data to be managed is available in this application. Request processing takes place between the agent application and external application.

AdventNet Inc . 5


7/18

I PC Example

IPC COM MIBIn this example, the resources to be managed by the agent are defined in the IPC-COMMUNICATION-MIB. The Agent application implements this MIB which contains a table ipcTablewith the following columns in it:

Table ColumnNames Usage

ipcldx The index column for the table of type integer and access as read-only.

ipcCount It is of type Integer and access as read-write.

ipcTime The time at which the request is made. It is of type timeticks and accessas read only.ipcStatus It is of type rowStatus and access as read-write.

AdventNet Inc . 6


8/18

I PC Example

Generated Code The following files get generated under . /projects/projectname/agent/stubs/ipc-communication-mib/src directory for IPC-COMMUNICATION-MIB :

ipccommunicationmib.c: This file contains all the init methods of the generated MIB andFreeResources Method.

ipctablehdlr.c: The basic functionality of this file is to register the module with the Agent and to handle all requests, such as GET, GET-NEXT, SET from the Managers.It also handles row creation and deletion in case of tables.

ipctableinstru.c : This file contains a get method for all table columns and a set method foreach scalar and table column provided they have read-write or read-create access. Thefunctions defined in this file will be called from the handler file whenever a GET,GET-NEXT,and SET request is received from the Manager.

In the Instrumentation topic, you will see how the methods present in the generated handler files areinstrumented for communicating with the external application.

AdventNet Inc . 7


9/18

I PC Example

External Application

Functions Defined in the External Appli cation (ipcext.c)

In this implementation, the external application is only a simulation . It is a separate entity and has to

be compiled and started separately.

Data Maintained by the External Appl ication

The external application maintains the ipctable as an array of structures. The structure template issimilar to the table maintained by the Agent as shown below. The user table initially maintains fiverows of data.

s t r uct i pcEnt r y{

I NT32 i pcI dx;I NT32 i pcCount ;LONG i pcTi me;

I NT32 i pcSt at us;};

In the external application, the macro for using Sockets/message queues is defined in the fileipcext.c .

Functions Defined fo r IPC Implementation Using Message Queues

1. ReadMessage()

This function reads the message from the message queue. It takes the following inputs:

qI d : The message queue I d. of t ype i nt eger .qBuf : The poi nt er t o t he message st r uct ur e

This function is used for reading the message from the Agent by the external application and returningthe received message. The function call msgrcv() is used for receiving the message.

2. ProcessAndSendQueueMessage()

This function is used to process and send the message from the agent to the external application . Ittakes the following inputs:

qI d : The message queue I d. of t ype i nt eger .qBuf : The poi nt er t o t he message st r uct ur e.t ext : The act ual message whi ch i s of t ype st r i ng

This function sends the message as Type2 as shown below:

qbuf - >mType = 2;

The other values of the message structure are filled up and sent using the function call:msgsnd() .

AdventNet Inc . 8


10/18

I PC Example

Functions Defined for IPC Implementation Using Sockets

1. ReadAndProcessUDPMessage()

This function reads the message from the client application and processes it according to the receivedinformation. It takes the following inputs:

SOCKET sockFdstruct sockaddr_in *sockAddr

The function call recvfrom() is used for receiving messages. After receiving the message from theAgent, the application processes it based on the type of the request and the message. In thisexample, the external application has 5 rows by default. The constraint found in the externalapplication in this example are:

Number of rows that can be added cannot exceed 10 with index values 1 to 10.

AdventNet Inc . 9


11/18

I PC Example

Instrumentation

Overview Using Instrument Files Using Header Files Newly Added Files Instrumentation Using UDP Sockets

o Defining a Message Structure

o Creating a Socket

o Binding the Socket

o Sending the Message to the External Application through the Socket

o Receiving the Message from the External Application through the Socket Instrumentation Using Message Queues

o Defining a Message Structure

o Creating the Message Queue

o Sending the Message to the External Application through the Message Queue

o Receiving the Message from the External Application through the Message Queue

Overview

This topic discusses the generated files of the agent application and their instrumentation to get thedata from the external application. Instrumentation can be done in two ways : Using Instrument files or Using Handler Files

Using Instrument Files

This file is generated for each table or scalar group of the MIB. It contains the set/get methods foreach variable defined in the Mib. Here, you can add the necessary code to contact the externalapplication and get the data. The disadvantage of instrumenting the instru.c files are

a. In case of Multi-Varbind request, the Agent has to contact the external application for eachvarbind.b. Instrumentation has to be done for each get/set method.

Using Handler Files

This file is generated for each table or scalar group of the MIB. It handles all requests, such as GET,GET-NEXT, and SET from the Managers. Here, you can add the necessary code to contact theexternal application and get the data. The advantages of instrumenting the handler files are

This file defines the Process Requests method from which you can knowthe set of table column/scalars received for a listener. Using these inputs, you can call yourapplication method and update the local data structure simultaneously.

In this example, instrumentation is done in the generated handler files. In addition, new filesare added for implementing this example.

AdventNet Inc . 10


12/18

I PC Example

Newly Added Files

In this implementation, we have defined a new header file ipcext.h which defines the macros neededfor IPC Communication. The example by default implements SOCKETS. The macro SOCK_IMPLdefined in this file specifies that the implementation is through SOCKETS. If this macro is not defined,then the implementation is through Message Queues. The external application socket is listening atport 9001 for requests from the agent application at 8005. The port numbers are defined under themacro's TARGET_PORT and CLIENT_PORT in ipcext.h .

In this example, we have implemented the ipc agent using sockets and message queues. Hence,instrumentation is dealt with in separate headings as shown in the link below:

Instrumentation Using Sockets Instrumentation Using Message Queues

Instrumentation Using UDP Sockets

In order to communicate with the external application, the files and methods generated in the agentapplication has to be instrumented to get the required functionality. The ipcext.h file is defined whichdeclares the necessary macros, the message structure, and functions. The ipctablehdlr.c file isinstrumented by adding new methods to create the message queue, to send messages to the externalapplication, and receive messages from the external application.

The following are the steps to instrument the IPC Agent using sockets: Defining a Message Structure Creating a Socket Binding the Socket Sending the Message to the External Application through the Socket Receiving the Message from the External Application through the Socket

a. Defining the Message Structure :

The communication between the agent and the external application is in the form of amessage. Hence, the first step is to define the structure of the message to be communicated.

The structure of the message, when it is transferred from the agent application to theexternal application, is defined in the ipcext.h file.

Request TypeText Message.I NT32 r eqType; / * 0 - GET / 1 - GET- NEXT / 2 - SET*/CHAR t ext [ 400] ;

The st r uct ur e of t he message, when i t i s t r ansf er r edf r om t he ext er nal appl i cat i on andt he agent appl i cat i ons, i sRet ur nTypeText Mess age.I NT32 r et Type; / * 0 - FAI LURE / 1 - SUCCESS */CHAR t ext [ 400] ;

b. Creating a Socket

In this example, the message to be communicated is through sockets. Hence, the next stepis to create a socket. The agent application creates a socket and binds it with a name in theInitIpcTable() function of ipctablehdlr.c . The global variable gv_ipcSockFd is defined in theheader file ipcext.h . An UDP socket is created and the descriptor is stored in the variablegv_ipcSockFd.

AdventNet Inc . 11


13/18

I PC Example

/ * Cr et es a UDP socket . */gv_i pcSockFd = socket ( AF_I NET, SOCK_DGRAM, 0) ;i f ( gv_i pcSockFd < 0)

{pr i nt f ( " Unabl e t o open socket on por t number %d

" ,CLI ENT_PORT) ;exi t ( 0) ;

}

c. Binding the Socket

After creating a socket, the socket is given a name by using the bind () call.

The gv_ipcSockAddr is declared in the header file ipcext.h . The macro's CLIENT_PORTand CLIENT_HOST are also defined in the header file ipcext.h . The values of CLIENT_PORT and the CLIENT_HOST are by default 8005 and 127.0.0.1 respectively.

gv_i pcSockAddr . si n_f ami l y = AF_I NET;gv_i pcSockAddr . si n_por t = ht ons( CLI ENT_PORT) ;gv_i pcSockAddr . si n_addr . s_addr =i net _addr ( CLI ENT_HOST) ;i f ( bi nd( gv_i pcSockFd, ( st r uct sockaddr*) &gv_i pcSockAddr ,si zeof ( gv_i pcSock Addr ) ) ! = 0)

{pr i nt f ( "Probl em i n bi nd\ n" ) ;p e r r o r ( " ! ! ! ! " ) ;exi t ( 0) ;

}

Now, we have defined a message structure, created a socket, and given a name for thesocket using the bind function. The next step is to send the message using the socket.

d. Sending the Message through the Socket

The function SendUDPMessage() is added in the ipctablehdlr.c file to create and send amessage from the agent application to the user application through sockets. The prototype of this function is void SendUDPMessage(CHAR *text, INT32 type) .

This function takes the following inputs :o text: The actual message which is of type string.

o reqType: The request type which is of type integer.

It creates the message by using this function and then it uses the sendto () call to send thismessage to the user / external application.

e. Reading the Message

Now, the agent application has to receive the message from the external application . Thefunction ReadUDPMessage() is added in the ipctablehdlr.c file to read and process thereceived message from the external application. The prototype of this function is

CHAR ReadUDPMessage( I NT32 * i ndOut )

This function uses the recvfrom () call to receive the message from the user / externalapplication.

AdventNet Inc . 12


14/18

I PC Example

Instrumentation Using Message Queues

To communicate with the external application, the files and methods generated in the agentapplication have to be instrumented to get the required functionality. To implement the IPC agentusing message queues, the ipcext.h file is defined which declares the necessary macros, themessage structure, and functions. The ipctablehdlr.c file is instrumented by adding new methods tocreate the message queue, to send messages to the external application, and to receive messagesfrom the external application. The following are the steps involved to instrument the IPC agent usingmessage queues:

Defining a Message Structure Creating the Message Queue Sending the Message to the External Application through the Message Queue Receiving the Message from the External Application through the Message Queue

Defining a Message Structure

The structure of the message is defined in ipcext.h as shown below :

st r uct myMsgBuf {

LONG mType;CHAR r eqType; / * 0 - GET / 1 - GET_NEXT / 2 - SET */CHAR mText [ 400] ;CHAR r et Type; / * 0 - FAI LURE / 1 - SUCCESS */

};

In the above message structure

mType: Type of the message (1 or 2). reqType: 0 for type GET, 1 for type GET-NEXT, and 2 for type SET specified by the agent. mText: The message content. retType: 1 for Success or 0 for Failure specified by the external application.

Creating the Message Queue

The Agent application creates the message queue in the InitIpcTable() function. The functionmsgget() creates a message queue and opens it if it does not exist . If the queue already exists, itopens the queue. This function returns the queue ID. The following code can be specified in the init function call of the MIB. In this example, the code is specified in the InitIpcTable function of theAgent. The agent and the external application communicate through a common Key 006.

/ * Open t he queue - cr eat e i f necessar y */i f ( ( gv_msgQueueI d = msgget ( KEY, I PC_CREAT| 0660) ) == - 1)

{per r or ( " msgget ") ;exi t ( 1) ;

}

AdventNet Inc . 13


15/18

I PC Example

Sending the Message through the Message Queue

The function SendQueueMessage() is added in the ipctablehdlr.c file to send the message from theagent to the external application using message queues. It takes the following inputs:

SendQueueMessage( I NT32 qi d, st r uct myMsgBuf *qBuf , CHAR r eqType, CHAR *t ext )

qId: The message queue ID of type integer. qBuf: The pointer to the message structure. reqType: The request type which is of type character. text: The actual message which is of type string.

This function sends the message as type1 as shown below:

qBuf - >mType = 1;

The other values of the message structure are filled up and sent using the function call msgsnd() .

Reading the Message from the Message Queue

The function ReadQueueMessage() is added in the ipctablehdlr.c file to read the message from themessage queue. The prototype of the function is

CHAR *ReadQueueMess age( I NT32 qi d, st r uct myMsgBuf *qBuf )

This function takes the following inputs:

qId: The message queue ID of type integer. qBuf: The pointer to the message structure.

This function is used to read the message from the external application by the agent and returns thereceived message. The function call msgrcv() is used to receive the message. The agent writes themessage into the queue as Type1. The external application reads this message and writes theresponse into the queue as Type2. Now the agent reads this message with Type2 and sends back theresponse to the manager.

AdventNet Inc . 14


16/18

I PC Example

Request Processing

Processing a GET Request Processing a GET-NEXT Request Processing a SET Request

Processing a GET Request

When a get request is sent by the Manager to the Agent

The Agent API calls the IpcTableProcessRequests() in the ipctablehdlr.c file. The above function processes the request and in turn calls the

SendMessageToExternalApplication() . This in turn calls the following method which sends the message to the external application:

o SendUDPMessage() in case of sockets.

o SendQueueMessage() in case of message queues. Next, the function ReadMessageFromExternalApplication() is called which in turn calls the

following method which receives the message from the external / external application whichcontains the values of the row.

o ReadUDPMessage() in case of sockets.

o ReadQueueMessage() in case of message queues.

The function ReadUDPMessage() then stores the value in the table gv_ipcTableVector() through the function call CreateAndAddNewIpcTableEntry() .

For example, for the column variable "ipcTime", the external application returns the time at which therequest is made. It then stores them in the table gv_ipcTableVector() .

When the request is made for a specified index, the index is sent to the external application . Theexternal application searches the corresponding row for the specified index. If the index matches withthe given index, it retrieves the corresponding column's row value and returns "1" to the variable typeretType in the message structure. If the index does not match with the given index, it returns "0" to thevariable retType in the message structure.

In this implementation, the index column ipcIdx is of type string. The agent will retrieve the columnvalues from the text variable in the message structure and will create a row in the table withcorresponding column values.

Processing of a GET-NEXT Request

The process for a get-next request is same as get request. In this case, the index is incremented by 1and sent to the user application. If there is no corresponding row in the external application for thespecified index, the external application finds the next index available in the table and returns thecorresponding row to the agent. For the column variable "ipcTime", the external application returnsthe time at which the request is made.

AdventNet Inc . 15


17/18

I PC Example

Processing a SET Request

When a set request is sent by the Manager to the Agent

The agent API calls the IpcTableProcessRequests() in the ipctablehdlr.c file. The above function processes the request and in turn calls the

SendMessageToExternalApplication() . This in turn calls the following method which sends the message to the external application:

o SendUDPMessage() in case of sockets.

o SendQueueMessage() in case of message queues. Next, the following function is called which gets the corresponding values of the

corresponding row:

o ReadUDPMessage()

o ReadQueueMessage() The values are then stored in the table gv_ipcTableVector(), using the function

CreateAndAddNewIpcTableEntry() . If the corresponding row does not exist in the external application, the table is not updated for

the corresponding row. If a request is received for a row (muti-varibinds) then the agent will contact external

application and retrieve value for the complete row. The Agent API updates the table with the new values set by the manager if a row already

exists or it creates a new row in the table if the row does not exist. Before sending a response to the manager, the Agent API calls the function

UpdateIpcTable() . This function is used to update the rows in the external application as maintained by the

agent. In case of row deletion, the UpdateIpcTable() function will have the row status value as non-

existent (0). This will delete the row in the external application.

AdventNet Inc . 16


18/18

I PC Example

Running the Example The IPC reference implementation files are available in the ./examples/mpa directory. Since, theimplementation involves two modules, one for agent and the other for external application, thefollowing files in the ./examples/mpa/ipc-mp-agent directory are used for the agent module:

ipctablehdlr.c ipcext.h

The following files in the ./examples/mpa/ipc_mp_agent/ipcext directory are used for externalapplication module:

ipcext.c stdvars.h

To implement this example, please follow the steps given below:

1. To generate code for the agent application, load the IPC-COMMUNICATION-MIB in theAgent (MIB) Compiler.

2. Create a new project with the Agent type as Multi-Protocol Agent.

3. In Settings->General options, specify the storage type as No storage and generate sourcecode.

4. Replace the generated ipctablehdlr file in the /C Agent/projects//agent/stubs/ipc-communication-mib/src directory with the filein the examples/mpa/ipc-mp-agent directory.

5. Copy the ipcext.h file in the /C-Agent/projects//agent/stubs/ipc-

communication-mib/include directory .6. Compile the generated code as given below :

cd /C-Agent/projects//agent make for Unix-based systems andnmake for Windows.

7. On successful compilation, run the agent as given below:cd /C-Agent/projects//agent/bin ./cagent for Unix-based systemsor cagent for Windows.

8. Compile the ipcext.c file in the /C Agent/examples/mpa/ipc-mp-agent/ipcext directory as given below:cd /C Agent/examples/mpa/ipc-mp-agent/ipcext - gcc ipcext.c -o ipcext for Unix-based systems (or) cl.exe ipcext.c for Windows.

9. To run the external application,cd /C Agent/examples/mpa/ipc-mp-agent/ipcext - ./ipcext for Unix (or) ipcext forWindows

10. Load the MIB in the MIB Browser and query the agent which runs at port 8001 by default.

You can find the Agent responding with the required values.

Ad 17

i pc example

Documents