mirror of https://github.com/tongzx/nt5src
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
734 lines
65 KiB
734 lines
65 KiB
{\rtf1\ansi \deff12\deflang1033{\fonttbl{\f0\froman\fcharset0\fprq2 Tms Rmn{\*\falt Times New Roman};}{\f1\froman\fcharset2\fprq2 Symbol;}{\f2\fswiss\fcharset0\fprq2 Helv;}{\f3\fmodern\fcharset0\fprq1 Courier;}
|
|
{\f4\froman\fcharset0\fprq2 Times New Roman;}{\f5\fswiss\fcharset0\fprq2 Arial;}{\f6\froman\fcharset0\fprq2 MS Serif;}{\f7\fswiss\fcharset0\fprq2 MS Sans Serif;}{\f8\froman\fcharset0\fprq2 Times;}{\f9\fswiss\fcharset0\fprq2 Helvetica;}
|
|
{\f10\fswiss\fcharset0\fprq2 System;}{\f11\fmodern\fcharset0\fprq1 Courier New;}{\f12\froman\fcharset0\fprq2 New York{\*\falt Times New Roman};}{\f13\fswiss\fcharset0\fprq2 Geneva;}{\f14\fswiss\fcharset0\fprq2 AvantGarde;}
|
|
{\f15\froman\fcharset0\fprq2 ITC Bookman;}{\f16\fswiss\fcharset0\fprq2 Helvetica-Narrow;}{\f17\froman\fcharset0\fprq2 NewCenturySchlbk;}{\f18\froman\fcharset0\fprq2 Palatino;}{\f19\froman\fcharset0\fprq2 ZapfChancery;}
|
|
{\f20\fdecor\fcharset2\fprq2 ZapfDingbats;}{\f21\fnil\fcharset2\fprq2 Marlett;}{\f22\fmodern\fcharset0\fprq1 Lucida Console;}{\f23\fswiss\fcharset0\fprq2 Lucida Sans Unicode;}{\f24\fnil\fcharset2\fprq2 Wingdings;}
|
|
{\f25\fswiss\fcharset0\fprq2 Arial Narrow;}{\f26\fswiss\fcharset0\fprq2 Arial Black;}{\f27\froman\fcharset0\fprq2 Book Antiqua;}{\f28\froman\fcharset0\fprq2 Bookman Old Style;}{\f29\froman\fcharset0\fprq2 Century Schoolbook;}
|
|
{\f30\fnil\fcharset2\fprq2 Monotype Sorts;}{\f31\froman\fcharset0\fprq2 Garamond;}{\f32\fmodern\fcharset2\fprq1 MS LineDraw;}{\f33\froman\fcharset255\fprq2 Roman;}{\f34\fscript\fcharset255\fprq2 Script;}{\f35\fmodern\fcharset255\fprq2 Modern;}
|
|
{\f36\fswiss\fcharset0\fprq1 MS Dialog;}{\f37\fswiss\fcharset0\fprq0 Chicago;}{\f38\fmodern\fcharset0\fprq0 Monaco;}{\f39\fscript\fcharset0\fprq0 Venice;}{\f40\fdecor\fcharset0\fprq0 London;}{\f41\fdecor\fcharset0\fprq0 Athens;}
|
|
{\f42\fdecor\fcharset0\fprq0 San Francisco;}{\f43\fnil\fcharset0\fprq0 Cairo;}{\f44\fnil\fcharset0\fprq0 Los Angeles;}{\f45\fnil\fcharset0\fprq0 Zapf Dingbats;}{\f46\fnil\fcharset0\fprq0 Bookman;}{\f47\fnil\fcharset0\fprq0 N Helvetica Narrow;}
|
|
{\f48\fnil\fcharset0\fprq0 Zapf Chancery;}{\f49\fnil\fcharset0\fprq0 Avant Garde;}{\f50\fnil\fcharset0\fprq0 New Century Schlbk;}{\f51\fnil\fcharset0\fprq0 MT Extra;}}{\colortbl;\red0\green0\blue0;\red0\green0\blue255;\red0\green255\blue255;
|
|
\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green128\blue0;\red128\green0\blue128;\red128\green0\blue0;\red128\green128\blue0;
|
|
\red128\green128\blue128;\red192\green192\blue192;}{\stylesheet{\nowidctlpar \f12 \snext0 Normal;}{\s1\sb120\keepn\nowidctlpar \b\f9 \sbasedon0\snext0 heading 1;}{\s2\sb120\keepn\nowidctlpar \b\f9 \sbasedon0\snext0 heading 2;}{
|
|
\s3\sb120\keepn\nowidctlpar\tx1080 \b\f9 \sbasedon0\snext0 heading 3;}{\s4\sb120\keepn\nowidctlpar\tx1080 \b\f9 \sbasedon0\snext0 heading 4;}{\s5\sb120\keepn\nowidctlpar\tx1440 \b\f9 \sbasedon0\snext0 heading 5;}{\*\cs10 \additive Default Paragraph Font;}
|
|
{\s15\li720\nowidctlpar\tx1980\tqr\tldot\tx9000 \f9\fs20 \sbasedon0\snext0 toc 5;}{\s16\li540\nowidctlpar\tx1620\tqr\tldot\tx9000 \f9\fs20 \sbasedon0\snext0 toc 4;}{\s17\li360\nowidctlpar\tx1260\tqr\tldot\tx9000 \f9\fs20 \sbasedon0\snext0 toc 3;}{
|
|
\s18\li180\sb60\nowidctlpar\tx900\tqr\tldot\tx9000 \f9\fs20 \sbasedon0\snext0 toc 2;}{\s19\sb100\nowidctlpar\tx540\tqr\tldot\tx9000 \f9\fs20 \sbasedon0\snext0 toc 1;}{\s20\nowidctlpar\tqc\tx4320\tqr\tx8640 \f12 \sbasedon0\snext0 footer;}{
|
|
\s21\nowidctlpar\tqc\tx4320\tqr\tx8640 \f12 \sbasedon0\snext0 header;}{\s22\qj\li360\ri360\sb100\nowidctlpar \f12\fs20 \sbasedon0\snext0 Normal Indent;}{\s23\qj\sb100\nowidctlpar \f12\fs20 \sbasedon0\snext23 Norm Justified;}{
|
|
\s24\fi-720\li720\sb60\nowidctlpar\tx720\tx1440\tx2160 \f3\fs20 \sbasedon23\snext24 Code Text;}{\s25\qc\sb100\nowidctlpar \b\f9\fs20 \sbasedon0\snext25 Diagram;}{\s26\qj\fi-288\li1008\sa240\keep\nowidctlpar\tx1008 \f8\fs20 \sbasedon0\snext26 Ref List;}{
|
|
\s27\qj\fi-720\li720\sb100\nowidctlpar \f12\fs20 \sbasedon23\snext27 Reference;}{\s28\qj\li1080\ri1080\nowidctlpar \f12\fs20 \sbasedon0\snext28 Confidentiality;}{\s29\qj\sb100\nowidctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 \sbasedon23\snext29
|
|
ParmListHdr;}{\s30\qj\fi-2880\li2880\sb100\nowidctlpar\tx2880 \f12\fs20 \sbasedon23\snext30 ParmListEntry;}{\s31\fi-720\li720\sb60\nowidctlpar\tx720\tx1440\tx2160 \f3\fs18 \sbasedon24\snext31 Appx Code Text;}{\s32\qj\li720\sb100\nowidctlpar\brdrb
|
|
\brdrs\brdrw15 \tx5040 \b\f9\fs20 \sbasedon29\snext32 Inset ParmListHdr;}{\s33\qj\fi-4320\li5040\sb100\nowidctlpar\tx5040 \f12\fs20 \sbasedon30\snext33 Inset ParmListEntry;}}{\info{\author Don Ryan}{\operator Don Ryan}{\creatim\yr1996\mo4\dy10\hr12\min52}
|
|
{\revtim\yr1996\mo9\dy27\hr10\min37}{\version2}{\edmins3}{\nofpages33}{\nofwords5710}{\nofchars32549}{\*\company Microsoft Corporation}{\vern57443}}\margl1440\margr1440 \widowctrl\ftnbj\aenddoc\ftnrestart\revisions\hyphcaps0 \fet0\sectd
|
|
\pgnrestart\linex0\endnhere {\*\pnseclvl1\pnucrm\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl2\pnucltr\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl3\pndec\pnstart1\pnindent720\pnhang{\pntxta .}}{\*\pnseclvl4
|
|
\pnlcltr\pnstart1\pnindent720\pnhang{\pntxta )}}{\*\pnseclvl5\pndec\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl6\pnlcltr\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl7\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}
|
|
{\pntxta )}}{\*\pnseclvl8\pnlcltr\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}{\*\pnseclvl9\pnlcrm\pnstart1\pnindent720\pnhang{\pntxtb (}{\pntxta )}}\pard\plain \qc\widctlpar \f12 {\b\fs28
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par }{\b\f9\fs36 Microsoft Windows NT
|
|
\par SNMP Programmer's Reference
|
|
\par }{\b\fs28
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par
|
|
\par }{\fs20 May 16, 1996
|
|
\par }\pard \widctlpar \sect \sectd \linex0\endnhere {\header \pard\plain \s21\qc\widctlpar \f12 {\b\f9\fs20 Microsoft Windows NT SNMP Programmer's Reference
|
|
\par }}{\footer \pard\plain \s20\widctlpar\tqc\tx4680\tqr\tx9360 \f12 {\b\f9\fs20 \tab \chpgn \tab
|
|
\par }}\pard\plain \s1\sb120\keepn\widctlpar \b\f9 1.\tab Introduction\tab
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 This document describes the Simple Network Management Protocol (SNMP) application programming interfaces (APIs) for Windows NT.
|
|
\par These APIs support the development of SNMP manager applications and extensions to the Windows NT SNMP agent application
|
|
. A SNMP agent application is a SNMP application entity that responds to queries from SNMP manager applications and generates traps to SNMP manager applications. A SNMP manager application is a SNMP application entity that generates queries to SNMP agen
|
|
t applications and receives traps generated by SNMP agent applications.
|
|
\par The Windows NT SNMP agent application employs a simple subagent multiplexing design which makes it easy for independent software vendors (ISVs) to supply additional variables from various Management Information Bases (MIBs). During initialization,
|
|
each subagent is asked to register the MIB view it supports and a list of subagents and their supported MIB views is constructed and lexographically sorted. When an incoming request is being serviced, each object identifier (OID) from the request is comp
|
|
ared to the entries of the subagent supported MIB view list and the request is divided into separate queries for each corresponding subagent. Microsoft currently ships subagents for RFC1213-MIB and LanMgr-Mib-II. The extensible a
|
|
gent is implemented as a Win32 Service, and the subgents are implemented as Win32 Dynamic Link Libraries (DLLs).
|
|
\par The Windows NT SNMP Management APIs allow multiple management consoles to operate on a single host computer by sharing access to resources like the SNMPTRAP port. A SNMP manager application would use
|
|
the Management APIs to send GET, SET, or GETNEXT requests to a SNMP agent application or to simply listen for traps from a SNMP agent application. The Management APIs are implemented as a Win32 DLL (note
|
|
the trap-related functions are only available when the SNMP Trap Service is running).
|
|
\par Miscellaneous utility APIs are also provided to assist with comparing, copying, and freeing allocated data structures, among other operations.
|
|
\par \pard\plain \s1\sb120\keepn\widctlpar \b\f9 2.\tab Application Program Interfaces
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 There are three categories of APIs provided: Agent, Manager, and Utility.
|
|
\par Wherever possible, the low-level details of SNMP have been hidden by these APIs. Abstract Syntax Notation One (ASN.1) and its Basic Encoding Rules (BER)
|
|
are not exposed by these APIs. The formatting and parsing of SNMP packets, and the communications code that sends/receives SNMP packets on the network are not exposed by these APIs.
|
|
\par The APIs utilize type definitions for SNMP variables, SNMP variable bindings, and SNMP variable bindings lists. These definitions along with the API parameters comprise the interface exposed to the ISV developing a SNMP agent extension
|
|
or manager application.
|
|
\par Agent APIs define the interface between the Windows NT extensible agent and the ISV-developed subagent DLLs.
|
|
\par Manager APIs define the interface between ISV-developed manager applications and the Management API DLL.
|
|
\par Utility APIs are provided to simplify manipulation of the type definitions discussed above, and perform other miscellaneous operations.
|
|
\par This results in the SNMP developer being able to concentrate on the task of providing or requesting management informati
|
|
on without having to be concerned with socket programming, message generation and parsing, ASN.1 BER encoding and decoding, and other low-level details of SNMP. This greatly simplifies the task of developing SNMP agent extensions
|
|
and manager applications.
|
|
\par \pard\plain \s2\sb120\keepn\widctlpar \b\f9 \page 2.1.\tab Agent APIs
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 Agent APIs define the interface between the Windows NT extensible agent and ISV-developed subagent DLLs.
|
|
\par These APIs are implemented by the ISV developing the subagent DLL and are called by the extensible agent provided by Microsoft. Some may view these as similar to callbacks. No active thread of execution is required in a subagent
|
|
DLL, but may be implemented if necessary to provided the desired functionality (neither of the Microsoft subagent DLLs discussed earlier contain an active thread of execution).
|
|
\par These ISV-developed subagent DLLs are dynamically linked by the extensible agent at run-time. The extensible agent determines what subagent DLLs need to be loaded by referring to its parameters in the Registry.
|
|
\par There are four Agent APIs: SnmpExtensionInit(), SnmpExtensionInitEx(), SnmpExtensionQuery(), and SnmpExtensionTrap(). SnmpExtensionInitEx() is optional and is designed for subagents who support multiple MIB views within the same DLL. SnmpExtensionTrap
|
|
() is optional and is designed for subagents who require trap generation capabilities.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 2.1.1.\tab SnmpExtensionInit()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpExtensionInit(
|
|
\par IN DWORD dwTimeZeroReference,
|
|
\par OUT HANDLE *hPollForTrapEvent,
|
|
\par OUT AsnObjectIdentifier *supportedView)
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpExtensionInit} function exported by the ISV-developed subagent DLL is called by the extensible agent during the extensible agent\rquote s service startup to exchange configuration information.
|
|
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 dwTimeZeroReference \tab Specifies a time-zero reference for the subagent.
|
|
\par hPollForTrapEvent \tab Points to a handle for an event that will be signaled when the {\b\f9 SnmpExtensionTrap} entry point should be polled by the extensible agent. If traps are not generated by the subagent, NULL should be returned.
|
|
\par supportedView \tab Points to an AsnObjectIdentifier specifying the MIB sub-tree supported by the subagent.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }The dwTimeZeroReference allows all subagents to report time information from the same reference point. The subagent can compute elapsed time by subtracting dwTimeZeroReference from the value returned by {\b\f9 GetCurrentTime}
|
|
. This time reference is necessary to implement traps, and possibly some MIB variables.
|
|
\par The subagent may need to generate traps for a variety of reasons. The hPollForTrapEvent is provided to support this functionality. The event handle is created by the subagent during initialization by calling {\b\f9 CreateEvent}. When this event is
|
|
signaled, the extensible agent will call the {\b\f9 SnmpExtensionTrap} entry point and use the returned information to send a trap to each destination listed in the Registry.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpExtensionTrap(), GetCurrentTime(), CreateEvent(), SetEvent().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.1.2.\tab SnmpExtensionInitEx()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpExtensionInit(
|
|
\par \tab OUT AsnObjectIdentifier *supportedView)
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpExtensionInitEx} function exported by the ISV-developed subagent DLL is called by the extensible agent during the extensible agent\rquote s service
|
|
startup to exchange additional configuration information.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 supportedView \tab Points to an AsnObjectIdentifier specifying the MIB sub-tree supported by the subagent.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If supportedView has been initialized with an additional MIB sub-tree, the return value is TRUE.
|
|
\par If there are no more MIB sub-trees to register, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }The extensible agent repeatedly calls the {\b SnmpExtensionInitEx} entry point in order to give subagents a chance to register support for additional MIB views. The subagent must keep track of which MIB views have already been registered.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpExtensionInit().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.1.3.\tab SnmpExtensionQuery()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpExtensionQuery(
|
|
\par IN BYTE requestType,
|
|
\par IN OUT RFC1157VarBindList *variableBindings,
|
|
\par OUT AsnInteger *errorStatus,
|
|
\par OUT AsnInteger *errorIndex)
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpExtensionQuery} function exported by the subagent DLL is called by the extensible agent to resolve SNMP requests containing variables within one or more of the subagent\rquote
|
|
s registered MIB views.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 requestType \tab Specifies the SNMP request type from the following list:
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 requestType\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 ASN_RFC1157_GETREQUEST\tab Indicates SNMP Get Request.
|
|
\par ASN_RFC1157_GETNEXTREQUEST\tab Indicates SNMP Get Next Request.
|
|
\par ASN_RFC1157_SETREQUEST\tab Indicates SNMP Set Request.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 variableBindings \tab Points to the variable bindings list.
|
|
\par errorStatus \tab Points to variable to receive the resulting error status from the following list
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 errorStatus\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 ASN_ERRORSTATUS_NOERROR\tab Indicates the noError error status.
|
|
\par ASN_ERRORSTATUS_TOOBIG\tab Indicates the tooBig error status.
|
|
\par ASN_ERRORSTATUS_NOSUCHNAME\tab Indicates the noSuchName error status.
|
|
\par ASN_ERRORSTATUS_BADVALUE\tab Indicates the badValue error status.
|
|
\par ASN_ERRORSTATUS_READONLY\tab Indicates the readOnly error status.
|
|
\par ASN_ERRORSTATUS_GENERR\tab Indicates the genError error status.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 errorIndex \tab Points to variable to receive the resulting error index.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }This entry point is called when the extensible agent must resolve a GET, GETNEXT, or SET operation within the subtree registered by the subagent during initialization. For GET or SET operations, the ISV must follow the rules in RFC 1157
|
|
to resolve the variable bindings or generate an error.
|
|
\par The GETNEXT operation is more complicated to process. The requested variable may not be resolvable by this subagent. If it can be resolved by this subagent, the ISV must follow the rules in RFC 1157 to resolve the var
|
|
iable bindings or generate an error. If it cannot be resolved by this subagent, the ISV must alter the name field of the variable binding to point just past the supportedView provided by {\b\f9 SnmpExtensionInit}
|
|
. If the agent's supported view was ".1.3.6.1.4.1.77.1", a GETNEXT request using variable ".1.3.6.1.4.1.77.1.5.1" would result in the name field being modified to be ".1.3.6.1.4.1.77.2". This signals the extensible a
|
|
gent to continue to attempt to resolve such variable bindings with other subagents.
|
|
\par It is important to note that during the {\b SnmpExtensionQuery} call, the extensible agent will be allocating dynamic memory that may be released by the subagent (if the object identifier needs to be modified)
|
|
and the subagent will be allocating dynamic memory that may be released by the extensible agent (if the object identifier was modified or if the value of the requested variable was an object identifer or a dynamically allocated string). It is therefore
|
|
critical that both the extensible agent and the subagent use allocation routines that resolve to the same heap. Originally, the ISVs developing Windows NT subagents were encouraged to use malloc() and free(). Unfortunately,
|
|
different versions of the C runtime implemented these functions differently. In the Windows NT 3.51 release, a pair of macros were introduced, SNMP_malloc() and SNMP_free(), which simply resolved to GlobalAlloc() and GlobalFree().
|
|
Although this solved the problem of the extensible agent and the subagent using different allocation routines, it did not provide a means for easily debugging memory leaks. In the Windows NT 4.0 release, the macros have been replaced by two entry points
|
|
, {\b SnmpUtilMemAlloc}() and {\b SnmpUtilMemFree}(), in a new utility DLL (SNMPAPI.DLL). Subagents should use these two functions (SNMP_malloc() and SNMP_free() now resolve to these functions) and should not assume they resolve to
|
|
GlobalAlloc() and GlobalFree() or any other specific heap routine.
|
|
\par
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpExtensionInit(), SnmpExtensionInitEx(), RFC 1157.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.1.4.\tab SnmpExtensionTrap()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpExtensionTrap(
|
|
\par OUT AsnObjectIdentifier *enterprise,
|
|
\par OUT AsnInteger *genericTrap,
|
|
\par OUT AsnInteger *specificTrap,
|
|
\par OUT AsnTimeticks *timeStamp,
|
|
\par OUT RFC1157VarBindList *variableBindings)
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpExtensionTrap} function exported by the subagent DLL is called by the extensible agent to retrieve subagent generated traps.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 enterprise \tab Points to an object identifier indicating the originating enterprise generating the trap.
|
|
\par genericTrap \tab Points to an indication of the generic trap generated from the following list:
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 genericTrap\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 SNMP_GENERICTRAP_COLDSTART\tab Indicates Cold Start trap.
|
|
\par SNMP_GENERICTRAP_WARMSTART\tab Indicates Warm Start trap.
|
|
\par SNMP_GENERICTRAP_LINKDOWN\tab Indicates Link Down trap.
|
|
\par SNMP_GENERICTRAP_LINKUP\tab Indicates Link Up trap.
|
|
\par SNMP_GENERICTRAP_AUTHFAILURE\tab Indicates Authentication Failure trap.
|
|
\par SNMP_GENERICTRAP_EGPNEIGHLOSS\tab Indicates EGP Neighbor Loss trap.
|
|
\par SNMP_GENERICTRAP_ENTERSPECIFIC\tab Indicates Enterprise Specific trap.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 specificTrap \tab Points to an indication of the specific trap generated.
|
|
\par timeStamp \tab Points to variable to receive the time-stamp.
|
|
\par variableBindings \tab Points to the variable bindings list.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function returned a trap in its parameters, the return value is TRUE. The function is called repeatedly by the extensible agent until a return value of FALSE is returned.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }This function is repeatedly called by the extensible agent once hPollForTrapEvent has been signaled. Each successful call returns a single trap's data in its parameters. It returns FALSE to indicate that it\rquote
|
|
s parameters do not represent valid trap data and to stop the extensible agent's repeated calls.
|
|
\par It is important to note that earlier documentation stated that the enterprise OID returned by the subagent must be dynamically allocated because the extensible agent would attempt to release the memory after sending the trap. This may have been how the
|
|
function was originally designed but it was not implemented like this in the extensible agent of any release of Windows NT. The subagent should not expect the extensible agent to attempt to release the memory associated with the enterprise OID.
|
|
It is recommended instead that you simply return a pointer to a static OID structure.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpExtensionInit().
|
|
\par \pard\plain \s2\sb120\keepn\widctlpar \b\f9 \page 2.2.\tab Manager APIs
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 Manager APIs define the interface between ISV-developed Manager Applications and the Management API DLL.
|
|
\par These APIs are provided by the Management API DLL. In the Windows NT 3.51 release and earlier, a detached process is used to receive SNMP traps and dispatch them to the Manager Applications that have registered to receive SNMP traps via
|
|
SnmpMgrTrapListen(). In the Windows NT 4.0 release, a separate SNMP Trap Service has been introduced so that SNMP Manager applications not using the Manager API can control the acquistion of the SNMPTRAP port Note that t
|
|
he SNMP Trap Service must be started before Manager applications can successfully call SnmpMgrTrapListen(). The Manager APIs are synchronous except the APIs dealing with SNMP traps, which are either polled or notification based.
|
|
\par The ISV-developed Manager Application links with this DLL to gain access to its services.
|
|
\par There are several Manager APIs: SnmpMgrOpen(), SnmpMgrClose(), SnmpMgrRequest(), SnmpMgrStrToOid(), SnmpMgrOidToStr(), SnmpMgrTrapListen(), and SnmpMgrGetTrap(). SnmpMgrOpen(), SnmpMgrClose(), and SnmpMgrRequest() are the primary APIs. SnmpMgrStrToOid(
|
|
) and SnmpMgrOidToStr() are only accessed if their respective conversions of Object Identifiers to/from Object Descriptors are desired. SnmpMgrTrapListen() and SnmpMgrGetTrap() are only accessed if trap reception is desired.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 2.2.1.\tab SnmpMgrOpen()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 LPSNMP_MGR_SESSION SnmpMgrOpen(
|
|
\par IN LPSTR lpAgentAddress, // Name/address of target SNMP agent
|
|
\par IN LPSTR lpAgentCommunity, // Community for target SNMP agent
|
|
\par IN INT nTimeOut, // Communication time-out in milliseconds
|
|
\par IN INT nRetries) // Communication time-out/retry count
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrOpen} function initializes communications sockets and data structures allowing communications with the specified agent.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 lpAgentAddress \tab Points to a null-terminated string specifying either a dotted-decimal IP address, or a host name that can be resolved to an IP address.
|
|
\par lpAgentCommunity \tab Points to a null-terminated string specifying the SNMP Community Name used when communicating with the agent specified in lpAgentAddress.
|
|
\par nTimeOut \tab Specifies the communications time-out in milliseconds.
|
|
\par nRetries \tab Specifies the communications retry count. The time-out specified in nTimeOut is doubled each time a retry attempt is transmitted.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is a pointer to a LPSNMP_MGR_SESSION structure. This structure is used internally and should not be altered by the programmer.
|
|
\par If the function fails, the return value is NULL. Use the {\b\f9 GetLastError} function to obtain extended error information.
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 GetLastError()\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 SNMP_MEM_ALLOC_ERROR\tab Indicates error allocating memory.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrClose(), SnmpMgrRequest().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.2.2.\tab SnmpMgrClose()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpMgrClose(
|
|
\par IN LPSNMP_MGR_SESSION session) // SNMP session pointer
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrClose} function closes communications socket and data structures associated with the specified session.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 session \tab Points to a LPSNMP_MGR_SESSION structure specifying the session to close.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE. Use the {\b\f9 GetLastError} function to obtain extended error information.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrOpen(), SnmpMgrRequest().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.2.3.\tab SnmpMgrRequest()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 SNMPAPI SnmpMgrRequest(
|
|
\par IN LPSNMP_MGR_SESSION session, // SNMP session pointer
|
|
\par IN BYTE requestType, // Get, GetNext, or Set
|
|
\par IN OUT RFC1157VarBindList *variableBindings, // Varible bindings
|
|
\par OUT AsnInteger *errorStatus, // Result error status
|
|
\par OUT AsnInteger *errorIndex) // Result error index
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrRequest} function requests the specified operation be performed with the specified agent.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 session \tab Points to a LPSNMP_MGR_SESSION structure specifying the session that will perform the request.
|
|
\par requestType \tab Specifies the SNMP request type from the following list:
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 requestType\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 ASN_RFC1157_GETREQUEST\tab Indicates SNMP Get Request.
|
|
\par ASN_RFC1157_GETNEXTREQUEST\tab Indicates SNMP Get Next Request.
|
|
\par ASN_RFC1157_SETREQUEST\tab Indicates SNMP Set Request.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 variableBindings \tab Points to the variable bindings list.
|
|
\par errorStatus \tab Points to variable to receive the resulting error status from the following list (see sections 4.1.2, 4.1.3, and 4.1.5 of RFC 1157 to understand the meaning of these errors for the supplied requestType):
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 errorStatus\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 ASN_ERRORSTATUS_NOERROR\tab Indicates the noError error status.
|
|
\par ASN_ERRORSTATUS_TOOBIG\tab Indicates the tooBig error status.
|
|
\par ASN_ERRORSTATUS_NOSUCHNAME\tab Indicates the noSuchName error status.
|
|
\par ASN_ERRORSTATUS_BADVALUE\tab Indicates the badValue error status.
|
|
\par ASN_ERRORSTATUS_READONLY\tab Indicates the readOnly error status.
|
|
\par ASN_ERRORSTATUS_GENERR\tab Indicates the genError error status.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 errorIndex \tab Points to variable to receive the resulting error index.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is NULL. Use the {\b\f9 GetLastError} function to obtain extended error information.
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 GetLastError()\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 SNMP_MGMTAPI_TIMEOUT\tab Request timed-out.
|
|
\par SNMP_MGMTAPI_SELECT_FDERRORS\tab Unexpected error file descriptors indicated by select().
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }For GET and GETNEXT requests, each variable in the variableBindings must be initialized to type ASN_NULL. .
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrOpen(), SnmpMgrClose(), RFC 1157.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.2.4.\tab SnmpMgrStrToOid()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpMgrStrToOid(
|
|
\par IN LPSTR string, // OID string to be converted
|
|
\par OUT AsnObjectIdentifier *oid) // OID internal representation
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrStrToOid} function converts a string OBJECT IDENTIFIER or OBJECT DESCRIPTOR representation to an internal AsnObjectIdentifier.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 string \tab Points to a NULL terminated string to be converted.
|
|
\par oid \tab Points to an AsnObjectIdentifier variable to receive the converted value.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrOidToStr(), MibCC.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.2.5.\tab SnmpMgrOidToStr()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpMgrOidToStr(
|
|
\par OUT AsnObjectIdentifier oid, // OID internal rep to be converted
|
|
\par IN LPSTR string) // OID string representation
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrStrToOid} function converts an internal AsnObjectIdentifier to a string OBJECT IDENTIFIER or OBJECT DESCRIPTOR representation.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 oid \tab Points to an AsnObjectIdentifier to be converted.
|
|
\par string \tab Points to a NULL terminated string to receive the converted value.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrStrToOid(), MibCC.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.2.6.\tab SnmpMgrTrapListen()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpMgrTrapListen(
|
|
\par OUT HANDLE *phTrapAvailable) // Event handle indicating trap(s) available
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrTrapListen} function registers the desire to receive SNMP traps.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 phTrapAvailable \tab Points to an event that is asserted when new traps have been received.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE. Use the {\b\f9 GetLastError} function to obtain extended error information.
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 GetLastError()\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 SNMP_MGMTAPI_TRAP_DUPINIT\tab This function has already been called.
|
|
\par SNMP_MGMTAPI_AGAIN\tab Error encountered, can attempt call again.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }The phTrapAvailable event is provided to allow event-driven acquisition of SNMP traps. It can be ignored and the {\b\f9 SnmpMgrGetTrap} function can be polled at regular intervals.
|
|
\par Or, a thread could be created waiting on the event using {\b\f9 WaitForSingleObject}. When the event is asserted, this thread should clear the event using {\b\f9 ResetEvent}, and then repeatedly call the {\b\f9 SnmpMgrGetTrap}
|
|
function until it returns FALSE.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrGetTrap(), WaitForSingleObject(), ResetEvent().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.2.7.\tab SnmpMgrGetTrap()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 BOOL SnmpMgrGetTrap(
|
|
\par OUT AsnObjectIdentifier *enterprise, // Generating enterprise
|
|
\par OUT AsnInteger *genericTrap, // Generic trap type
|
|
\par OUT AsnInteger *specificTrap, // Enterprise specific type
|
|
\par OUT AsnTimeticks *timeStamp, // Time stamp
|
|
\par OUT RFC1157VarBindList *variableBindings) // Variable bindings
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpMgrGetTrap} function returns outstanding trap data that the caller has not yet received.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 enterprise \tab Points to an object identifier indicating the originating enterprise generating the trap.
|
|
\par genericTrap \tab Points to an indication of the generic trap generated from the following list:
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 genericTrap\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 SNMP_GENERICTRAP_COLDSTART\tab Indicates Cold Start trap.
|
|
\par SNMP_GENERICTRAP_WARMSTART\tab Indicates Warm Start trap.
|
|
\par SNMP_GENERICTRAP_LINKDOWN\tab Indicates Link Down trap.
|
|
\par SNMP_GENERICTRAP_LINKUP\tab Indicates Link Up trap.
|
|
\par SNMP_GENERICTRAP_AUTHFAILURE\tab Indicates Authentication Failure trap.
|
|
\par SNMP_GENERICTRAP_EGPNEIGHLOSS\tab Indicates EGP Neighbor Loss trap.
|
|
\par SNMP_GENERICTRAP_ENTERSPECIFIC\tab Indicates Enterprise Specific trap.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 specificTrap \tab Points to an indication of the specific trap generated.
|
|
\par timeStamp \tab Points to variable to receive the time-stamp.
|
|
\par variableBindings \tab Points to the variable bindings list.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function returned a trap in its parameters, the return value is TRUE. The function should be called repeatedly until a return value of FALSE is returned with {\b\f9 GetLastError()} indicating either an error or SNMP_MGMTAPI_NOTRAPS.
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 GetLastError()\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 SNMP_MGMTAPI_TRAP_ERRORS\tab Errors encountered, traps not accessible.
|
|
\par SNMP_MGMTAPI_NOTRAPS\tab No traps are available.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }The phTrapAvailable event from {\b\f9 SnmpMgrTrapListen} is provided to allow event-driven acquisition of SNMP traps. It can be ignored and this function can be polled at regular intervals.
|
|
\par Or, a thread could be created waiting on the event using {\b\f9 WaitForSingleObject}. When the event is asserted, this thread should clear the event using {\b\f9 ResetEvent}, and then repeatedly call the this function until it returns FALSE.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpMgrTrapListen(), WaitForSingleObject(), ResetEvent().
|
|
\par \pard\plain \s2\sb120\keepn\widctlpar \b\f9 \page 2.3.\tab Utility APIs
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 Utility APIs are provided to simplify manipulation of the type definitions discussed above, and perform other miscellaneous operations.
|
|
\par In the Windows NT 3.51 release and earilier, these APIs were provided by the SNMP static library, {\b\f9 SNMP.LIB}. In the Windows NT 4.0 release, these APIs are provided by the SNMP utility DLL,{\b }{\b\f9 SNMPAPI.DLL}, and it\rquote s import library,
|
|
{\b\f9 SNMPAPI.LIB}.
|
|
\par The ISV developed Application links with this library to gain access to its services.
|
|
\par There are several Utility APIs: SnmpUtilMemAlloc(), SnmpUtilMemFree(), SnmpUtilMemReAlloc(), SnmpUtilOi
|
|
dCpy(), SnmpUtilOidAppend(), SnmpUtilOidNCmp(), SnmpUtilOidCmp(), SnmpUtilOidFree(), SnmpUtilVarBindListCpy(), SnmpUtilVarBindCpy(), SnmpUtilVarBindListFree(), SnmpUtilVarBindFree(), and SnmpUtilPrintAsnAny().
|
|
\par Care should be taken to insure that dynamic memory is allocated with SnmpUtilMemAlloc() and is released with SnmpUtilMemFree(). The extensible agent and all of the Utility APIs use these routines exclusively.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 2.3.1.\tab SnmpUtilMemAlloc()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 LPVOID SnmpUtilMemAlloc(
|
|
\par \tab IN UINT Size // number of bytes to allocate
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilMemAlloc} function allocates the specified number of bytes from the heap.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 Size \tab Specifies the number of bytes to allocate.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is a pointer to the newly allocated memory object.
|
|
\par If the function fails, the return value is NULL.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Memory should be released using {\b\f9 SnmpUtilMemFree}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilMemFree(), SnmpUtilMemReAlloc().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.2.\tab SnmpUtilMemFree()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 VOID SnmpUtilMemFree(
|
|
\par \tab IN LPVOID Addr // pointer to the memory object
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilMemFree} function frees the specified memory object.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 Addr \tab Specifies the memory object to release.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }None.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Memory should be allocated using {\b\f9 SnmpUtilMemAlloc}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilMemAlloc(), SnmpUtilMemReAlloc().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.3.\tab SnmpUtilMemReAlloc()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 LPVOID SnmpUtilMemReAlloc(
|
|
\par \tab IN LPVOID Addr, // pointer to the memory object
|
|
\par \tab IN UINT Size // number of bytes to allocate
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilMemReAlloc} function changes the size of the specified memory object.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 Addr \tab Specifies the memory object to resize.
|
|
\par Size \tab Specifies the new size of the memory object.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is a pointer to the newly allocated memory object.
|
|
\par If the function fails, the return value is NULL.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Memory should be released using {\b\f9 SnmpUtilMemFree}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilMemAlloc(), SnmpUtilMemFree().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.4.\tab SnmpUtilOidCpy()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 SNMPAPI SnmpUtilOidCpy(
|
|
\par OUT AsnObjectIdentifier *DestObjId, // Destination OID
|
|
\par IN AsnObjectIdentifier *SrcObjId // Source OID
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidCpy} function copies the SrcObjId to the DestObjId allocating any necessary memory for the destination's copy.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 DestObjId \tab Points to an AsnObjectIdentifier variable to receive the copy.
|
|
\par SrcObjId \tab Points to an AsnObjectIdentifier variable to copy.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Any memory allocated for the destination can be freed using {\b\f9 SnmpUtilOidFree}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilOidFree().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.5.\tab SnmpUtilOidAppend()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 SNMPAPI SnmpUtilOidAppend(
|
|
\par IN OUT AsnObjectIdentifier *DestObjId, // Destination OID
|
|
\par IN AsnObjectIdentifier *SrcObjId // Source OID
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidAppend} function appends the SrcObjId to the DestObjId reallocating any necessary memory for the destination's copy.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 DestObjId \tab Points to an AsnObjectIdentifier variable to receive the copy.
|
|
\par SrcObjId \tab Points to an AsnObjectIdentifier variable to copy.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Any memory allocated for the destination can be freed using {\b\f9 SnmpUtilOidFree}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilOidFree().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.6.\tab SnmpUtilOidNCmp()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 int SnmpUtilOidNCmp(
|
|
\par IN AsnObjectIdentifier *A, // First OID
|
|
\par IN AsnObjectIdentifier *B, // Second OID
|
|
\par IN UINT Len // Max len to compare
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidNCmp} function compares Len sub-identifiers of A and B.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 A \tab Points to an AsnObjectIdentifier variable to compare.
|
|
\par B \tab Points to an AsnObjectIdentifier variable to compare.
|
|
\par Len \tab Indicates the number of sub-identifiers to compare.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }The function returns a value greater than zero if A is greater than B, zero if A equals B, and less than zero if A is less than B.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilOidCmp().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.7.\tab SnmpUtilOidCmp()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 int SnmpUtilOidCmp(
|
|
\par IN AsnObjectIdentifier *A, // First OID
|
|
\par IN AsnObjectIdentifier *B, // Second OID
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidCmp} function compares object identifiers A and B.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 A \tab Points to an AsnObjectIdentifier variable to compare.
|
|
\par B \tab Points to an AsnObjectIdentifier variable to compare.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }The function returns a value greater than zero if A is greater than B, zero if A equals B, and less than zero if A is less than B.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilOidNCmp().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.8.\tab SnmpUtilOidFree()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 void SnmpUtilOidFree(
|
|
\par IN OUT AsnObjectIdentifier *Obj // OID to free
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidFree} function frees any allocated data associated with Obj.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 Obj \tab Points to an AsnObjectIdentifier variable whose allocated data should be freed.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }None.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }None.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.9.\tab SnmpUtilVarBindListCpy()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 SNMPAPI SnmpUtilVarBindListCpy(
|
|
\par RFC1157VarBindList *dst, // Destination var bind list
|
|
\par RFC1157VarBindList *src // Source var bind list
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidCpy} function copies the RFC1157VarBindList allocating any necessary memory for the destination's copy.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 dst \tab Points to an RFC1157VarBindList to receive the copy.
|
|
\par src \tab Points to an RFC1157VarBindList to copy.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Any memory allocated for the destination can be freed using {\b\f9 SnmpUtilVarBindListFree}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilVarBindListFree().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.10.\tab SnmpUtilVarBindCpy()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 SNMPAPI SnmpUtilVarBindCpy(
|
|
\par RFC1157VarBind *dst, // Destination var bind
|
|
\par RFC1157VarBind *src // Source var bind
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilOidCpy} function copies the RFC1157VarBind allocating any necessary memory for the destination's copy.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 dst \tab Points to an RFC1157VarBind to receive the copy.
|
|
\par src \tab Points to an RFC1157VarBind to copy.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }If the function is successful, the return value is TRUE.
|
|
\par If the function fails, the return value is FALSE.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }Any memory allocated for the destination can be freed using {\b\f9 SnmpUtilVarBindFree}.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }SnmpUtilVarBindFree().
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.11.\tab SnmpUtilVarBindListFree()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 void SnmpUtilVarBindListFree(
|
|
\par RFC1157VarBindList *VarBindList // Variable bindings list to free
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilVarBindListFree} function frees any allocated data associated with VarBindList.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 VarBindList \tab Points to an RFC1157VarBindList whose allocated data should be freed.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }None.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }None.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.12.\tab SnmpUtilVarBindFree()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 void SnmpUtilVarBindFree(
|
|
\par RFC1157VarBind *VarBind // Variable binding to free
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilVarBindFree} function frees any allocated data associated with VarBind.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 VarBindList \tab Points to an RFC1157VarBind whose allocated data should be freed.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }None.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }None.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 2.3.13.\tab SnmpUtilPrintAsnAny()
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 void SnmpUtilPrintAsnAny(
|
|
\par IN AsnAny *Any
|
|
\par );
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 SnmpUtilPrintAsnAny} function prints the value of Any to stdout.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Parameter\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 Any\tab Points to an AsnAny structure whose value is to be printed.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Returns}{\b
|
|
\par }None.
|
|
\par {\b\f9 Comments}{\b
|
|
\par }This function is provided for debugging and development purposes. It does not generally print the data in forms a Manager Applications would normally need.
|
|
\par This function determines the type of data from the AsnAny structure which was probably set internally by referring to a BER tag value in an encoded stream.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }AsnAny.
|
|
\par \pard\plain \s1\sb120\keepn\widctlpar \b\f9 \page 3.\tab Structures and Types
|
|
\par \pard\plain \s2\sb120\keepn\widctlpar \b\f9 3.1.\tab Structures
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.1.1.\tab AsnAny
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef struct \{
|
|
\par BYTE asnType;
|
|
\par union \{
|
|
\par // RFC 1155 SimpleSyntax (subset of ISO ASN.1)
|
|
\par AsnInteger number;
|
|
\par AsnOctetString string;
|
|
\par AsnObjectIdentifier object;
|
|
\par
|
|
\par // ISO ASN.1
|
|
\par AsnSequence sequence;
|
|
\par
|
|
\par // RFC 1155 ApplicationSyntax
|
|
\par AsnIPAddress address;
|
|
\par AsnCounter counter;
|
|
\par AsnGauge gauge;
|
|
\par AsnTimeticks ticks;
|
|
\par AsnOpaque arbitrary;
|
|
\par \} asnValue;
|
|
\par \} AsnAny;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 AsnAny} structure contains a SNMP variable type and value. This structure is a member of the RFC1157VarBind structure used as a parameter in many of the SNMP APIs.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Member\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 asnType \tab Indicates the variable's type and what portion of the union should be used.
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 asnType\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 ASN_INTEGER\tab Indicates integer variable.
|
|
\par ASN_OCTETSTRING\tab Indicates octet string variable.
|
|
\par ASN_OBJECTIDENTIFIER\tab Indicates object identifier variable.
|
|
\par ASN_SEQUENCE\tab Indicates ASN sequence variable.
|
|
\par ASN_RFC1155_IPADDRESS\tab Indicates IP address variable.
|
|
\par ASN_RFC1155_COUNTER\tab Indicates counter variable.
|
|
\par ASN_RFC1155_GAUGE\tab Indicates gauge variable.
|
|
\par ASN_RFC1155_TIMETICKS\tab Indicates timeticks variable.
|
|
\par ASN_RFC1155_OPAQUE\tab Indicates opaque variable.
|
|
\par ASN_RFC1213_DISPSTRING\tab Indicates display string variable.
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 asnValue \tab Contains the variable's value. This union supports the possible SNMP values.
|
|
\par \pard\plain \s32\qj\li720\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx5040 \b\f9\fs20 Member\tab Description
|
|
\par \pard\plain \s33\qj\fi-4320\li5040\sb100\widctlpar\tx5040 \f12\fs20 number\tab Accesses integer variable.
|
|
\par string\tab Accesses octet string variable.
|
|
\par object\tab Accesses object identifier variable.
|
|
\par sequence\tab Accesses ASN sequence variable.
|
|
\par address\tab Accesses IP address variable.
|
|
\par counter\tab Accesses counter variable.
|
|
\par gauge\tab Accesses gauge variable.
|
|
\par ticks\tab Accesses timeticks variable.
|
|
\par arbitrary\tab Accesses opaque variable.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC1157VarBind, RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.1.2.\tab RFC1157VarBind
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef struct vb \{
|
|
\par AsnObjectName name;
|
|
\par AsnObjectSyntax value;
|
|
\par \} RFC1157VarBind;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 RFC1157VarBind} structure represents a SNMP variable binding as defined in RFC 1157.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Member\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 name \tab Indicates the variable's name as an object identifier.
|
|
\par value \tab Contains the variable's value.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155, RFC 1157.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.1.3.\tab RFC1157VarBindList
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef struct \{
|
|
\par RFC1157VarBind *list;
|
|
\par UINT len;
|
|
\par \} RFC1157VarBindList;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The {\b\f9 RFC1157VarBindList} structure represents a SNMP variable bindings list as defined in RFC 1157.
|
|
\par \pard\plain \s29\qj\sb100\widctlpar\brdrb\brdrs\brdrw15 \tx2880 \b\f9\fs20 Member\tab Description
|
|
\par \pard\plain \s30\qj\fi-2880\li2880\sb100\widctlpar\tx2880 \f12\fs20 list \tab A pointer that may be dereferenced as an array to access individual variable bindings.
|
|
\par len \tab Contains the number of variable bindings in the list.
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 Comments}{\b
|
|
\par }None.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC1157VarBind, RFC 1157.
|
|
\par \pard\plain \s2\sb120\keepn\widctlpar \b\f9 \page 3.2.\tab Types
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.1.\tab AsnInteger
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef long AsnInteger;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnInteger} is used to represent signed integer quantities as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.2.\tab AsnOctetString
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef struct \{
|
|
\par BYTE *stream;
|
|
\par UINT length;
|
|
\par BOOL dynamic;
|
|
\par \} AsnOctetString;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnOctetString} is used to represent octet (usually byte) quantities as defined in RFC 1155.
|
|
\par The dynamic flag indicates to data structure freeing code whether the stream is allocated from dynamic memory.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.3.\tab AsnObjectIdentifier
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef struct \{
|
|
\par UINT idLength;
|
|
\par UINT *ids;
|
|
\par \} AsnObjectIdentifier;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnObjectIdentifier} is used to represent objects as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.4.\tab AsnSequence
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnOctetString AsnSequence;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnSequence} is used to represent sequences as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.5.\tab AsnImplicitSequence
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnSequence AsnImplicitSequence;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnImplicitSequence} is used to represent implicit sequences as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.6.\tab AsnIPAddress
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnOctetString AsnIPAddress;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnIPAddress} is used to represent Internet Protocol (IP) addresses as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 \page 3.2.7.\tab AsnDisplayString
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnOctetString AsnDisplayString;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnDisplayString} is used to represent human readable octets as defined in RFC 1213.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1213.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.8.\tab AsnCounter
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnInteger AsnCounter;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnCounter} is used to represent counted quantities as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.9.\tab AsnGauge
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnInteger AsnGauge;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnGauge} is used to represent metered quantities as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.10.\tab AsnTimeticks
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnInteger AsnTimeticks;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnTimeTicks} is used to represent relative time quantities as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s3\sb120\keepn\widctlpar\tx1080 \b\f9 3.2.11.\tab AsnOpaque
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 typedef AsnOctetString AsnOpaque;
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 {\b\f9 AsnOpaque} is used to represent an encapsolation of other ASN constructs as defined in RFC 1155.
|
|
\par {\b\f9 See Also}{\f9
|
|
\par }RFC 1155.
|
|
\par \pard\plain \s1\sb120\keepn\widctlpar \b\f9 \page 4.\tab MIB Compiler
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 A basic SNMP MIB Compiler is provided with the Management APIs. This MIB c
|
|
ompiler is currently used only to resolve the conversions requested by SnmpMgrStrToOid() and SnmpMgrOidToStr(). These conversions are Object Identifier to/from Object Descriptor translations.
|
|
\par Help on how this MIB compiler is invoked is provided by typing 'MIBCC -?':
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 c:\\>mibcc -?
|
|
\par usage: mibcc [-?] [-e] [-l] [-n] [-o] -[w] [files...]
|
|
\par MibCC compiles the specified SNMP MIB files.
|
|
\par -? usage.
|
|
\par -eX stop after X Errors. (default = 10)
|
|
\par -l do not print Logo.
|
|
\par -n print each Node as it is added.
|
|
\par -ofile output file name. (default = mib.bin)
|
|
\par -wX set Warning level. (1=errors, 2=warnings)
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20
|
|
This MIB compiler accepts the subset of ASN.1 defined by the SNMP RFCs. A file containing ASN.1 source code can contain one or more MODULE definitions, although it is easier to keep one module per file and specify multiple files on the command line. Ord
|
|
er of specification is significant. For example, SMI.MIB should be specified before any other MIBs.
|
|
\par An example compile may look like:
|
|
\par \pard\plain \s24\fi-720\li720\sb60\widctlpar\tx720\tx1440\tx2160 \f3\fs20 c:\\>mibcc smi.mib mib-ii.mib
|
|
\par Microsoft (R) SNMP MIB Compiler Version 1.00
|
|
\par Copyright (c) Microsoft Corporation 1992. All rights reserved.
|
|
\par warning : EXPORTS on line 3 not supported (ignored)
|
|
\par warning : IMPORTS on line 135 not supported (ignored)
|
|
\par Parse of 'test.mib' was successful. 2756 lines were parsed.
|
|
\par mibcc: total files processed: 1.
|
|
\par mibcc: writing compiled SNMP MIB.
|
|
\par
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 The following MIB files have been included in this distribution: SMI.MIB, MIB_II.MIB, LMMIB2.MIB, WINS.MIB, DHCP.MIB, INETSRV.MIB, HTTP.MIB, GOPHERD.MIB, FTP.MIB, and TOASTER.MIB.
|
|
\par \pard\plain \s1\sb120\keepn\widctlpar \b\f9 \page 5.\tab Example Code
|
|
\par \pard\plain \s23\qj\sb100\widctlpar \f12\fs20 Example SNMP application entities are contained in the Win32 SDK to aid in understanding the workings of the various APIs. Look undermstools\\samples\\win32\\winnt\\snmp\\testdll for an example subagent and
|
|
look under mstools\\samples\\win32\\winnt\\snmp\\snmputil for an example management application.
|
|
\par It should be noted that agent developers should thoroughly understand the non-protocol issues presented in RFC 1155 and RFC 1157.
|
|
\par \pard\plain \s2\sb120\keepn\widctlpar \b\f9
|
|
\par }
|