Microsoft Windows NT
SNMP Programmer's Reference

May 16, 1996

1.	Introduction	
This document describes the Simple Network Management Protocol (SNMP) application programming interfaces (APIs) for Windows NT.  
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 agent applications and receives traps generated by SNMP agent applications.  
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 compared 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 agent is implemented as a Win32 Service, and the subgents are implemented as Win32 Dynamic Link Libraries (DLLs).  
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). 
Miscellaneous utility APIs are also provided to assist with comparing, copying, and freeing allocated data structures, among other operations.  
2.	Application Program Interfaces
There are three categories of APIs provided:  Agent, Manager, and Utility.  
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.  
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.  
Agent APIs define the interface between the Windows NT extensible agent and the ISV-developed subagent DLLs.
Manager APIs define the interface between ISV-developed manager applications and the Management API DLL.  
Utility APIs are provided to simplify manipulation of the type definitions discussed above, and perform other miscellaneous operations.  
This results in the SNMP developer being able to concentrate on the task of providing or requesting management information 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.  

2.1.	Agent APIs
Agent APIs define the interface between the Windows NT extensible agent and ISV-developed subagent DLLs.  
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).  
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.  
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. 
2.1.1.	SnmpExtensionInit()
BOOL SnmpExtensionInit(
    IN  DWORD               dwTimeZeroReference,
    OUT HANDLE              *hPollForTrapEvent,
    OUT AsnObjectIdentifier *supportedView)
The SnmpExtensionInit function exported by the ISV-developed subagent DLL is called by the extensible agent during the extensible agent’s service startup to exchange configuration information.  
Parameter	Description
dwTimeZeroReference 	Specifies a time-zero reference for the subagent.  
hPollForTrapEvent 	Points to a handle for an event that will be signaled when the SnmpExtensionTrap entry point should be polled by the extensible agent.  If traps are not generated by the subagent, NULL should be returned.  
supportedView 	Points to an AsnObjectIdentifier specifying the MIB sub-tree supported by the subagent.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
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 GetCurrentTime.  This time reference is necessary to implement traps, and possibly some MIB variables.  
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 CreateEvent.  When this event is signaled, the extensible agent will call the SnmpExtensionTrap entry point and use the returned information to send a trap to each destination listed in the Registry.  
See Also 
SnmpExtensionTrap(), GetCurrentTime(), CreateEvent(), SetEvent().

2.1.2.	SnmpExtensionInitEx()
BOOL SnmpExtensionInit(
	OUT AsnObjectIdentifier *supportedView)
The SnmpExtensionInitEx function exported by the ISV-developed subagent DLL is called by the extensible agent during the extensible agent’s service startup to exchange additional configuration information.  
Parameter	Description
supportedView 	Points to an AsnObjectIdentifier specifying the MIB sub-tree supported by the subagent.  
Returns
If supportedView has been initialized with an additional MIB sub-tree, the return value is TRUE.  
If there are no more MIB sub-trees to register, the return value is FALSE.  
Comments
The extensible agent repeatedly calls the 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.
See Also 
SnmpExtensionInit().

2.1.3.	SnmpExtensionQuery()
BOOL SnmpExtensionQuery(
    IN BYTE                   requestType,
    IN OUT RFC1157VarBindList *variableBindings,
    OUT AsnInteger            *errorStatus,
    OUT AsnInteger            *errorIndex)
The 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’s registered MIB views.  
Parameter	Description
requestType 	Specifies the SNMP request type from the following list:
requestType	Description
ASN_RFC1157_GETREQUEST	Indicates SNMP Get Request.  
ASN_RFC1157_GETNEXTREQUEST	Indicates SNMP Get Next Request.  
ASN_RFC1157_SETREQUEST	Indicates SNMP Set Request.  
variableBindings 	Points to the variable bindings list.  
errorStatus 	Points to variable to receive the resulting error status from the following list 
errorStatus	Description
ASN_ERRORSTATUS_NOERROR	Indicates the noError error status.  
ASN_ERRORSTATUS_TOOBIG	Indicates the tooBig error status.  
ASN_ERRORSTATUS_NOSUCHNAME	Indicates the noSuchName error status.  
ASN_ERRORSTATUS_BADVALUE	Indicates the badValue error status.  
ASN_ERRORSTATUS_READONLY	Indicates the readOnly error status.  
ASN_ERRORSTATUS_GENERR	Indicates the genError error status.  
errorIndex 	Points to variable to receive the resulting error index.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
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.  
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 variable 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 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 agent to continue to attempt to resolve such variable bindings with other subagents.  
It is important to note that during the 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, SnmpUtilMemAlloc() and 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.

See Also 
SnmpExtensionInit(), SnmpExtensionInitEx(), RFC 1157.

2.1.4.	SnmpExtensionTrap()
BOOL SnmpExtensionTrap(
    OUT AsnObjectIdentifier *enterprise,
    OUT AsnInteger          *genericTrap,
    OUT AsnInteger          *specificTrap,
    OUT AsnTimeticks        *timeStamp,
    OUT RFC1157VarBindList  *variableBindings)
The SnmpExtensionTrap function exported by the subagent DLL is called by the extensible agent to retrieve subagent generated traps.  
Parameter	Description
enterprise 	Points to an object identifier indicating the originating enterprise generating the trap.  
genericTrap 	Points to an indication of the generic trap generated from the following list:
genericTrap	Description
SNMP_GENERICTRAP_COLDSTART	Indicates Cold Start trap.  
SNMP_GENERICTRAP_WARMSTART	Indicates Warm Start trap.  
SNMP_GENERICTRAP_LINKDOWN	Indicates Link Down trap.  
SNMP_GENERICTRAP_LINKUP	Indicates Link Up trap.  
SNMP_GENERICTRAP_AUTHFAILURE	Indicates Authentication Failure trap.  
SNMP_GENERICTRAP_EGPNEIGHLOSS	Indicates EGP Neighbor Loss trap.  
SNMP_GENERICTRAP_ENTERSPECIFIC	Indicates Enterprise Specific trap.  
specificTrap 	Points to an indication of the specific trap generated.  
timeStamp 	Points to variable to receive the time-stamp.  
variableBindings 	Points to the variable bindings list.  
Returns
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.  
Comments
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’s parameters do not represent valid trap data and to stop the extensible agent's repeated calls.  
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.
See Also 
SnmpExtensionInit().

2.2.	Manager APIs
Manager APIs define the interface between ISV-developed Manager Applications and the Management API DLL.  
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 the 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.  
The ISV-developed Manager Application links with this DLL to gain access to its services.  
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.  
2.2.1.	SnmpMgrOpen()
LPSNMP_MGR_SESSION SnmpMgrOpen(
    IN LPSTR lpAgentAddress,    // Name/address of target SNMP agent
    IN LPSTR lpAgentCommunity,  // Community for target SNMP agent
    IN INT   nTimeOut,          // Communication time-out in milliseconds
    IN INT   nRetries)          // Communication time-out/retry count
The SnmpMgrOpen function initializes communications sockets and data structures allowing communications with the specified agent.  
Parameter	Description
lpAgentAddress 	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.  
lpAgentCommunity 	Points to a null-terminated string specifying the SNMP Community Name used when communicating with the agent specified in lpAgentAddress.  
nTimeOut 	Specifies the communications time-out in milliseconds.  
nRetries 	Specifies the communications retry count.  The time-out specified in nTimeOut is doubled each time a retry attempt is transmitted.  
Returns
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.  
If the function fails, the return value is NULL.  Use the GetLastError function to obtain extended error information.  
GetLastError()	Description
SNMP_MEM_ALLOC_ERROR	Indicates error allocating memory.  
Comments
None.
See Also 
SnmpMgrClose(), SnmpMgrRequest().

2.2.2.	SnmpMgrClose()
BOOL SnmpMgrClose(
    IN LPSNMP_MGR_SESSION session) // SNMP session pointer
The SnmpMgrClose function closes communications socket and data structures associated with the specified session.
Parameter	Description
session 	Points to a LPSNMP_MGR_SESSION structure specifying the session to close.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  Use the GetLastError function to obtain extended error information.  
Comments
None.
See Also 
SnmpMgrOpen(), SnmpMgrRequest().

2.2.3.	SnmpMgrRequest()
SNMPAPI SnmpMgrRequest(
    IN     LPSNMP_MGR_SESSION session,           // SNMP session pointer
    IN     BYTE               requestType,       // Get, GetNext, or Set
    IN OUT RFC1157VarBindList *variableBindings, // Varible bindings
    OUT    AsnInteger         *errorStatus,      // Result error status
    OUT    AsnInteger         *errorIndex)       // Result error index
The SnmpMgrRequest function requests the specified operation be performed with the specified agent.  
Parameter	Description
session 	Points to a LPSNMP_MGR_SESSION structure specifying the session that will perform the request.  
requestType 	Specifies the SNMP request type from the following list:
requestType	Description
ASN_RFC1157_GETREQUEST	Indicates SNMP Get Request.  
ASN_RFC1157_GETNEXTREQUEST	Indicates SNMP Get Next Request.  
ASN_RFC1157_SETREQUEST	Indicates SNMP Set Request.  
variableBindings 	Points to the variable bindings list.  
errorStatus 	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):
errorStatus	Description
ASN_ERRORSTATUS_NOERROR	Indicates the noError error status.  
ASN_ERRORSTATUS_TOOBIG	Indicates the tooBig error status.  
ASN_ERRORSTATUS_NOSUCHNAME	Indicates the noSuchName error status.  
ASN_ERRORSTATUS_BADVALUE	Indicates the badValue error status.  
ASN_ERRORSTATUS_READONLY	Indicates the readOnly error status.  
ASN_ERRORSTATUS_GENERR	Indicates the genError error status.  
errorIndex 	Points to variable to receive the resulting error index.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is NULL.  Use the GetLastError function to obtain extended error information.  
GetLastError()	Description
SNMP_MGMTAPI_TIMEOUT	Request timed-out.  
SNMP_MGMTAPI_SELECT_FDERRORS	Unexpected error file descriptors indicated by select().  
Comments
For GET and GETNEXT requests, each variable in the variableBindings must be initialized to type ASN_NULL.  .
See Also 
SnmpMgrOpen(), SnmpMgrClose(), RFC 1157.

2.2.4.	SnmpMgrStrToOid()
BOOL SnmpMgrStrToOid(
    IN  LPSTR               string,   // OID string to be converted
    OUT AsnObjectIdentifier *oid)     // OID internal representation
The SnmpMgrStrToOid function converts a string OBJECT IDENTIFIER or OBJECT DESCRIPTOR representation to an internal AsnObjectIdentifier.
Parameter	Description
string 	Points to a NULL terminated string to be converted.  
oid 	Points to an AsnObjectIdentifier variable to receive the converted value.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
None.
See Also 
SnmpMgrOidToStr(), MibCC.

2.2.5.	SnmpMgrOidToStr()
BOOL SnmpMgrOidToStr(
    OUT AsnObjectIdentifier oid,     // OID internal rep to be converted
    IN  LPSTR               string)  // OID string representation
The SnmpMgrStrToOid function converts an internal AsnObjectIdentifier to a string OBJECT IDENTIFIER or OBJECT DESCRIPTOR representation.
Parameter	Description
oid 	Points to an AsnObjectIdentifier to be converted.  
string 	Points to a NULL terminated string to receive the converted value.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
None.
See Also 
SnmpMgrStrToOid(), MibCC.

2.2.6.	SnmpMgrTrapListen()
BOOL SnmpMgrTrapListen(
    OUT HANDLE *phTrapAvailable) // Event handle indicating trap(s) available
The SnmpMgrTrapListen function registers the desire to receive SNMP traps.  
Parameter	Description
phTrapAvailable 	Points to an event that is asserted when new traps have been received.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  Use the GetLastError function to obtain extended error information.  
GetLastError()	Description
SNMP_MGMTAPI_TRAP_DUPINIT	This function has already been called.  
SNMP_MGMTAPI_AGAIN	Error encountered, can attempt call again.  
Comments
The phTrapAvailable event is provided to allow event-driven acquisition of SNMP traps.  It can be ignored and the SnmpMgrGetTrap function can be polled at regular intervals.  
Or, a thread could be created waiting on the event using WaitForSingleObject.  When the event is asserted, this thread should clear the event using ResetEvent, and then repeatedly call the SnmpMgrGetTrap function until it returns FALSE.  
See Also 
SnmpMgrGetTrap(), WaitForSingleObject(), ResetEvent().

2.2.7.	SnmpMgrGetTrap()
BOOL SnmpMgrGetTrap(
    OUT AsnObjectIdentifier *enterprise,       // Generating enterprise
    OUT AsnInteger          *genericTrap,      // Generic trap type
    OUT AsnInteger          *specificTrap,     // Enterprise specific type
    OUT AsnTimeticks        *timeStamp,        // Time stamp
    OUT RFC1157VarBindList  *variableBindings) // Variable bindings
The SnmpMgrGetTrap function returns outstanding trap data that the caller has not yet received.  
Parameter	Description
enterprise 	Points to an object identifier indicating the originating enterprise generating the trap.  
genericTrap 	Points to an indication of the generic trap generated from the following list:
genericTrap	Description
SNMP_GENERICTRAP_COLDSTART	Indicates Cold Start trap.  
SNMP_GENERICTRAP_WARMSTART	Indicates Warm Start trap.  
SNMP_GENERICTRAP_LINKDOWN	Indicates Link Down trap.  
SNMP_GENERICTRAP_LINKUP	Indicates Link Up trap.  
SNMP_GENERICTRAP_AUTHFAILURE	Indicates Authentication Failure trap.  
SNMP_GENERICTRAP_EGPNEIGHLOSS	Indicates EGP Neighbor Loss trap.  
SNMP_GENERICTRAP_ENTERSPECIFIC	Indicates Enterprise Specific trap.  
specificTrap 	Points to an indication of the specific trap generated.  
timeStamp 	Points to variable to receive the time-stamp.  
variableBindings 	Points to the variable bindings list.  
Returns
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 GetLastError() indicating either an error or SNMP_MGMTAPI_NOTRAPS.  
GetLastError()	Description
SNMP_MGMTAPI_TRAP_ERRORS	Errors encountered, traps not accessible.  
SNMP_MGMTAPI_NOTRAPS	No traps are available.  
Comments
The phTrapAvailable event from SnmpMgrTrapListen is provided to allow event-driven acquisition of SNMP traps.  It can be ignored and this function can be polled at regular intervals.  
Or, a thread could be created waiting on the event using WaitForSingleObject.  When the event is asserted, this thread should clear the event using ResetEvent, and then repeatedly call the this function until it returns FALSE.  
See Also 
SnmpMgrTrapListen(), WaitForSingleObject(), ResetEvent().

2.3.	Utility APIs
Utility APIs are provided to simplify manipulation of the type definitions discussed above, and perform other miscellaneous operations.  
In the Windows NT 3.51 release and earilier, these APIs were provided by the SNMP static library, SNMP.LIB.  In the Windows NT 4.0 release, these APIs are provided by the SNMP utility DLL, SNMPAPI.DLL, and it’s import library, SNMPAPI.LIB.
The ISV developed Application links with this library to gain access to its services.  
There are several Utility APIs:  SnmpUtilMemAlloc(), SnmpUtilMemFree(), SnmpUtilMemReAlloc(), SnmpUtilOidCpy(), SnmpUtilOidAppend(), SnmpUtilOidNCmp(), SnmpUtilOidCmp(), SnmpUtilOidFree(), SnmpUtilVarBindListCpy(), SnmpUtilVarBindCpy(), SnmpUtilVarBindListFree(), SnmpUtilVarBindFree(), and SnmpUtilPrintAsnAny().  
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. 
2.3.1.	SnmpUtilMemAlloc()
LPVOID SnmpUtilMemAlloc(
	IN UINT Size // number of bytes to allocate
    );
The SnmpUtilMemAlloc function allocates the specified number of bytes from the heap.
Parameter	Description
Size 	Specifies the number of bytes to allocate.
Returns
If the function is successful, the return value is a pointer to the newly allocated memory object.  
If the function fails, the return value is NULL.  
Comments
Memory should be released using SnmpUtilMemFree.
See Also 
SnmpUtilMemFree(), SnmpUtilMemReAlloc().

2.3.2.	SnmpUtilMemFree()
VOID SnmpUtilMemFree(
	IN LPVOID Addr // pointer to the memory object
    );
The SnmpUtilMemFree function frees the specified memory object.
Parameter	Description
Addr 	Specifies the memory object to release.
Returns
None.  
Comments
Memory should be allocated using SnmpUtilMemAlloc.
See Also 
SnmpUtilMemAlloc(), SnmpUtilMemReAlloc().

2.3.3.	SnmpUtilMemReAlloc()
LPVOID SnmpUtilMemReAlloc(
	IN LPVOID Addr, // pointer to the memory object
	IN UINT Size    // number of bytes to allocate
    );
The SnmpUtilMemReAlloc function changes the size of the specified memory object.
Parameter	Description
Addr 	Specifies the memory object to resize.
Size 	Specifies the new size of the memory object.
Returns
If the function is successful, the return value is a pointer to the newly allocated memory object.  
If the function fails, the return value is NULL.  
Comments
Memory should be released using SnmpUtilMemFree.
See Also 
SnmpUtilMemAlloc(), SnmpUtilMemFree().

2.3.4.	SnmpUtilOidCpy()
SNMPAPI SnmpUtilOidCpy(
    OUT AsnObjectIdentifier *DestObjId, // Destination OID
    IN AsnObjectIdentifier *SrcObjId    // Source OID
    );
The SnmpUtilOidCpy function copies the SrcObjId to the DestObjId allocating any necessary memory for the destination's copy.
Parameter	Description
DestObjId 	Points to an AsnObjectIdentifier variable to receive the copy.  
SrcObjId 	Points to an AsnObjectIdentifier variable to copy.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
Any memory allocated for the destination can be freed using SnmpUtilOidFree.
See Also 
SnmpUtilOidFree().

2.3.5.	SnmpUtilOidAppend()
SNMPAPI SnmpUtilOidAppend(
    IN OUT AsnObjectIdentifier *DestObjId, // Destination OID
    IN AsnObjectIdentifier *SrcObjId       // Source OID
    );
The SnmpUtilOidAppend function appends the SrcObjId to the DestObjId reallocating any necessary memory for the destination's copy.
Parameter	Description
DestObjId 	Points to an AsnObjectIdentifier variable to receive the copy.  
SrcObjId 	Points to an AsnObjectIdentifier variable to copy.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
Any memory allocated for the destination can be freed using SnmpUtilOidFree.
See Also 
SnmpUtilOidFree().

2.3.6.	SnmpUtilOidNCmp()
int SnmpUtilOidNCmp(
    IN AsnObjectIdentifier *A, // First OID
    IN AsnObjectIdentifier *B, // Second OID
    IN UINT Len                // Max len to compare
    );
The SnmpUtilOidNCmp function compares Len sub-identifiers of A and B.
Parameter	Description
A 	Points to an AsnObjectIdentifier variable to compare.  
B 	Points to an AsnObjectIdentifier variable to compare.  
Len 	Indicates the number of sub-identifiers to compare.  
Returns
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.  
Comments
None.  
See Also 
SnmpUtilOidCmp().  

2.3.7.	SnmpUtilOidCmp()
int SnmpUtilOidCmp(
    IN AsnObjectIdentifier *A, // First OID
    IN AsnObjectIdentifier *B, // Second OID
    );
The SnmpUtilOidCmp function compares object identifiers A and B.
Parameter	Description
A 	Points to an AsnObjectIdentifier variable to compare.  
B 	Points to an AsnObjectIdentifier variable to compare.  
Returns
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.  
Comments
None.  
See Also 
SnmpUtilOidNCmp().  

2.3.8.	SnmpUtilOidFree()
void SnmpUtilOidFree(
    IN OUT AsnObjectIdentifier *Obj // OID to free
    );
The SnmpUtilOidFree function frees any allocated data associated with Obj.
Parameter	Description
Obj 	Points to an AsnObjectIdentifier variable whose allocated data should be freed.  
Returns
None.  
Comments
None.  
See Also 
None.  

2.3.9.	SnmpUtilVarBindListCpy()
SNMPAPI SnmpUtilVarBindListCpy(
    RFC1157VarBindList *dst, // Destination var bind list
    RFC1157VarBindList *src  // Source var bind list
    );
The SnmpUtilOidCpy function copies the RFC1157VarBindList allocating any necessary memory for the destination's copy.
Parameter	Description
dst 	Points to an RFC1157VarBindList to receive the copy.  
src 	Points to an RFC1157VarBindList to copy.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
Any memory allocated for the destination can be freed using SnmpUtilVarBindListFree.
See Also 
SnmpUtilVarBindListFree().

2.3.10.	SnmpUtilVarBindCpy()
SNMPAPI SnmpUtilVarBindCpy(
    RFC1157VarBind *dst, // Destination var bind
    RFC1157VarBind *src  // Source var bind
    );
The SnmpUtilOidCpy function copies the RFC1157VarBind allocating any necessary memory for the destination's copy.
Parameter	Description
dst 	Points to an RFC1157VarBind to receive the copy.  
src 	Points to an RFC1157VarBind to copy.  
Returns
If the function is successful, the return value is TRUE.  
If the function fails, the return value is FALSE.  
Comments
Any memory allocated for the destination can be freed using SnmpUtilVarBindFree.
See Also 
SnmpUtilVarBindFree().

2.3.11.	SnmpUtilVarBindListFree()
void SnmpUtilVarBindListFree(
    RFC1157VarBindList *VarBindList // Variable bindings list to free
    );
The SnmpUtilVarBindListFree function frees any allocated data associated with VarBindList.
Parameter	Description
VarBindList 	Points to an RFC1157VarBindList whose allocated data should be freed.  
Returns
None.  
Comments
None.  
See Also 
None.  

2.3.12.	SnmpUtilVarBindFree()
void SnmpUtilVarBindFree(
    RFC1157VarBind *VarBind // Variable binding to free
    );
The SnmpUtilVarBindFree function frees any allocated data associated with VarBind.
Parameter	Description
VarBindList 	Points to an RFC1157VarBind whose allocated data should be freed.  
Returns
None.  
Comments
None.  
See Also 
None.  

2.3.13.	SnmpUtilPrintAsnAny()
void SnmpUtilPrintAsnAny(
    IN AsnAny *Any
    );
The SnmpUtilPrintAsnAny function prints the value of Any to stdout.
Parameter	Description
Any	Points to an AsnAny structure whose value is to be printed.  
Returns
None.  
Comments
This function is provided for debugging and development purposes.  It does not generally print the data in forms a Manager Applications would normally need.  
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.  
See Also 
AsnAny.  

3.	Structures and Types
3.1.	Structures
3.1.1.	AsnAny
typedef struct {
    BYTE asnType;
    union {
        // RFC 1155 SimpleSyntax (subset of ISO ASN.1)
        AsnInteger           number;
        AsnOctetString       string;
        AsnObjectIdentifier  object;

        // ISO ASN.1
        AsnSequence          sequence;

        // RFC 1155 ApplicationSyntax
        AsnIPAddress         address;
        AsnCounter           counter;
        AsnGauge             gauge;
        AsnTimeticks         ticks;
        AsnOpaque            arbitrary;
    } asnValue;
} AsnAny;
The 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.  
Member	Description
asnType 	Indicates the variable's type and what portion of the union should be used.  
asnType	Description
ASN_INTEGER	Indicates integer variable.  
ASN_OCTETSTRING	Indicates octet string variable.  
ASN_OBJECTIDENTIFIER	Indicates object identifier variable.  
ASN_SEQUENCE	Indicates ASN sequence variable.  
ASN_RFC1155_IPADDRESS	Indicates IP address variable.  
ASN_RFC1155_COUNTER	Indicates counter variable.  
ASN_RFC1155_GAUGE	Indicates gauge variable.  
ASN_RFC1155_TIMETICKS	Indicates timeticks variable.  
ASN_RFC1155_OPAQUE	Indicates opaque variable.  
ASN_RFC1213_DISPSTRING	Indicates display string variable.  
asnValue 	Contains the variable's value.  This union supports the possible SNMP values.  
Member	Description
number	Accesses integer variable.  
string	Accesses octet string variable.  
object	Accesses object identifier variable.  
sequence	Accesses ASN sequence variable.  
address	Accesses IP address variable.  
counter	Accesses counter variable.  
gauge	Accesses gauge variable.  
ticks	Accesses timeticks variable.  
arbitrary	Accesses opaque variable.  
Comments
None.
See Also 
RFC1157VarBind, RFC 1155.
3.1.2.	RFC1157VarBind
typedef struct vb {
    AsnObjectName   name;
    AsnObjectSyntax value;
} RFC1157VarBind;
The RFC1157VarBind structure represents a SNMP variable binding as defined in RFC 1157.  
Member	Description
name 	Indicates the variable's name as an object identifier.  
value 	Contains the variable's value.  
Comments
None.
See Also 
RFC 1155, RFC 1157.
3.1.3.	RFC1157VarBindList
typedef struct {
    RFC1157VarBind *list;
    UINT           len;
} RFC1157VarBindList;
The RFC1157VarBindList structure represents a SNMP variable bindings list as defined in RFC 1157.  
Member	Description
list 	A pointer that may be dereferenced as an array to access individual variable bindings.  
len 	Contains the number of variable bindings in the list.  
Comments
None.
See Also 
RFC1157VarBind, RFC 1157.

3.2.	Types
3.2.1.	AsnInteger
typedef long           AsnInteger;
AsnInteger is used to represent signed integer quantities as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.2.	AsnOctetString
typedef struct {
    BYTE *stream;
    UINT  length;
    BOOL dynamic;
}                      AsnOctetString;
AsnOctetString is used to represent octet (usually byte) quantities as defined in RFC 1155.  
The dynamic flag indicates to data structure freeing code whether the stream is allocated from dynamic memory.  
See Also 
RFC 1155.
3.2.3.	AsnObjectIdentifier
typedef struct {
    UINT idLength;
    UINT *ids;
}                      AsnObjectIdentifier;
AsnObjectIdentifier is used to represent objects as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.4.	AsnSequence
typedef AsnOctetString AsnSequence;
AsnSequence is used to represent sequences as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.5.	AsnImplicitSequence
typedef AsnSequence    AsnImplicitSequence;
AsnImplicitSequence is used to represent implicit sequences as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.6.	AsnIPAddress
typedef AsnOctetString AsnIPAddress;
AsnIPAddress is used to represent Internet Protocol (IP) addresses as defined in RFC 1155.  
See Also 
RFC 1155.

3.2.7.	AsnDisplayString
typedef AsnOctetString AsnDisplayString;
AsnDisplayString is used to represent human readable octets as defined in RFC 1213.  
See Also 
RFC 1213.
3.2.8.	AsnCounter
typedef AsnInteger     AsnCounter;
AsnCounter is used to represent counted quantities as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.9.	AsnGauge
typedef AsnInteger     AsnGauge;
AsnGauge is used to represent metered quantities as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.10.	AsnTimeticks
typedef AsnInteger     AsnTimeticks;
AsnTimeTicks is used to represent relative time quantities as defined in RFC 1155.  
See Also 
RFC 1155.
3.2.11.	AsnOpaque
typedef AsnOctetString AsnOpaque;
AsnOpaque is used to represent an encapsolation of other ASN constructs as defined in RFC 1155.  
See Also 
RFC 1155.

4.	MIB Compiler
A basic SNMP MIB Compiler is provided with the Management APIs.  This MIB compiler is currently used only to resolve the conversions requested by SnmpMgrStrToOid() and SnmpMgrOidToStr().  These conversions are Object Identifier to/from Object Descriptor translations.  
Help on how this MIB compiler is invoked is provided by typing 'MIBCC -?':  
c:\>mibcc -?
usage: mibcc [-?] [-e] [-l] [-n] [-o] -[w] [files...]              
   MibCC compiles the specified SNMP MIB files.                         
      -?      usage.                                                    
      -eX     stop after X Errors. (default = 10)                       
      -l      do not print Logo.                                        
      -n      print each Node as it is added.                           
      -ofile  output file name.  (default = mib.bin)                    
      -wX     set Warning level.  (1=errors, 2=warnings)                
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.  Order of specification is significant.  For example, SMI.MIB should be specified before any other MIBs.
An example compile may look like:
c:\>mibcc smi.mib mib-ii.mib                   
Microsoft (R) SNMP MIB Compiler Version 1.00                            
Copyright (c) Microsoft Corporation 1992.  All rights reserved.         
warning : EXPORTS on line 3 not supported (ignored)                     
warning : IMPORTS on line 135 not supported (ignored)                   
Parse of 'test.mib' was successful.  2756 lines were parsed.            
mibcc: total files processed:  1.                                       
mibcc: writing compiled SNMP MIB.                                       
                                                                        
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. 

5.	Example Code
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.
It should be noted that agent developers should thoroughly understand the non-protocol issues presented in RFC 1155 and RFC 1157.