snmpDiscover_v3()--SNMP Version 3 Discovery

 #include <qtomeapi.h>

 int snmpDiscover_v3(char  *             host_ptr,
                     unsigned long int   time_out,
                     snmp_auth_cb *      my_auth_cb);

An SNMP managing application uses the snmpDiscover_v3() function to discover authentication-related information about a remote or local SNMP version 3 (SNMPv3) agent. This function must be used prior to doing any other SNMPv3 operation such as a GET or SET. This function must also be used for each individual agent that a manager communicates with.

Parameters

host_ptr

(Input) A pointer to the character string that contains the Internet Protocol (IP) address. The internet address may be an IPv4 or IPv6 address.

An IPv4 internet address is specified in the form nnn.nnn.nnn.nnn, where nnn is a decimal number ranging from 0 through 255. An IPv4 internet address is not valid if it has a value of all binary ones or all binary zeros for the network identifier (ID) portion or the host ID portion of the address.

An IPv6 internet address is specified in the form x:x:x:x:x:x:x:x, where x is a hexadecimal number ranging from 0 through X'FFFF'. "::" may be used once in the IPv6 address to indicate one or more groups of 16 bits of zeros. The "::" may be used to compress leading, imbedded, or trailing zeros in the address.

This parameter can also be stored in host address format, that is, mycompany.com. This parameter must contain printable characters only.

time_out

(Input) The time-out value.

This parameter is the amount of time in seconds that the management application is willing to wait for the response PDU. The minimum value is 1, and the maximum is 100.

my_auth_cb

(Output) The address of a pointer to an SNMPv3 authentication control block built by the snmpDiscover_v3() function for the host specified by the host_ptr parameter.

Authorities

Service Program Authority

*USE

Return Value

The following are the possible return codes posted by the snmpDiscover_v3() function:

0	API_RC_OK snmpDiscover_v3() was successful.
-4	API_RC_OUT_OF_MEMORY There was not enough storage to complete this operation.
-18	API_RC_TIMEOUT A response to this request was not received within the allotted time-out value.
-103	API_RC_INVALID_IP_ADDRESS The IP address that was specified is not valid.
-108	API_RC_INVALID_TIMEOUT_PARM The time-out value must be greater than 0 and less than or equal to 100.
-110	API_RC_UNKNOWN_HOST The host name or IP address that is specified is not known on the network.
-114	API_RC_INVALID_HOST_POINTER The pointer value to the host address must be non-NULL.
-121	API_RC_SNMPV3_NOT_ALLOWED SNMPv3 is not allowed by the SNMP attributes.
-201	API_RC_SOCKET_ERROR The APIs have detected a socket error and cannot continue.
-202	API_RC_NOT_OK The APIs have detected an unknown error and cannot continue.
1	API_RC_VAL_LEN_LESS_THAN_RETURNED_ VAL_LEN The value being returned by the API is greater than the space allocated by the user.
241	API_RC_DOMAIN_ERROR This is equivalent to an MCH6801 error--stating object domain error.
242	API_RC_INVALID_POINTER This is equivalent to an MCH3601 error--referenced location in a space does not contain a pointer.
243	API_RC_INVALID_PTR_TYPE This is equivalent to an MCH3602 error-pointer type not valid for requested operation.

For more information, see the Simple Network Management Protocol (SNMP) Support manual.

Usage Notes

1. All character strings that are passed to the APIs must be null-terminated.
2. The data returned in the authentication control block should not be modified in any way. The authentication control block is directly tied to a specific agent, so the manager application must call the snmpDiscover_v3 API for each agent it communicates with.
3. If an agent or the manager is restarted, the data in the authentication control block is no longer valid. So, a new authentication control block is required. The snmpDiscover_v3 API must be called again in order to build a new control block for the agent.
4. A timeout on a version 3 get, get next, set operation may indicate one of the following:
   • The authentication control block is no longer valid. The snmpDiscover_v3 API needs to be called again to get a new authentication control block.
   • Authentication of the specified user failed.
   • There was an error communicating with the agent.
5. The snmpDiscover_v3 API does not reuse storage for an authentication control block. The storage used by the authentication control block must be freed using the snmpFreeAuthCB_v3 API.
6. The snmpDiscover_v3 API opens a socket that will be used by subsequent calls to other SNMPv3 manager APIs. The socket is closed by the snmpFreeAuthCB_v3 API.
7. The snmpDiscover_v3 API attempts to bind to the port specified by the snmp-mgr service table entry. If for any reason it can not bind to that port, a random ephemeral port is used.
8. These APIs are blocked, which means that on a call to the API a request is sent across a communications protocol to an SNMP agent on a local or remote system. The call returns when a response has been received from the agent or when the command times out. On the return, all returned data is placed in the appropriate locations. You need do no further action to retrieve such data.

Related Information

• The <qtomeapi.h> file (see Header Files for UNIX^®-Type Functions)
  
  
• snmpGet()--Retrieve MIB Objects
  
  
• snmpGetnext()--Retrieve Next MIB Object
  
  
• snmpSet()--Set MIB Objects
  
  
• snmpFreeAuthCB_v3()--SNMP version 3 Free Authentication Control Block
  
  
• snmpGet_v3()--Retrieve MIB Objects Using SNMP Version 3
  
  
• snmpGetbulk_v3()--Retrieve Bulk MIB Objects Using SNMP Version 3
  
  
• snmpGetnext_v3()--Retrieve Next MIB Object Using SNMP Version 3
  
  
• snmpSet_v3()--Set MIB Objects Using SNMP Version 3
  
  
• snmpSetContext_v3()--SNMP Version 3 Set Context for SNMP Messages
  

Example

For examples that pertain to the SNMP manager APIs, see Using SNMP Manager APIs--Example.