SnmpSetPort function (winsnmp.h)
[SNMP is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Instead, use Windows Remote Management, which is the Microsoft implementation of WS-Man.]
A WinSNMP application calls the SnmpSetPort function to change the port assigned to a destination entity. The SnmpSetPort function is an element of the WinSNMP API, version 2.0.
Syntax
SNMPAPI_STATUS SNMPAPI_CALL SnmpSetPort(
[in] HSNMP_ENTITY hEntity,
[in] UINT nPort
);
Parameters
[in] hEntity
Handle to a WinSNMP destination entity. This parameter can specify the handle to an entity acting in the role of an SNMP agent application as a result of a call to the SnmpListen function. For more information, see the following Remarks section.
[in] nPort
Specifies an unsigned integer that identifies the new port assignment for the destination entity. If you specify a local address that is busy, or if you specify a remote address that is unavailable, a call to the SnmpSetPort function fails.
Return value
If the function succeeds, the return value is SNMPAPI_SUCCESS.
If the function fails, the return value is SNMPAPI_FAILURE. To get extended error information, call SnmpGetLastError specifying a NULL value in its session parameter. The SnmpGetLastError function can return one of the following errors.
| Return code | Description |
|---|---|
|
The SnmpStartup function did not complete successfully. |
|
The entity specified by the hEntity parameter is already functioning in an agent role as the result of a call to the SnmpListen function. For more information, see the following Remarks section. |
|
The hEntity parameter is invalid. This parameter must be a handle returned by a previous call to the SnmpStrToEntity function. |
|
An unknown or undefined error occurred. |
Remarks
The Microsoft WinSNMP implementation assigns a port to each management entity as a result of a WinSNMP application's call to the SnmpStrToEntity function. If the SNMPAPI_UNTRANSLATED mode is in effect when the implementation creates an entity, the implementation typically assigns the standard SNMP request port for the respective protocol family to the entity; for example, UDP 161 or IPX 36879. If the SNMPAPI_TRANSLATED mode is in effect, the implementation assigns the port specified for the entity in the WinSNMP database. To retrieve the current entity and context translation mode in effect for the implementation, an application can call the SnmpGetTranslateMode function. For more information, see Setting the Entity and Context Translation Mode and The WinSNMP Database.
A call to the SnmpSetPort function fails if the entity specified by the hEntity parameter is currently functioning in an agent role. This is because the entity has already been assigned to a port other than the one specified by the nPort parameter. To ensure assignment of an agent application to a specific port, a WinSNMP application can perform the following steps.
-
Call SnmpStrToEntity as follows:
hAgent = SnmpStrToEntity (hSession, <addrString>); -
Call SnmpSetPort as follows:
SnmpSetPort (hAgent, <nPort>); -
Call SnmpListen as follows:
SnmpListen (hAgent, SNMPAPI_ON);
Note that an IPX address contains a network number that consists of eight hexadecimal digits (zero-filled if necessary); a separator (either ":", "." or " – "); and a node number that consists of 12 hexadecimal digits (zero-filled if necessary)—for example, 00000001:00081A0D01C2. For more information, see Support for IPX Address Strings in WinSNMP.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | winsnmp.h |
| Library | Wsnmp32.lib |
| DLL | Wsnmp32.dll |