winsnmp2.txt

windows的snmp api源码

operating in the window/message notification mode.  (See the
descriptive text for the SnmpOpen() function elsewhere in
the alphabetical "Function Reference" chapter for additional
background information.)

Note:  The fCallBack function must return SNMPAPI_SUCCESS to
indicate continued viability.  Any other returned value will
be interpreted as SNMPAPI_FAILURE and will result in the
implementation doing an implicit SnmpClose() operation on
the session.

Note:  If the fCallBack parameter to SnmpCreateSession() is
NULL, any non-NULL value of lpClientData is meaningless and,
therefore, will be ignored by the implementation.

Note:  When the callback function is called for the purpose
of notifying the session of the presence of an SNMP message
for it, the value passed for wParam must be 0.  Otherwise,
any non-zero value of wParam will signal an asynchronous
error notification for the session.  The most common example
of such an error notification is a "no response from agent"
timeout when the implementation is executing retransmission
policy for the application; in which case, the value of
wParam will be SNMPAPI_TL_TIMEOUT [108].  The value passed
in the lParam parameter will always indicate the RequestID
of the affected PDU.  (See the descriptive text for the
SnmpRecvMsg() function elsewhere in the alphabetical
"Function Reference" chapter for more information about the
general use of these two parameters.)

Following are some sample calling modes for different
operating environments:

MS-Windows, Window/Message notification mode:
hSession = SnmpCreateSession (myWnd, myMsg, NULL, NULL);

MS-Windows, Callback notification mode:
hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

UNIX X-Windows, Callback notification mode:
hSession = SnmpCreateSession (myWnd, 0, myFunc, <NULL|myData>);

Any non-window Command Line Environment, Callback mode:
hSession = SnmpCreateSession (0, 0, myFunc, <NULL|myData>);

Note:  The first example above is equivalent to a standard
WinSNMP SnmpOpen() call.

Note:  For non-MS-Windows operating environments,
implementors may (and will likely have to) supply
definitions for the Windows-specific data types used in the
standard WinSNMP.h file, which originate from <windows.h>
(which is #include'd in WinSNMP.h).

A possible example of a "windows.h" file for a generic
X-Windows operating environment follows:

// windows.h
// #include'd in WinSNMP.h
// typedef's for the SnmpCreateSession function
typedef XtAppContext  HWND;     // X-Window id
typedef unsigned int  UINT;     // Not used
typedef void         *CALLBACK; // Callback function
typedef void         *LPVOID;   // Callback user data
// additional typedef's for the fCallBack prototype
typedef unsigned int  WPARAM;   // Notification code
typedef unsigned int  LPARAM;   // RequestID

See also:  SnmpOpen() and SnmpRecvMsg() in the alphabetical
function reference section, and "Retransmission and Timeout
Notification" in the "Programming with WinSNMP" section.

2.  SnmpCreateEntity()

Due to the on-going work in the IETF SNMPv3 WG, this function
will be deferred to the WinSNMP v3 time frame.

This "placeholder" is being retained here as a signal to
interested parties to monitor the SNMPv3 output for future
incorporation in WinSNMP v3.

3.  SnmpCreateContext()

Due to the on-going work in the IETF SNMPv3 WG, this function
will be deferred to the WinSNMP v3 time frame.

This "placeholder" is being retained here as a signal to
interested parties to monitor the SNMPv3 output for future
incorporation in WinSNMP v3.

4.  SnmpCancelMsg()

The SnmpCancelMsg() function requests cancellation of any
further retransmissions or timeout notification for the PDU
identified by the requestId parameter for the specified
session.

SNMPAPI_STATUS SnmpCancelMsg (IN HSNMP_SESSION session,
                              IN smiINT32 requestId);

WINSNMP.DEF category = Communications Functions;
ordinal value = @222.

Parameter     Description
session       Identifies the session which submitted the
              message to be canceled.
requestId     Identifies the Request-ID value of the
              hPdu used in the corresponding call to
              SnmpSendMsg().

Returns:

If the function executes successfully, the return value is
SNMPAPI_SUCCESS.

If the function fails, the return value is SNMPAPI_FAILURE.
Use SnmpGetLastError() to obtain extended error information.

SnmpGetLastError()       Description
SNMPAPI_SESSION_INVALID  The session parameter is invalid.
SNMPAPI_PDU_INVALID      The requestId parameter does not
                         identify a message with outstanding
                         retransmissions for the specified
                         session.

Comments:

Successful execution of this function is analogous to
setting RetransmitMode to SNMPAPI_OFF for the affected
message.

Note:  Applications must be aware that--due to transaction
queuing at various levels--it is possible that the subject
destination entity may still receive and/or respond to a
corresponding SNMP message even following successful
execution of SnmpCancelMsg().  But the implementation must
not transmit any retries or submit a Response-PDU or timeout
notification to the application for the subject message
following successful execution of this function.

Note:  Successful execution of this function applies to a
single message instance.  This point illustrates another
reason why applications should use "meaningful" Request-ID
values for their respective PDUs.

Note:  Implementations must effectively execute
SnmpCancelMsg() on any outstanding messages for a session
when SnmpClose() is called, whether directly or indirectly
via SnmpCleanup().

5.  SnmpSetPort()

The SnmpSetPort() function permits an application to change
the port assignment of a given destination entity.

SNMPAPI_STATUS SNMPAPI_CALL SnmpSetPort
				(IN HSNMP_ENTITY hEntity,
                            	IN UINT nPort);

WINSNMP.DEF category = Entity/Context Functions;
ordinal value = @320.

Note:  "Destination entity" includes entities used as
agent applications via the local WinSNMP implementation
(see Section III.6, "SnmpListen()", below).

Note:  If the hEntity parameter identifies an entity which
is already operating in an agent mode for this application
(via the new SnmpListen() function outlined below), then
this function will return SNMPAPI_FAILURE, with SnmpGetLastError()
set to return SNMPAPI_ENTITY_INVALID, since such an entity is
already bound to a port.  The proper sequence of events for
such an entity is:

	hAgent = SnmpStrToEntity (hSession, <addrString>);
	lStatus = SnmpSetPort (hAgent, <nPort>);
	lStatus = SnmpListen (hAgent, SNMPAPI_ON);

The implementation will have "assigned" a port value to the
entity as part of the SnmpStrToEntity() operation.  This will
normally be the standard SNMP request port for the respective
protocol family (e.g., UDP 161 or IPX 36879) for an entity
created in "untranslated" mode or whatever may be specified in
the local database for an entity created in "translated" mode.
So, if the agent is to listen on a different port, or just to
be safe, the app can use SnmpSetPort() to arrange that.

6.  SnmpListen()

This new function permits the "attachment" of an agent
application using the [local] address and port settings
in effect for the hEntity parameter.

SNMPAPI_STATUS SNMPAPI_CALL SnmpListen
				(IN HSNMP_ENTITY hEntity,
                           	IN SNMPAPI_STATUS lStatus);

WINSNMP.DEF category = Communications Functions;
ordinal value = @221.

"hEntity" will indicate the session to be notified (via
callback or window/message) when an in-coming request
is received for this agent application, and the address
family, interface address, and port to use for this
"agent".  Note that all of these attributes already exist
as aspects of a WinSNMP "entity".

"lStatus" will take either of two values: SNMPAPI_ON
or SNMPAPI_OFF.  If it is SNMPAPI_ON, all else passing,
the "agent" will then bind to its af:addr:port and
listen for incoming requests, which will be transferred
to it via the normal WinSNMP mechanisms.  It will then
"do its thing" with the request, form the response,
reverse the srcEntity and dstEntity parameters it
received on the SnmpRecvMsg() call, and transmit the
response back to the requester via SnmpSendMsg().

If the entity's port is already in use, the call to
SnmpListen() will fail with an appropriate error
via SnmpGetLastError().  When an entity no longer
wants to function as an agent, it should call
SnmpListen() with an "lStatus" value of SNMPAPI_OFF
to release the port (and other resources).  Both
SnmpClose() for the session and SnmpCleanup() for
the app must release all affected agent ports.

7.  SnmpGetVendorInfo()

This new function returns vendor identification information
to the application using a new structure defined in winsnmp.h:

#define MAXVENDORINFO 32
typedef struct
	{
	char vendorName[MAXVENDORINFO*2];
	char vendorContact[MAXVENDORINFO*2];
	char vendorVersionId[MAXVENDORINFO];
	char vendorVersionDate[MAXVENDORINFO];
	smiUINT32 vendorEnterprise;
	} smiVENDORINFO, FAR *smiLPVENDORINFO;

SNMPAPI_STATUS SNMPAPI_CALL SnmpGetVendorInfo
				(OUT smiLPVENDORINFO vendorInfo);

WINSNMP.DEF category = Local Database Functions;
ordinal value = @120.

If vendorInfo is NULL, the return value is SNMPAPI_FAILURE with
SnmpGetLastError() set to return SNMPAPI_NOOP.

Upon successful return from this function, the four "char"
fields should contain NULL-terminated text strings suitable
for output on a display device.  The content of these fields
is vendor-determined, but should provide information helpful
to end-users in the event of a problem, if displayed by an
application.  For example, "vendorContact" could include a
physical or postal address, telephone and/or fax numbers,
an e-mail address or a URL.  If a vendor has an IANA-issue
enterprise number, then it should be returned as the value
of vendorEnterprise; otherwise, its value must be zero.

8.  SnmpOpen()

[Note:  Modified for clarity wrt SnmpCreateSession(), which
is new for WinSNMP v2.]

[Do_Box]
Important:  WinSNMP v2.0 added the SnmpCreateSession()
function which provides a superset of the SnmpOpen()
functionality.  Developers are encouraged to use
SnmpCreateSession() instead of SnmpOpen().

SnmpOpen() is maintained for backwards compatibility with
pre-v2.0 WinSNMP applications, but some (non-Windows)
implementations may return SNMPAPI_OPERATION_INVALID in
response to any SnmpOpen() call, as described below.
[End_Box]

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 enables
the implementation to perform an orderly release of
resources in response to a subsequent SnmpClose() function
call for a given session (or in response to a subsequent
SnmpCleanup() call for the application).

Syntax:
HSNMP_SESSION     SnmpOpen (
IN HWND           hWnd,
IN UINT           wMsg);

Parameter     Description
hWnd     Identifies the application's notification window.
wMsg     Identifies the application's notification message.

Returns:

If the function is successful, the return value is a non-
zero HSNMP_SESSION value which identifies the WinSNMP
session opened by the implementation on behalf of the
calling application.

If the function fails, the return value is SNMPAPI_FAILURE.
Use the SnmpGetLastError() function to obtain extended error
information.

SnmpGetLastError()        Description
"Common Error Codes"      See Section 2.10.1. Common Error
                          Codes.
SNMPAPI_HWND_INVALID      The hWnd parameter is not a valid
                          window handle.
SNMPAPI_OPERATION_INVALID This implementation does not
                          support the Windows/Message
                          notification scheme (see
                          SnmpCreateSession()).

Comments:

See Section 2.5. Sessions and Section <new> SnmpCreateSession().

An application can open multiple sessions.  Each such
session for the same hWnd should provide a different wMsg,
but this is not required.

A successful SnmpOpen() call always returns a unique
HSNMP_SESSION value (with respect to all other currently
open sessions for the calling application).

The hWnd parameter specifies the window to be notified when
an asynchronous request completes or trap/notification
occurs and the wMsg parameter specifies the message number
that the implementation will send to the window.  Upon
receipt of this message,

     - If the wParam component of the notification message
       is zero (0),  the application should call
       SnmpRecvMsg() to retrieve the subject PDU for
       immediate or subsequent processing.

     - If the wParam component of the notification message
       is non-zero, it will represent a WinSNMP API error
       code (e.g., SNMPAPI_TL_TIMEOUT) referring to the
       PDU identified by the Request_Id value in the lParam
       component.  In this case, the application should
       react to the error condition and should not call
       SnmpRecvMsg().

In other programming models (e.g., synchronous, CLI-driven,
or "curtained" applications), the WinSNMP implementation may
interpret hWnd and hMsg differently.  Likewise, the session
model may be used to facilitate multi-threaded programming
in supporting environments.  The SnmpCreateSession()
function has been added to WinSNMP v2.0 to formalize such
usage.

Note:  A well-behaved WinSNMP application will call
SnmpClose() for each session opened with SnmpOpen().  When
an emergency exit is required by the application, it must at
least call SnmpCleanup().

A well-behaved WinSNMP implementation must react to an
SnmpCleanup() call as though it were a series of SnmpClose()
calls for each open session allocated to the calling
application.