[This is preliminary documentation and subject to change.]
The SnmpStartup function notifies the Microsoft WinSNMP implementation that the WinSNMP manager application requires the implementation's services. The WinSNMP SnmpStartup function enables the implementation to initialize and to return to the application the version of the Windows SNMP Manager Application Programming Interface (WinSNMP Manager API), the level of SNMP communications that the implementation supports, and the implementation's default translation and retransmission modes.
Note A WinSNMP manager application must call the SnmpStartup function successfully before it calls any other WinSNMP function.
SNMPAPI_STATUS SnmpStartup(
smiLPUINT32 nMajorVersion, // major version number of the
// WinSNMP API
smiLPUINT32 nMinorVersion, // minor version number of the
// WinSNMP API
smiLPUINT32 nLevel, // level of SNMP the implementation
// supports
smiLPUINT32 nTranslateMode, // default entity/context translation
// mode
smiLPUINT32 nRetransmitMode // default retransmission mode
);
Value | Meaning |
---|---|
SNMPAPI_NO_SUPPORT | Level 0: Support for message encoding and decoding only. |
SNMPAPI_V1_SUPPORT | Level 1: Support for Level 0 communications, as well as interaction with SNMP agent entities operating under the SNMP version 1 framework (SNMPv1). |
SNMPAPI_V2_SUPPORT | Level 2: Support for Level 1 communications, as well as interaction with SNMP agent entities operating under the SNMP version 2C framework (SNMPv2C). |
Value | Meaning |
---|---|
SNMPAPI_TRANSLATED | The implementation uses its database to translate user-friendly names for SNMP entities and managed objects. The implementation translates them into their SNMPv1 or SNMPv2C components. |
SNMPAPI_UNTRANSLATED_V1 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. |
SNMPAPI_UNTRANSLATED_V2 | The implementation interprets SNMP entity parameters as SNMP transport addresses, and context parameters as SNMP community strings. |
For additional information, see Setting the Entity and Context Translation Mode.
Value | Meaning |
---|---|
SNMPAPI_OFF | The implementation is not executing the retransmission policy of the WinSNMP manager application. |
SNMPAPI_ON | The implementation is executing the retransmission policy of the WinSNMP manager application. |
For additional information, see About Retransmission.
If the function succeeds, the return value is SNMPAPI_SUCCESS, and the parameters contain appropriate values, as indicated in the preceding parameter descriptions.
If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError. The SnmpGetLastError function can return one of the following errors. For additional information, see the Remarks section that follows.
Error Code | Description |
---|---|
SNMPAPI_NOT_INITIALIZED | The SnmpStartup function did not complete successfully. |
SNMPAPI_ALLOC_ERROR | An error occurred during memory allocation. |
SNMPAPI_OTHER_ERROR | An unknown or undefined error occurred. |
A WinSNMP manager application must call the SnmpStartup function successfully at least once, before it calls any other WinSNMP function. If a WinSNMP manager application does call another WinSNMP function, before it successfully calls SnmpStartup, the implementation returns the error SNMPAPI_NOT_INITIALIZED.
The WinSNMP manager application can call SnmpGetLastError for error information, or retry SnmpStartup if a call to the SnmpStartup function fails. When SnmpStartup returns SNMPAPI_FAILURE, and a subsequent call to SnmpGetLastError returns SNMP_ALLOC_ERROR, the WinSNMP manager application can elect to wait. It can retry the call to SnmpStartup when the implementation has adequate free resources.
A WinSNMP manager application can call SnmpStartup multiple times. For example, it may need to retry the function call for the reasons discussed preceding. A WinSNMP manager application must also call SnmpCleanup at least once, as the last WinSNMP function call before it terminates. Multiple SnmpStartup calls do not require multiple SnmpCleanup calls.
For additional information, see Levels of SNMP Support and About SNMP Versions.
Windows NT: Requires version 5.0 or later. Available as a redistributable for Windows NT 4.0.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winsnmp.h.
Import Library: Use wsnmp32.lib.
WinSNMP Manager API Overview, WinSNMP Functions, SnmpStrToEntity, SnmpStrToContext, SnmpCleanup