Introduction
One day i wanted to know what kind of configuration routers in my company have.
Because i am working in a bank, there are many branches, many routers and ,
of course, many configurations. So i wanted to access to the routers and made a
request to one of my friends in Ankara to send me a configuration file installed
on the routers. At last ( many days later ) he sent me one. I had a look at the
file and saw that he had deleted all enable password sections, virtual terminal
access sections, auxiluary port access sections and console access section. But
there was an open door, snmp read/write community name. Yes, i had an open door
but i had no any snmp utility to get routers's configuration file. I found one
that is great named "Solar Winds Engineers Edition". 30 days later, the trial
period ended. and then i made a serach on net, again, again again. At last,
i was bored and decided to write my own program doing what i want. This time i
searched the net for snmp protocol, after finding some documentations i wrote this
program.
In this section i will give you litle information about SNMP protocol ( if you
want to know more about it, you can go the cisco web site for it - www.cisco.com ),
wsnmp32 api functions declerations and the usage of them. The last section will
include the source code of the program. I hope these all things will be useful
for one person on net at least.
What Is SNMP ?
SNMP ( Simple Network Managment Protocol ) is a protocol that enables to exchange
of management information between network devices. It also enables to manage
network performance, find and solve network problems and plan for network growth.
There are three versions of SNMP which are SNMP V.1, SNMP V.2 and SNMP V.3. Each
version of SNMP introduces new functionalities over the old one. SNMP has three
basic components which are a managed device, an agent and a network managment
system ( NMS ). A managed device is a network node that contains the agents and
is resided on a managed network. They can be routers, access servers, switchs,
bridges, hubs, computer hosts or printers. An agent is a network-management
software module resides in a managed device. An NMS contains application programs
that monitor and control the managed device.
What Is Win SNMP
Win SNMP is an API that enables SNMP-based network management applications running
under the Microsoft Windows operating systems to use the functionality of SNMP.It
contains many functions to get information about SNMP agents and to set them with
new values. Here, you will find all the structures and constant definitions, function
declerations and their usages defined in SNMP V.1 and SNMP V.2.
SNMP Data Types And Structures
The SNMP data types and structures are as fallows
Data Types |
Type Name | C# Type |
smiINT | int |
smiINT32 | int |
smiUINT32 | uint |
smiOCTETS | Structure of smiOCTET |
smiBITS | Structure of smiOCTET |
smiOID | Structure of smiOCTET |
smiIPADDR | Structure of smiOCTET |
smiCNTR32 | uint |
smiGAUGE32 | uint |
smiTIMETICKS | uint |
smiOPAQUE | Structure of smiOCTET |
smiNSAPADDR | Structure of smiOCTET |
smiCNTR64S | Structure of smiCNTR64 |
smiOCTET |
Type Name | C# Type |
smiUINT32 len | uint len |
smiUINT32 ptr | uint ptr |
C# structure definition |
struct smiOCTET
{
uint len;
uint ptr;
} |
smiCNTR64 |
Type Name | C# Type |
smiUINT32 hipart | uint hipart |
smiUINT32 lopart | uint lopart |
C# structure definition |
struct smiCNTR64
{
uint hipart;
uint lopart;
} |
Local Database Functions
Local database functions are as fallows
SnmpSetTranslateMode
Definitions |
Win SNMP | C# |
SnmpSetTranslateMode( IN smiUINT32 nTranslateMode); | [DllImport("wsnmp32")] extern int SnmpSetTranslateMode( int nTransMode); |
Description |
The SnmpSetTranslateMode function enables the calling application to inform the
implementation as the desired entity/context translation mode to use for subsequent
SnmpStrToEntity and SnmpStrToContext function calls. nTranslateMode is the desired
mode to set and must be one of the fallowing values:
SNMPAPI_TRANSLATED
SNMPAPI_UNTRANSLATED_V1
SNMPAPI_UNTRANSLATED_V2
|
SnmpSetRetransmitMode
Definitions |
Win SNMP | C# |
SnmpSetRetransmitMode( IN smiUINT32 nRetransmitMode); | [DllImport("wsnmp32")] extern int SnmpSetRetransmitMode(int nRetransmitMode); |
Description |
The SnmpSetRetransmitMode function enables the calling application to inform the
implementation as to the desired retransmission mode (i.e., timeout/retry) for
subsequent SnmpSendMsg operations. nRetransmitMode is the desired mode to set and
must be one of the fallowing values
SNMPAPI_ON -> The implementation is doing retransmission
SNMPAPI_OFF -> The implementation is not doing retransmission
|
Communication Functions
Communication functions are as fallows
SnmpStartup
Definitions |
Win SNMP | C# |
SnmpStartup(OUT smiUINT32 nVerMaj, OUT smiUINT32 nVerMin, OUT smiUINT32 nLevel, OUT smiUINT32 nTMode, OUT smiUINT32 nRMode); | [DllImport("wsnmp32")] extern int SnmpStartup(ref int nVerMaj, ref int nVerMin, ref int nLevel, ref int nTMode, ref int nRMode); |
Description |
The SnmpStartup function notifies the implementation that the calling application
is going to use its services, enabling the implementation to perform any required
start-up procedures and allocations and to return some useful housekeeping information
to the application.
nMajorVersion -> is the variable to receive the major version number
nMinorVersion -> is the variable to receive the minor version number
nLevel -> is the variable to receive the highest level supported
nTranslateMode -> is the variable to receive the default entity/context translation mode in effect
nRetransmitMode -> is the variable to receive the default retransmission mode in effect
Note : Every Win SNMP application must call this function preceeding any other
Win SNMP functions.
|
SnmpCleanup();
Definitions |
Win SNMP | C# |
SnmpCleanup(); | [DllImport("wsnmp32")] extern int SnmpCleanup(); |
Description |
The SnmpCleanup function informs the implementation that the calling application
is disconnecting and no longer requires any open resources which might be allocated
to it by the implementation. The implementation will deallocate all resources
allocated to the application, unless they have also been allocated to other active
applications. Important Note : Every application must call SnmpFreeXXX functions and
SnmpClose function after every SnmpOpen function call before exiting the application.
In an emergency exit, implementation only releases the resources that are being
responsible by itself, if this function calls./font>
|
SnmpClose
Definitions |
Win SNMP | C# |
SnmpClose(IN smiUINT32 hSession); | [DllImport("wsnmp32")] extern int SnmpClose(int hSession); |
Description |
The SnmpClose function causes the implementation to deallocate and/or close memory,
resources, communications mechanisms and data structures associated with the specified
session, on behalf of the calling application. A well-behaved application will call
SnmpClose after each opened session when a session is no longer needed. In an emergency
exit, at least SnmpCleanup must be called.
|
SnmpSendMsg
Definitions |
Win SNMP | C# |
SnmpSendMsg(IN smiUINT32 hSession, IN smiUINT32 sEntity, IN smiUINT32 dEntity, IN smiUINT32 hContext, IN smiUINT32 hPDU); | [DllImport("wsnmp32")] extern int SnmpSendMsg(int hSession, int sEntity, int dEntity, int hContext, int hPDU); |
Description |
The SnmpSendMsg function requests the specified PDU be transmitted to the destination
entity, using the specified context and--for SNMPv2 communications--the designated
source entity
When a transmission request is received by the implementation via the SnmpSendMsg
function, the WinSNMP implementation determines which version of SNMP and which
transport to use based on its own capabilities and the corresponding properties
associated with the requesting session and with the remote entity which holds
the context to be accessed, based on values in the Local Database.
session -> Identifies the session that will perform the operation.
srcEntity -> Identifies the subject management entity.
dstEntity -> Identifies the target management entity.
context -> Identifies the target context of interest.
pdu -> Identifies the SNMP protocol data unit containing the operation.
Note: It is the responsibility of the WinSNMP implementation to verify the correctness
of the PDU structure (and other arguments)
|
SnmpRecvMsg
Definitions |
Win SNMP | C# |
SnmpRecvMsg(IN smiUINT32 hSession, OUT smiUINT32 sEntity, OUT smiUINT32 dEntity, OUT smiUINT32 hContext, OUT smiUINT32 hPDU); | [DllImport("wsnmp32")] extern int SnmpRecvMsg(int hSession, ref int sEntity, ref int dEntity, ref int hContext, ref int hPDU); |
Description |
The SnmpRecvMsg function retrieves the results from a completed asynchronous request
made on a given HSNMP_SESSION. It also receives traps registered for that session.
session -> Specifies the session that will receive the SNMP message.
sEntity -> Identifies the entity (agent role) which sent the message.
dEntity -> Identifies the entity (manager role) which is to receive the message.
hcontext -> Identifies the context from which the srcEntity issued the message.
hpdu -> Identifies the PDU component of the received message.
Note: Because there may be multiple messages sent to an agent, receiving order
may not be in the same order for the messages that are sent. so, it is the responsibility of the
Win SNMP application to check the request id by the request id of the message that is sent to make
sure that the received message is the reply of the message that is sent.
|
SnmpOpen
Definitions |
Win SNMP | C# |
SnmpOpen(IN smiUINT32 hWnd, IN smiUINT32 wMsg); | [DllImport("wsnmp32")] extern int SnmpOpen(IntPtr hWnd, int wMsg); |
Description |
The SnmpOpen function enables the implementation to allocate and initialize memory,
resources, and/or communications mechanisms and data structures for the application.
The application will continue to use the "session identifier" returned by the implementation
in subsequent WinSNMP function calls to facilitate resource accounting on a per session basis.
This mechanism will enable the implementation to perform an orderly release of resources
in response to a subsequent SnmpClose function call for a given session.
hWnd -> Identifies the application's notification window.
wMsg -> Identifies the application's notification message.
|
Entity / Context Functions
Entity / Context functions are as fallows
SnmpStrToEntity
Definitions |
Win SNMP | C# |
SnmpStrToEntity(IN smiUINT32 hSession, IN LPCSTR Entity); | [DllImport("wsnmp32")] extern int SnmpStrToEntity(int hSession, string Entity); |
Description |
The SnmpStrToEntity function accepts a pointer to a null-terminated text string
identifying an entity of interest and, if successful, returns a handle to an
implementation-specific representation of entity information. Note that the resulting
entity handle may be used as either a srcEntity value or as a dstEntity value.
hsession -> Handle of the allocating session.
Entity -> Pointer to a NULL-terminated text string identifying the management entity of interest.
|
SnmpFreeEntity
Definitions |
Win SNMP | C# |
SnmpFreeEntity(IN smiUINT32 hEntity); | [DllImport("wsnmp32")] extern int SnmpFreeEntity(int hEntity); |
Description |
The SnmpFreeEntity function releases resources associated with a entity returned by
the SnmpStrToEntity function.
hEntity -> An entity handle to be released.
|
SnmpStrToContext
Definitions |
Win SNMP | C# |
SnmpStrToContext(IN smiUINT32 hSession, OUT smiOCTET smiOctets); | [DllImport("wsnmp32")] extern int SnmpStrToContext(int hSession, ref smiOCTETSTRING smiOctets); |
Description |
The SnmpStrToContext function accepts an OCTET STRING naming the collection of managed
objects (or "profile") of interest (for SNMPAPI_TRANSLATED mode), a community string
(for SNMPAPI_UNTRANSLATED_V1 mode), or a contextID (for SNMPAPI_UNTRANSLATED_V2 mode)
and returns a handle to an implementation-specific representation of context information
for use with the SnmpSendMsg and SnmpRegister functions.
session -> Handle of the allocating session.
smiOctets -> Pointer to an smiOCTETS descriptor identifying a collection of managed objects, community string, or contextID.
|
SnmpFreeContext
Definitions |
Win SNMP | C# |
SnmpFreeContext(IN smiUINT32 hContext); | [DllImport("wsnmp32")] extern int SnmpFreeContext(int hContext); |
Description |
The SnmpFreeContext function releases resources associated with a context returned
by the SnmpStrToContext function.
hContext -> A context handle to be released.
|
PDU Functions
PDU functions are as fallows
SnmpCreatePdu
Definitions |
Win SNMP | C# |
SnmpCreatePdu(IN smiUINT32 hSession, IN smiINT32 typePDU, IN smiINT32 ReqID, IN smiINT32 errorStat, IN smiINT32 errorIdx, IN smiUINT32 hVBL); | [DllImport("wsnmp32")] extern int SnmpCreatePdu(int hSession, int typePDU, int ReqID, int errorStat, int errorIdx, int hVBL); |
Description |
The SnmpCreatePdu function allocates and initializes an SNMP protocol data unit for
subsequent use in SnmpSendMsg, SnmpEncodeMsg, and other functions.
hSession -> Handle of the allocating session.
typePDU -> NULL or one of the values shown in the PDU_types table shown in the introduction to the PDU Functions section. If NULL, the WinSNMP implementation will supply SNMP_PDU_GETNEXT.
ReqID -> An application-supplied value used to identify the PDU or NULL, in which case the WinSNMP implementation will supply a value.
errorStat -> Ignored (and may be NULL) on input for all PDU types except SNMP_PDU_GETBULK, in which case it represents the value for non_repeaters. For all other PDU types, the WinSNMP implementation will supply SNMP_ERROR_NOERROR.
errorIdx -> Ignored (and may be NULL) on input for all PDU types except SNMP_PDU_GETBULK, in which case it represents the value for max_repetitions. The WinSNMP implementation returns 0 (zero) for all other PDU types.
hVBL -> A handle to a varbindlist data structure (or NULL).
|
SnmpGetPduData
Definitions |
Win SNMP | C# |
SnmpGetPduData(IN smiUINT32 hPDU, OUT smiUINT32 typePDU, OUT smiUINT32 ReqID, OUT smiUINT32 errorStat, OUT smiUINT32 errorIdx, OUT smiUINT32 hVBL); | [DllImport("wsnmp32")] extern int SnmpGetPduData(int hPDU, ref int typePDU, ref int ReqID, ref int errorStat, ref int errorIdx, ref int hVBL); |
Description |
The SnmpGetPduData function extracts selected data elements from the specified PDU and
copies them to the respective locations given as corresponding output parameters.
hPDU -> Identifies the SNMP protocol data unit.
typePDU -> If not NULL, points to an smiINT variable that will receive the PDU_type of the PDU.
ReqID -> If not NULL, points to an smiINT32 variable that will receive the request_id of the PDU.
errorStat -> If not NULL, points to an smiINT variable that will receive the error_status (or non_repeaters) of the PDU.
errorIdx -> If not NULL, points to an smiINT variable that will receive the error_index (or max_repetitions) of the PDU.
hVBL -> If not NULL, points to an HSNMP_VBL variable that will receive the handle to the varbindlist of the PDU.
|
SnmpFreePdu
Definitions |
Win SNMP | C# |
SnmpFreePdu(IN smiUINT32 hPDU); | [DllImport("wsnmp32")] extern int SnmpFreePdu(int hPDU); |
Description |
The SnmpFreePdu function releases resources associated with a protocol data unit previously
created by the SnmpCreatePdu or SnmpDuplicatePdu function.
hPDU -> Identifies the SNMP protocol data unit to be freed.
|
Variable Binding Functions
Variable Binding functions are as fallows
SnmpCreateVbl
Definitions |
Win SNMP | C# |
SnmpCreateVbl(IN smiUINT32 hSession, IN smiOID VarOID, IN smiVALUE VarVal); | [DllImport("wsnmp32")] extern int SnmpCreateVbl(int hSession, ref smiOID VarOID, ref smiVALUEINT VarVal); |
Description |
The SnmpCreateVbl function creates a new varbindlist structure for the calling application.
If the "name" and "value" parameters are not NULL, SnmpCreateVbl uses them to construct
the initial varbind member of the varbindlist.
hSession -> Handle of the allocating session.
VarOID -> If not NULL, points to an OID for initialization of the varbindlist.
VarVal -> If not NULL, points to a value for initialization of the varbidlist.
|
SnmpFreeVbl
Definitions |
Win SNMP | C# |
SnmpFreeVbl(IN smiUINT32 hVBL); | [DllImport("wsnmp32")] extern int SnmpFreeVbl(int hVBL); |
Description |
The SnmpFreeVbl function releases resources associated with a varbindlist structure
previously allocated by SnmpCreateVbl or SnmpDuplicateVbl. It is the responsibility of WinSNMP
applications to free varbindlist resources allocated through calls to SnmpCreateVbl and
SnmpDuplicateVbl.
hVBL -> Identifies the varbindlist to be released.
|
SnmpGetVb
Definitions |
Win SNMP | C# |
SnmpGetVb(IN smiUINT32 hVBL, IN smiUINT32 Index, OUT smiOID VarOID, OUT smiVALUE VarVal); | [DllImport("wsnmp32")] extern int SnmpGetVb(int hVBL, int Index, ref smiOID VarOID, ref smiVALUEOCTET VarVal); |
Description |
The SnmpGetVb function retrieves the object instance name and its associated value
from the varbind identified by the index parameter. The SnmpGetVb function returns
the object instance name in the descriptor pointed to by the name parameter and
its associated value in the descriptor pointed to by the value parameter.
hVBL -> Identifies the subject varbindlist.
Index -> Identifies the position of the subject varbind within the varbindlist.
VarOID -> Points to a variable to receive the OID portion of the varbind.
VarVal -> Points to a variable to receive the value portion of the varbind.
|
Utility Binding Functions
Utility Binding functions are as fallows
SnmpGetLastError
Definitions |
Win SNMP | C# |
SnmpGetLastError(IN smiUINT32 hSession); | [DllImport("wsnmp32")] extern int SnmpGetLastError(int hSession); |
Description |
The SnmpGetLastError function returns an indication of why the last WinSNMP operation
executed by the application failed.
hSession -> Indicates the session for which error information is requested. If NULL, the application-wide error information is returned.
|
SnmpStrToOid
Definitions |
Win SNMP | C# |
SnmpStrToOid(IN LPCSTR strOID, OUT smiOID dstOID); | [DllImport("wsnmp32")] extern int SnmpStrToOid(string strOID, ref smiOID dstOID); |
Description |
The SnmpStrToOid function converts a textual representation of the dotted numeric
form of an OBJECT IDENTIFIER into an internal OBJECT IDENTIFIER representation.
strOID -> Points to a NULL terminated string to be converted.
dstOID -> Points to an smiOID variable to receive the converted value.
|
SnmpFreeDescOid
Definitions |
Win SNMP | C# |
SnmpFreeDescOid(IN smiUINT32 syntax,OUT smiOID Descriptor); | [DllImport("wsnmp32", EntryPoint="SnmpFreeDescriptor")] extern int SnmpFreeDescOid(int syntax,ref smiOID Descriptor); |
Description |
The SnmpFreeDescriptor function is used by the application to inform the implementation
that it no longer requires access to a WinSNMP "descriptor object" that had been
"populated" earlier on its behalf by the implementation.
syntax -> Identifies the "syntax" (data type) of the target descriptor.
Descriptor -> Identifies the target descriptor object..
|
Kernel Functions
Kernel functions used in the code are as fallows
[DllImport("kernel32")] public static extern void
Sleep(int dwMilliseconds);
[DllImport("kernel32")] public static extern int
GetTickCount();
[DllImport("Kernel32", EntryPoint="RtlMoveMemory")] unsafe public static extern int
CopyMemoryInt(int dest, int src, int length);
About Next Section
Next section of this artical will be about the source code of the program. Because
there ara many lines of code, not all of the codes will be shown in the artical.
But the basic procedure of SnmpSend and SnmpReceive functions, SnmpGet, SnmpGetNext
function will be shown. See you in the next section.