winsnmp2.txt

windows的snmp api源码

namely, each output represents a new "instance" (used loosely)
of the object.  Such a new "instance" may be either a new
unique value for that object type or may correspond to some
internal, implementation-specific mechanism (such as a
"reference count").

The key underlying principle is that actual value of a
WinSNMP resource object is not meaningful to the
application, but is meaningful to the implementation.
Applications need only be certain to match up each WinSNMP
resource object creation operation with a corresponding
"free" operation or, as may be appropriate, to free them via
calls to SnmpClose() or SnmpCleanup().

10.  GetBulk -> GetNext mapping

When the dstEntity used in an SnmpSendMsg() operation is an
SNMPv1 entity and the PDU type is SNMP_PDU_GETBULK, the
implementation must automatically and transparently modify
the PDU type to SNMP_PDU_GETNEXT, per RFC 1908.  Note that
this "translation" occurs during serialization of the
WinSNMP components (hContext, hPdu, and hVbl, in this case)
into the SNMP message that will be transmitted.  It does
NOT alter the submitted components themselves.

11.  IPX support in SnmpStrToEntity()

WinSNMP v1 was highly oriented toward IP/UDP, but was not
meant to exclude the compatible, symmetrical use of other
transport protocols by specific implementations.  As a
result, some implementations accepted alternative string
formats as arguments to SnmpStrToEntity()--when called by
an application operating in "untranslated" mode--to signal
the use of protocols other than UDP.

In particular, the use of "<netnum><sep><nodenum>" for the
IPX protocol found a significant degree of usage.  Hence, it
is considered helpful to the community to specify a standard
format for this purpose and to explicitly allow its use in
SnmpStrToEntity().  This standard format consists of three
collated parts:

     1.  A "network number" <netnum>, consisting of eight
         hexadecimal digits (zero-filled, if necessary).

     2.  A separator (i.e., either ":" or "-").

     3.  A "node number" <nodenum>, consisting of twelve
         hexadecimal digits (zero-filled, if necessary).

For example:  "00000001:00080A0D01C2"
         or:  "00000001-00008A0D01C2"

Note that SnmpEntityToStr() is also modified to return a
properly formatted IPX address string, per above, for any
IPX entity--when called by an application operating in
"untranslated" mode at the time, or in "translated" mode
but with no "friendlyName" value available.

The ":" separator is the recommended default for use in
the output string.

12.  SnmpDecodeMsg() outputs

This clarification has to do with return values for the hSrc
and hDst output parameters.  The key point is that an
implementation cannot be required to supply information that
is not unambiguously available to it.  When WinSNMP v1 was
designed, party-based SNMPv2 (since deprecated to "Historic"
status) was being actively considered by the IETF.  That
form of the protocol might have included more address-type
information in the encoded SNMP messages.  If it had, then
this information could have been used by the implementation
of the SnmpDecodeMsg() function to instantiate hSrc and hDst
entity values.

However, the IETF adopted a different form of SNMPv2 (SNMPv2c,
as defined in RFCs 1901-1908) and this form retains the same
message format as SNMPv1 and that message format does not
include the addressing information needed to properly create
WinSNMP entity resources.

Therefore, SnmpDecodeMsg() cannot return meaningful values
for the hSrc or hDst parameter for SNMPv1 or SNMPv2 messages
submitted to it and must return a value of zero in these
output parameters.

13.  Inform processing

SNMPv2 Inform requests are only supported to a destination
entity that supports SNMPv2.  An attempt to send an Inform
request to an SNMPv1 destination using SnmpSendMsg() must
return SNMPAPI_FAILURE, with SnmpGetLastError() set to
return SNMPAPI_OPERATION_INVALID.

The implementation is responsible for generating and
transmitting the (single) Response-PDU for any received
InformRequest-PDU.

Applications that receive an InformRequest-PDU via a WinSNMP
session must not issue a corresponding Response-PDU.

14.  Thread-safeness

A multi-threaded application must ensure the thread-safeness
of its own WinSNMP operations.

The implementation must ensure "thread-safeness" at the
application (process) level.  That is, the implementation
must ensure that the WinSNMP operations of one process do
not unilaterally modify the WinSNMP settings of any other
process.

The WinSNMP operations that might merit attention on the
part of a multi-threaded application are those which set
application-level parameters.  At this time, there are
only two such settings:

	- SnmpSetTranslateMode()
	- SnmpSetRetransmitMode()

It is often, not always, the case that an application--
multi-threaded or not--will operate with a single constant
value for each of these settings, with this value normally
being either the default supplied by the SnmpStartup() call
or an application-specified value (via SnmpSetTranslateMode()
and/or SnmpSetRetransmitMode()) before any calls to the
WinSNMP entity or context creation functions (for "translate"
mode) or calls to SnmpSendMsg() (for "retransmit" mode).

Nonetheless, implementors providing WinSNMP for operating
environments which support multi-threaded applications
are encouraged to include guidance on this issue in their
developer-oriented documentation.

15.  WinSNMP++ -> SNMP++ change

The embryonic WinSNMP++ appendix to the WinSNMP v1
specification has been deprecated and deleted from the
WinSNMP v2 specification.

Implementors are now directed to the open SNMP++
specification (and reference code) published by Hewlett-
Packard (http://rosegarden.external.hp.com/snmp++).

16.  SnmpRegister()

The primary purpose of SnmpRegister() is to enable an
application to indicate that it wants to receive traps
that arrive at the default SNMP trap port(s) (UDP 162
and/or IPX 36880) on the local machine.  This can be
accomplished by passing the following parameter values
in the call to SnmpRegister():

     session      - a valid session handle
     srcEntity    - NULL
     dstEntity    - NULL
     context      - NULL
     notification - NULL
     status       - SNMPAPI_ON

This sequence of parameter values, assuming the call is
otherwise successful, will result in all notifications
(traps and informs) received by the WinSNMP implementation
being delivered to the session.  We will refer to the
above setting as an "unfiltered" registration.

A secondary purpose of SnmpRegister() is to function as
a minimal "trap filter" on notifications received by the
WinSNMP implementation.  In this mode, non-NULL values
for any combination of one or more of the srcEntity,
dstEntity, context, or notification parameters, will be
used to form a filter to be applied to traps received by
the WinSNMP implementation for the indicated session.
We will refer to any such operation as a "filtered"
registration.

Note that while an "unfiltered" registration is in
effect for a session, it makes no sense to issue any
"filtered" registration requests for that same session.
They would be totally superfluous--since all notifications
would already be delivered to the session anyway due to
the "unfiltered" registration.  This is one of three types
of "redundant" registrations.  Another type of "redundant"
registration is a duplicate call to SnmpRegister()--that
is, one in which the parameter list is identical to the
parameter list used to instantiate an active registration
for the same session.  The third type of "redundant"
registration is one in which the notification parameter
(when dereferenced) fully contains (as a prefix) a
notification parameter used on an active registration
for the same session.  This is redundant due to the
wildcard interpretation of the notification parameter
specified in the WinSNMP v1.1a spec.

In all cases of "redundant" registrations, SnmpRegister()
should return SNMPAPI_SUCCESS, since the action requested
by the application--namely, to deliver the specified
notifications to the indicated session--will be carried
out.  [Yes, we could have gone with SNMPAPI_FAILURE in
these cases and setting SnmpGetLastError() to return
SNMPAPI_NOOP, but the incidence of problems resulting
form such "redundant" calls has proven to be close to
zero in practice and, therefore, we are taking a more
streamlined approach.]

Also, note that such redundant "register" requests are
idempotent, meaning that only a single corresponding
"unregister" call is required.  To "unregister" means
to call SnmpRegister() with a status parameter value of
SNMPAPI_OFF and with the first five parameters having
the same effective values as some previously successful
call with a status parameter of SNMPAPI_ON.

Implementations do not maintain a "count" of redundant
registrations that must be matched with an equal number
of corresponding unregistrations.

Of course, each unique (non-redundant) register must
be matched with an unregister call to remove it, if
desired by the application.

III - New Functions:

1.  SnmpCreateSession()

The SnmpCreateSession() function is used to create a WinSNMP
"session" and to specify the notification mode-either a
"window/message" pair or callback function--that will be
used for the session.

With this function, Windows programmers now have the option
of having the implementation use either the standard Windows
message notification method (as in SnmpOpen()) or a direct
callback into a session-specific function.  As a by-product
of this enhanced flexibility for Windows programmers, the
WinSNMP API can now also be used in some non-Windows
operating environments (some examples are given below).

This function is a superset of the SnmpOpen() function.
That is, when used to create a session with window/message
notification, it provides the exact same functionality as
SnmpOpen().  (Refer to the descriptive text for SnmpOpen()
elsewhere in this alphabetical "Function Reference" chapter
for more information.)

Developers writing new applications for WinSNMP v2.0 are
encouraged to use SnmpCreateSession() for all session
creation, even when selecting the window/message
notification mode (i.e., instead of using SnmpOpen()).
Developers upgrading applications written for earlier
versions of WinSNMP to take advantage of other WinSNMP v2.0
features are encouraged to change all SnmpOpen() calls to
the equivalent form of SnmpCreateSession().

HSNMP_SESSION SnmpCreateSession (IN HWND hWnd,
                                 IN UINT wMsg,
                                 IN SNMPAPI_CALLBACK fCallBack,
                                 IN LPVOID lpClientData);

WINSNMP.DEF category = Communications Functions;
ordinal value = 220.

Parameter     Description
hWnd          Identifies a notification window.
wMsg          Identifies a notification message.
fCallBack     Identifies a notification callback function;
              may be NULL.
lpClientData  Identifies a pointer to optional application
              data to pass to the fCallBack function; may be
              NULL.

Returns:

If the SnmpCreateSession() function is successful, the return
value is an HSNMP_SESSION handle 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
and SnmpGetLastError() will be set to return extended error
information as follows:

SnmpGetLastError()        Description
"Common Error Codes"      See Section 2.10.1. Common Error
                          Codes.
SNMPAPI_HWND_INVALID      hWnd is not a valid window value.
SNMPAPI_MSG_INVALID       wMsg is not a valid message value.
SNMPAPI_MODE_INVALID      The combination of values passed
                          is mutually incompatible or
                          incomplete.
SNMPAPI_OPERATION_INVALID The combination of values passed
                          does not identify a valid
                          notification mode for this
                          implementation.

As will be explained below, the conditions leading to any of
the three specific error codes listed above are somewhat
environment-specific.

Comments:

If fCallBack is NULL, SnmpCreateSession() is equivalent to
the SnmpOpen() function.  In this window/notification mode,
the values of hWnd and wMsg must both be valid in the
implementation's operating environment.

If the value of hWnd is invalid, then the function returns
SNMPAPI_FAILURE, and SnmpGetLastError() is set to return
SNMPAPI_HWND_INVALID.

Else, if the value of wMsg is invalid, then the function
returns SNMPAPI_FAILURE, and SnmpGetLastError() is set to
return SNMPAPI_WMSG_INVALID.

Else, if both values are individually valid but are mutually
incompatible in a given windowing environment, then the
function returns SNMPAPI_FAILURE, and SnmpGetLastError() is
set to return SNMPAPI_MODE_INVALID.

If fCallBack is non-NULL, it represents the address of a
function to be called whenever the implementation has a
notification to deliver to the session.  The notification
may signal the presence of an SNMP message for the session
or it may signal the existence of an asynchronous error
condition (for example, a transport layer timeout error).
(Refer to the discussion of "Retransmission and Timeout
Notification" in the "Programming with WinSNMP" chapter
and the descriptive text for SnmpRecvMsg() elsewhere in
this alphabetical "Function Reference" chapter for more
information.)  When fCallBack is non-NULL, a given operating
environment may require valid values for any or all of hWnd,
wMsg, and/or lpClientData and should return one of the three
function-specific error codes in a manner consistent with
that outlined above.

The callback function prototype must be:

typedef SNMPAPI_STATUS (CALLBACK *SNMPAPI_CALLBACK)(
                        IN HSNMP_SESSION session,
                        IN HWND hWnd,
                        IN UINT wMsg,
                        IN WPARAM wParam,
                        IN LPARAM lParam,
                        IN LPVOID lpClientData);

Parameter     Description
session       Identifies the session being notified.
hWnd          Identifies the session's notification window.
wMsg          Identifies the session's notification message.
wParam        Identifies the purpose of the notification.
lParam        Identifies the RequestID of the subject PDU.
lpClientData  Identifies a pointer to optional application
              data, if such a pointer was specified in the
              session's SnmpCreateSession() call.

Note:  If fCallBack is non-NULL on a successful call to the
SnmpCreateSession() function, then the session operates in
callback notification mode and the values of hWnd and wMsg
passed to the SnmpCreateSession() function may or may not be
significant depending upon the operating environment, but
are always passed to the callback function for its possible
use.

Note:  If a callback function has been assigned to a session
in this manner, then upon receipt of an SNMP message for the
session the implementation will call the callback function--
instead of sending the wMsg notification message to the hWnd
as it would in the window/message notification mode--and
pass it the session identifier and two values representing
the wParam and lParam values that would have been used if