SnmpSetPort

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.

SNMPAPI_STATUS SnmpSetPort(
  HSNMP_ENTITY hEntity,  // handle to the destination entity 
  UINT nPort             // new port assignment 
);

Parameters

hEntity

[in] 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.

nPort

[in] 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 Values

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.

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 steps outlined in the following code sample.

hAgent = SnmpStrToEntity (hSession, <addrString>);
lStatus = SnmpSetPort (hAgent, <nPort>);
lStatus = SnmpListen (hAgent, SNMPAPI_ON);

where <addrString> contains the string representation of an IP address or an IPX address, and <nPort> contains the new port assignment for the agent application.

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

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Unsupported.
  Header: Declared in Winsnmp.h.
  Library: Use Wsnmp32.lib.

See Also

WinSNMP API Overview, WinSNMP Functions, SnmpListen, SnmpStrToEntity, SnmpSetPort, SnmpGetTranslateMode