Compaq TCP/IP Services for OpenVMS
SNMP Programming and Reference


Previous Contents Index


o_oid

Loads an OID value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.

Format

int o_oid ( VARBIND *vb,
OBJECT *obj,
OID *oid );


Arguments

vb

A pointer to the VARBIND structure that is supposed to receive the data.

If the original value in the VARBIND structure is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure, fill the structure with zeros before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

oid

The value to be inserted into the VARBIND structure as data. For more information about OID length and values, see Chapter 3.

The real type as defined in the object structure must be ESNMP_TYPE_OBJECT_IDENTIFIER.


Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_genErr An error occurred.

Example


 
#include <esnmp.h> 
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition 
VARBIND     *vb       = method->varbind; 
OBJECT      *object   = method->object; 
ipNetToMediaEntry_type *data; 
: 
: assume buffer and structure member assignments occur here 
: 
switch(arg) { 
 case I_atObjectID: 
  return o_oid(vb, object, &data->ipNetToMediaObjectID); 
 


o_string

Loads a string value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.

Format

int o_string ( VARBIND *vb,
OBJECT *obj,
unsigned character *ptr,
int len );


Arguments

vb

A pointer to the VARBIND structure that is supposed to receive the data.

If the original value in the VARBIND structure is not null, this routine attempts to free it. So if you dynamically allocate memory or issue the malloc command to allocate your own VARBIND structure, fill the structure with zeros before using it.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

ptr

The pointer to the buffer containing data to be inserted into the VARBIND structure as data.

len

The length of the data in buffer pointed to by ptr.

The real type as defined in the object structure must be one of the following; otherwise, an error is returned.
ESNMP_TYPE_OCTET_STRING Octet string (ASN.1)
ESNMP_TYPE_IpAddress Implicit octet string (4) (in octet form, network byte order)
ESNMP_TYPE_DisplayString DisplayString (textual convention)
ESNMP_TYPE_NsapAddress Implicit octet string
ESNMP_TYPE_Opaque Implicit octet string
ESNMP_TYPE_OBJECT_IDENTIFIER Object identifier (ASN.1) (in dot notation, for example: 1.3.4.6.3)


Return Values

ESNMP_MTHD_noError The routine completed successfully.
ESNMP_MTHD_genErr An error occurred.

Example


 
#include <esnmp.h> 
#include "ip_tbl.h"  <-- for ipNetToMediaEntry_type definition 
VARBIND     *vb       = method->varbind; 
OBJECT      *object   = method->object; 
ipNetToMediaEntry_type *data; 
: 
: assume buffer and structure member assignments occur here 
: 
switch(arg) { 
 case I_atPhysAddress: 
   return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr, 
                               data->ipNetToMediaPhysAddress.len); 
 


o_counter64

Loads a counter64 value into the VARBIND structure.

Format

int o_counter64 ( VARBIND *vb,
OBJECT *obj,
uint64 value ); (for Alpha)
uint64_vax value

; (for VAX))


Arguments

vb

A pointer to the VARBIND structure that is supposed to receive the data.

obj

A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

value

The 8-byte value to be inserted into the VARBIND structure, passed as an array of two integers.

The real type as defined in the object structure must be ESNMP_TYPE_Counter64. Otherwise, an error is returned.


Example

See the example for the o_integer routine.

Return Values

ESNMP_MTHD_noError No error was generated.
ESNMP_MTHD_genErr An error was generated.

str2oid

Converts a null-terminated string OID in dot notation to an OID structure. The str2oid routine does not allocate an OID structure.

Format

oid *str2oid ( oid *oid,
char *s );


Arguments

oid

The value to be inserted as data into the VARBIND structure. For more information about OID length and values, see Chapter 3.

s

A null string or empty string returns an OID structure that has one element of zero.

Description

The routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in the call. The caller must explicitly free this buffer. The OID can have a maximum of 128 elements.

Return Values

null An error occurred. Otherwise, the pointer to the OID structure (its first argument) is returned.

Example


 
include <esnmp.h> 
OID abc; 
if (stroid (&abc, "1.2.5.4.3.6") == NULL 
   DPRINTF((WARNING, "It did not work...\n"); 
 


sprintoid

Converts an OID into a null-terminated string.

Format

char *sprintoid ( char *buffer,
oid *oid );


Description

An OID can have up to 128 elements. A full-sized OID can require a large buffer.

Return Values

The return value points to its first argument.

Example


 
#include <esnmp.h> 
#define SOMETHING_BIG 1024 
OID abc; 
char buffer[SOMETHING_BIG]; 
: 
: assume abc gets initialized with some value 
: 
printf("dots=%s\n", sprintoid(buffer, &abc)); 
 


instance2oid

Copies the object's base OID and appends a copy of the instance array to make a complete OID for a value. This routine does not allocate an OID structure. It only allocates the array containing the elements.

Format

oid instance2oid ( oid *new,
object *obj,
unsigned int *instance,
int *len );


Arguments

new

A pointer to the OID that is to receive the new OID value.

obj

A pointer to the object table entry for the MIB variable being obtained. The first part of the new OID is the OID from this MIB object table entry.

instance

A pointer to an array of instance values. These values are appended to the base OID obtained from the MIB object table entry to construct the new OID.

len

The number of elements in the instance array.

Description

The instance array may be created by oid2instance or constructed from key values as a result of a GetNext command (see Chapter 1).

This routine dynamically allocates the buffer and inserts its pointer into the OID structure passed in the call. The caller must explicitly free the buffer.

You should point to the OID structure receiving the new values and then call the instance2oid routine. Previous values in the OID structure are freed (that is, free_oid is called first), and then the new values are dynamically allocated and inserted. Be sure the initial value of the new OID is all zeros. If you do not want the initial value freed, make sure the new OID structure is all zeros.


Return Values

null An error occurred. Otherwise, the pointer to the OID structure ( new) is returned.


Example


 
#include <esnmp.h> 
VARBIND *vb;      <-- filled in 
OBJECT  *object;  <-- filled in 
unsigned int instance[6]; 
 
-- Construct the outgoing OID in a GETNEXT          -- 
-- Instance is N.1.A.A.A.A where A's are IP address -- 
instance[0] = data->ipNetToMediaIfIndex; 
instance[1] = 1; 
for (i = 0; i < 4; i++) { 
instance[i+2]=((unsigned char *)(&data->ipNetToMediaNetAddress))[i]; 
} 
instance2oid(&vb->name, object, instance, 6); 
 


oid2instance

Extracts the instance values from an OID structure and copies them to the specified array of integers. The routine then returns the number of elements in the array.

Format

int oid2instance ( oid *oid,
object *obj,
unsigned int *instance,
int *max_len );


Arguments

oid

A pointer to an incoming OID containing an instance or part of an instance.

obj

A pointer to the object table entry for the MIB variable.

instance

A pointer to an array of unsigned integers where the index is placed.

max_len

The number of elements in the instance array.

Description

The instance values are the elements of an OID beyond those that identify the MIB variable. These elements identify a specific instance of a MIB value.

If there are more elements in the OID structure than specified by the max_len parameter, the function copies the number of elements specified by max_len only and returns the total number of elements that would have been copied had there been space.


Return Values

Less than zero An error occurred. This is not returned if the object was obtained by looking at this OID.
Zero No instance elements.
Greater than zero The returned value indicates the number of elements in the index. This could be larger than the max_len parameter.

Example


 
#include <esnmp.h> 
OID         *incoming = &method->varbind->name; 
OBJECT      *object   = method->object; 
int         instLength; 
unsigned int instance[6]; 
 
-- in a GET operation -- 
-- Expected Instance is N.1.A.A.A.A where A's are IP address -- 
instLength = oid2instance(incoming, object, instance, 6); 
if (instLength != 6) 
    return ESNMP_MTHD_noSuchInstance; 
 

The N will be in instance[0] and the IP address will be in instance[2] , instance[3] , instance[4] , and instance[5] .


inst2ip

Returns an IP address derived from an OID instance.

Format

int inst2ip ( unsigned int *instance,
int *length,
unsigned int *ipaddr,
int *exact,
int *carry );


Arguments

instance

A pointer to an array of unsigned int containing the instance numbers returned by the oid2instance routine to be converted to an IP address.

The range for elements is between zero and 255. Using the EXACT mode, the routine returns 1 if an element is out of range. Using the NEXT mode, a value greater than 255 causes that element to overflow. In this case, the value is set to 0 and the next most significant element is incremented; therefore, it returns a lexically equivalent value of the next possible ipaddr.

length

The number of elements in the instance array. Instances beyond the fourth are ignored. If the length is less than four, the missing values are assumed to be zero. A negative length results in an ipaddr value of zero. For an exact match (such as Get ), there must be exactly four elements.

ipAddr

A pointer indicating where to return the IP address value. This routine is in network byte order (the most significant element is first).

exact

Can either be TRUE or FALSE .

TRUE means do an EXACT match. If any element is greater than 255 or if there are not exactly four elements, a value of 1 is returned. The carry argument is ignored.

FALSE means do a NEXT match. That is, the lexically next IP address is returned, if the carry value is set and the length is at least four. If there are fewer than four elements, this function assumes the missing values are zero. If any one element contains a value greater than 255, the value is zeroed and the next most significant element is incremented. Returns a 1 (one) only when there is a carry from the most significant (the first) value.

carry

Adds to the IP address on a NEXT match. If you are trying to determine the next possible IP address, pass in a one. Otherwise, pass in a zero. A length of less than 4 cancels the carry.

Description

Use the EXACT mode for evaluating an instance for Get and Set operations. For GetNext and GetBulk operations, use the NEXT mode. When using NEXT mode, this routine assumes that the search for data will be performed using greater than or equal to matches.

Return Values

Carry value is 0 The routine completed successfully.
Carry value is 1 For EXACT match, an error occurred. For NEXT match, there was a carry. (If there was a carry, the returned ipaddr is 0.)

Examples

  1. The following example converts an instance to an IP address for a Get operation, which is an EXACT match.


     
    #include <esnmp.h> 
    OID         *incoming = &method->varbind->name; 
    OBJECT      *object   = method->object; 
    int instLength; 
    unsigned int instance[6]; 
    unsigned int ip_addr; 
    int          iface; 
     
    -- The instance is N.1.A.A.A.A where the A's are the IP address-- 
    instLength = oid2instance(incoming, object, instance, 6); 
    if (instLength == 6 && !inst2ip(&instance[2], 4, &ip_addr, TRUE,0)) { 
        iface = (int) instance[0]; 
    } 
    else 
       return ESNMP_MTHD_noSuchInstance; 
     
    

  2. The following example shows a GetNext operation in which there is only one key or in which the ipaddr value is the least significant part of the key. This is a NEXT match; therefore, a value of 1 is passed back for the carry value.


     
    #include <esnmp.h> 
    OID         *incoming = &method->varbind->name; 
    OBJECT      *object   = method->object; 
    int instLength; 
    unsigned int instance[6]; 
    unsigned int ip_addr; 
    int          iface; 
     
    -- The instance is N.1.A.A.A.A where the A's are the IP address-- 
    instLength = oid2instance(incoming, object, instance, 6); 
    iface = (instLength < 1) ? 0 :(int) instance[0]; 
     
    iface += inst2ip(&instance[2], instLength - 2, &ip_addr, FALSE, 1); 
     
    

  3. In the following example, the search key consists of multiple parts. If you are doing a GetNext operation, you must find the next possible value for the search key, so that you can perform a cascaded greater-than or equal-to search.
    The search key consists of a number and two ipaddr values. These are represented in the instance part of the OID as n.A.A.A.A.B.B.B.B, where:
    • n is a single value integer.
    • The A.A.A.A portion makes up one IP address.
    • The B.B.B.B portion makes up a second IP address.

    If all elements are given, the total length of the search key is 9. In this case, you perform the operation as follows:
    • Convert the least significant part of the key (that is, the B.B.B.B portion), by calling the inst2ip routine, passing it a 1 for the carry and (length - 5) for the length.
    • If the conversion of the B.B.B.B portion generates a carry (that is, returns 1), you pass it to the next most significant part of the key.
    • Convert the A.A.A.A portion by calling the inst2ip routine, passing it (length - 1) for the length and the carry returned from the conversion of the B.B.B.B portion.
    • The most significant element n is a number; therefore, add the carry from the A.A.A.A conversion to the number. If the result overflows, then the search key is not valid.


    #include <esnmp.h> 
    OID         *incoming = &method->varbind->name; 
    OBJECT      *object   = method->object; 
    int instLength; 
    unsigned int instance[9]; 
    unsigned int ip_addrA; 
    unsigned int ip_addrB; 
    int          iface; 
    int          carry; 
     
    -- The instance is N.A.A.A.A.B.B.B.B -- 
    instLength = oid2instance(incoming, object, instance, 9); 
    iface = (instLength < 1) ? 0 :(int) instance[0]; 
    carry = inst2ip(&instance[1], instLength - 1, &ip_addrB, FALSE, 1); 
    carry = inst2ip(&instance[5], instLength - 5, &ip_addrA, FALSE, carry); 
    iface += carry; 
    if (iface > carry) { 
     
    -- a carry caused an overflow in the most significant element 
    return ESNMP_MTHD_noSuchInstance; 
    } 
    


cmp_oid

Compares two OID structures.

Format

int cmp_oid ( oid *q,
oid *p );


Description

This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element. If all other elements are equal, the OID with the least number of elements is considered less.

Return Values

-1 The OID q is less than OID p .
0 The OID q is in OID p .
1 The OID q is greater than OID p .

cmp_oid_prefix

Compares an OID against a prefix.

Format

int cmp_oid_prefix ( oid *q,
oid *prefix );


Description

A prefix could be the OID on an object in the object table. The elements beyond the prefix are the instance information.

This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element. If all elements of the prefix OID match exactly with corresponding elements of the OID q structure, it is considered an even match if the OID q structure contains additional elements. The OID q structure is considered greater than the prefix if the first nonmatching element is larger. It is considered smaller if the first nonmatching element is less.


Return Values

-1 The OID is less than the prefix.
0 The OID is in prefix.
1 The OID is greater than the prefix.

Example


 
#include <esnmp.h> 
OID *q; 
OBJECT *object; 
if (cmp_oid_prefix(q, &object->oid) == 0) 
   printf("matches prefix\n"); 
 


Previous Next Contents Index