winsnmp2.txt

windows的snmp api源码

WinSNMP v2.0 Addendum

Document version information:

	November 1, 1997 - Initial Release Version
	December 5, 1997 - Typos wrt SnmpListen() params fixed

Document contents information:

       I - Introduction

      II - Clarifications for WinSNMP v2.0:

          1.  Version 2.0
          2.  Level definitions
          3.  Operating system dependencies
          4.  Retransmission support
          5.  Timeout notification methods
          6.  SNMPv1 Trap-PDU generation
          7.  Notification port usage
          8.  Request-ID/SnmpCreatePdu()/SnmpSetPdu()
          9.  SnmpGetPduData() and hVbl
         10.  GetBulk -> GetNext mapping
         11.  IPX support in SnmpStrToEntity()
         12.  SnmpDecodeMsg() outputs
         13.  Inform processing
         14.  Thread-safeness
         15.  WinSNMP++ -> SNMP++ change
         16.  SnmpRegister()

     III - New functions for WinSNMP v2.0:

          1.  SnmpCreateSession()
          2.  SnmpCreateEntity()
          3.  SnmpCreateContext()
          4.  SnmpCancelMsg()
          5.  SnmpSetPort()
          6.  SnmpListen()
          7.  SnmpGetVendorInfo()
          8.  SnmpOpen() [Re-written for v2.0]

I - Introduction

This document is an update Addendum to the WinSNMP/Manager
API Specification, v1.1a, dated August 9, 1995).  In some
places (Section II below, especially) it modifies (via
clarifying text) that earlier document; in other places
(Section III below, especially) it adds completely new
functionality.  Users of the WinSNMP API--implementors
and application developers must be familiar with both
documents until such time as the new WinSNMP API v2.0
specification document is published.  Said document will
incorporate all of the text in the final version of this
update Addendum.

Like the WinSNMP API specification document itself, this
document is intended to be freely available for use by
all interested parties.  It is the product of an open,
collaborative effort via the ad hoc WinSNMP Industry Forum
e-mail discussion list ([e-mail]).
Numerous individuals have contributed to the WinSNMP API
since this work was started in the 1992/93 time frame.

II - Clarifications

1.  Version 2.0

The collection of clarifications to v1.1a of the
WinSNMP/Manager API specification described herein defines
v2.0 of the WinSNMP API specification.

A compliant v2.0 implementation MUST support ALL of the
functions and operations defined in both the WinSNMP v1.1a
specification and is this WinSNMP v2.0 Addendum.

Where this WinSNMP v2.0 Addendum differs from the WinSNMP
v1.1a specification, this Addendum has precedence.

Note that for v2.0, the SnmpStartup() function must return a
value of 2 for the lMajor parameter and a value of 0 for the
lMinor parameter.

Note also that the "/Manager" qualifier is dropped for v2.0.
This version explicitly supports agent-side SNMP operations,
in addition to the manager-side SNMP operations.

2.  Level definitions

The concept of "levels of support" is deprecated for v2.0.
Implementations must report a value of 2 for the lLevel
parameter of SnmpStartup().

Level 2 equates to full support for the IETF standard SNMPv2
protocol as defined in RFCs 1902-1908 with the community-
based message wrapper as defined in RFC 1901 (SNMPv2c).

Levels 0 and 1 are fully subsumed under Level 2.  That is,
in addition to full SNMPv2 support (as defined in the
previous paragraph), all WinSNMP v2.0 implementations must
implement the SnmpEncodeMsg() and SnmpDecodeMsg() functions
(since no WinSNMP functions are optional in any case) and
must also support all SNMPv1 protocol operations (except
that, as always, all received SNMPv1 traps are converted
to SNMPv2 Trap-PDU format for delivery to registered WinSNMP
applications).

Level 3, as originally defined, is no longer germane since the
"Manager-to-Manager" MIB of "SNMPv2-Classic" was deprecated to
"Historic" status by the IESG and, on the positive side, the
combination of SNMPv2 support (especially, InformRequest-PDUs
and their associated Response-PDUs) and the new functions to
support agent applications under WinSNMP v2.0 (especially, the
SnmpListen() function) now provide the basis for building
Mid-Level Manager (MLM) solutions using WinSNMP.  Additionally,
it is envisioned that the next major revision of WinSNMP (v3)
will correspond to adding support for the eventual IETF SNMPv3.

(You will note that the proposed SnmpCreateEntity() and
SnmpCreateContext() functions which were included in the
earlier drafts of this Addendum have been dropped.  It is
anticipated that they will be added in WinSNMP v3 to support
the corresponding constructs which will (almost surely!) be
included in SNMPv3.)

"SNMPAPI_UNTRANSLATED_V2" mode now means "SNMPv2c"; all
the party stuff is gone (deprecated to "Historic" RFCs)
and this mode uses community names in a manner identical
to "SNMPAPI_UNTRANSLATED_V1" in terms of entity and context
definitions.  The only difference is that messages built
for SNMPv2 destination entities will use the SNMPv2 value
[1] in the "version" member of the SNMP message in the
PDUs on the wire.

3.  Operating system dependencies

WinSNMP v1 was targeted at the Microsoft Windows family of
operating systems.

WinSNMP v2 is not targeted at any particular operating
systems or environments; however, to ensure backward
compatibility with fielded WinSNMP v1 applications, the
fundamental design objectives and architectural constructs
of WinSNMP v1 are retained.

The degree of operating system independence targeted in
WinSNMP v2 is realized via the new SnmpCreateSession()
function (specified in Section III.1 of this document).

The original session creation function--SnmpOpen()--is
retained and comprises a proper subset of the possible forms
of using SnmpCreateSession().  Some minor clarifying text
has been added to SnmpOpen() for WinSNMP v2 (specified in
Section III.8 of this document).

4.  Retransmission support

Execution of the retransmission policy was optional for
implementations in WinSNMP v1.  It is mandatory capability
for implementations in WinSNMP v2.

Implementations may still announce their "default" mode of
operation at each call to SnmpStartup().  The default mode
is whatever the implementation says it is in response to
the given call to SnmpStartup().

Applications may elect to operate with the RetransmitMode
set to SNMPAPI_ON or SNMPAPI_OFF at any given point in time.

The RetransmitMode setting is evaluated by the implementation
at SnmpSendMsg() time.

Unless and until a response is received, a message sent when
the RetransmitMode is "on" will result in retries (if a non-
zero retry count is specified for the dstEntity at the time
SnmpSendMsg() is called) and issuance of a timeout notification
to the associated session (when no response is received within
the timeout interval and the retry count is exhausted).

A message sent when RetransmitMode is "off" does not result
in retries and no timeout notification is sent to the
associated session.

See the "Timeout notification methods" clarification for
related information.

See the new SnmpCancelMsg() function for associated
functionality.

5.  Timeout notification methods

The method for notifying a session of a timed out request
message was not specified for WinSNMP v1.

It is specified for WinSNMP v2.

The implementation must return the SNMPAPI_TL_TIMEOUT error
value in wParam and the RequestID of the timed out PDU in
lParam (this is true regardless of the notification mode of
the session...i.e., message-based or callback-based).

Note that for normal request, response, or trap delivery,
the implementation must set wParam to zero and lParam to the
RequestID of the PDU to be retrieved.

Applications should check wParam on all notifications,
regardless of notification mode (message or callback).
If it is non-zero, then its value is one of the "transport
layer" (SNMPAPI_TL_<n>) error codes and the application
does not need to (and should not) call SnmpRecvMsg() in
response to this notification.

However, if the application elects to make the SnmpRecvMsg()
call, then one of three results may occur:

          1.  If there is a pending message for this
              session, the DLL may deliver it at this
              time; or,

          2.  If there is no pending message for this
              session, then SnmpRecvMsg() must return
              SNMPAPI_FAILURE, with SnmpGetLastError()
              set to:

               a.  SNMPAPI_NOOP [8], or

               b.  SNMPAPI_TL_TIMEOUT [108].

Note that if Result 1 obtains, the session may eventually
receive a notification that will yield Result 2a, since
that notification may have happened asynchronously to the
early retrieval of the message.

Note to implementors:  If there is no message pending for the
calling application, then Result 2a is the preferred error
setting.  Result 2b is allowed for backward compatibility
with certain fielded applications.

6.  SNMPv1 Trap-PDU generation

The WinSNMP API is oriented towards SNMPv2.  No standard
function is provided to accommodate the unique fields of an
SNMPv1 Trap-PDU (SNMP_PDU_V1TRAP).  All SNMPv1 and SNMPv2
Trap-PDUs which are received by a WinSNMP implementation
and delivered to applications who requested them via
SnmpRegister(), are delivered as SNMPv2 traps (SNMP_PDU_TRAP).
Furthermore, only SNMPv2 Trap-PDUs can be assembled directly
via SnmpCreatePdu() and/or SnmpSetPduData().

However, WinSNMP entities operating in an agent role may
need to emit traps to non-WinSNMP SNMPv1 targets.  To
accommodate this requirement, the SnmpSendMsg() must
evaluate the SNMP-version level of the dstEntity parameter
of any out-going SNMP_PDU_TRAP message.  If the dstEntity is
an SNMPv1 entity, then the message must be automatically and
transparently converted to an SNMP_PDU_V1TRAP message via
the following procedure:

The WinSNMP API is intended to be a common interface that
provides bilingual protocol support as transparently as
possible.  To this end, the API takes on a "v2-style
interface" in all other areas, and "downgrades" a request
appropriate to communicate with either v1 or v2 agents using
the *SAME* interface.

For example, WinSNMP v1.1a specified that all implementations
(level 1 or 2) must support the GetBulk operator.  However,
if the request is sent to a v1 entity, then the WinSNMP
implementation transparently "downgrades" the GetBulk to a
GetNext request per RFC 1908.  This enables an application
to be coded to always use GetBulk and not care whether the
dstEntity is a v1 or a v2 entity, especially in "translated
mode".

While RFC 1908 does not specify how to "downgrade" an
SNMP_PDU_TRAP message into an SNMP_PDU_V1TRAP message, the
translation is straight forward.  As such, the WinSNMP
interface for sending traps--whether to a v1 or a v2
destination-is stipulated hereby as an SNMPv2 Trap-PDU
(SNMP_PDU_TRAP).

If the dstEntity of an SNMP_TRAP_PDU submitted to
SnmpSendMessage() or SnmpEncodeMsg() is a v1 entity, then
the WinSNMP implementation must "downgrade" (translate)
the trap into an SNMP_PDU_V1TRAP during assembly of the
corresponding SNMP message.

This action taken on out-going SNMP trap messages has no
bearing on SNMP traps received by an implementation.  As
with v1 of the WinSNMP API specification, in all cases,
received traps are presented to WinSNMP applications as
SNMPv2 traps (SNMP_PDU_TRAP).

The translation procedure (e.g., during serialization) is
simply the converse of the v1-to-v2 trap translation that
is already done by WinSNMP implementations when v1traps
are received and presented to the application.  The steps
are defined in Section 3.3 of RFC 2089, "V2ToV1 Mapping
SNMPv2 onto SNMPv1 within a bi-lingual SNMP agent" by Bert
Wijnen and David Levi.

From an implementation perspective, it is straight-forward
and rather easy to implement.  From an application developer
perspective, eliminating the need for the application to
know/care about differences in v1 vs v2 traps enormously
simplifies the application.

The bottom line is that this approach preserves the "single
interface / bilingual protocol" value proposition that
WinSNMP was founded on.  It also eliminates the need for a
new / additional function in the WinSNMP API.

7.  Notification port usage

The term "notification" as used here applies to both traps
(SNMPv1 and SNMPv2c) and informs (SNMPv2c only).  Trap
mapping between entities of different SNMP versions is
described above.  Important details wrt Inform requests are
given in Section II.13, "Inform Processing", below.

InformRequest-PDUs may only be sent to a destination entity
that supports SNMPv2c.  An attempt by an application to send
an InformRequest-PDU to an SNMPv1 destination entity using
SnmpSendMsg() results in SNMPAPI_FAILURE, with SnmpGetLastError()
set to return SNMPAPI_OPERATION_INVALID.

The well-known notification port for any protocol supported
by an implementation (e.g., 162 for UDP and 36880 for IPX)
should be held by an implementation of this WinSNMP API, if
at all, only when there are active SnmpRegister() entries
that might accept an incoming notification message.

Where possible, an implementation should use some de facto or
de jure standard "system service" for receiving notification
messages to be dispatched to registered WinSNMP applications,
such that other (non-WinSNMP) notification targets may operate
concurrently with it.  For Microsoft Windows NT, this standard
mechanism is the "SNMPTRAP" system service.

8.  Request-ID/SnmpCreatePdu()/SnmpSetPdu()

Applications should specify "meaningful" Request-ID values
via SnmpCreatePdu() and/or SnmpSetPduData().

Implementations will automatically assign an arbitrary
Request-ID value when SnmpCreatePdu() is called without a
specified Request-ID value (i.e., the value is zero).  The
SnmpSetPduData() function may be used by an application to
assign any Request-ID value it wants, including a value of
zero.

Implementations must use the resulting Request-ID value at
SnmpSendMsg() time to return the eventual Response-PDU or
timeout notification (if a corresponding Response-PDU is
not received) to the application.

Note that the Request-ID used in the "on-the-wire" messages
is assigned by the implementation independently and may or
may not be the same as the Request-ID used at the application
level for any given message.

9.  SnmpGetPduData() and hVbl

If an hVbl output parameter is specified on a call to
SnmpGetPduData() it will return a new instance of the
VarBindList associated with the corresponding hPdu.

This behavior is consistent with both the basic purpose of
SnmpGetPduData()--which is to de-reference the components of
a received PDU--and a basic characteristic of all WinSNMP
functions which return WinSNMP resource objects (sessions,
entities, contexts, PDUs, and VarBindLists) as outputs...