|
HP OpenVMS Systems Documentation |
|
HP TCP/IP Services for OpenVMS
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Previous | Contents | Index |
Loads an OID value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.
int o_oid ( VARBIND *vb,
OBJECT *obj,
OID *oid );
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.
ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_genErr An error occurred.
#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);
Loads a string value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure.
int o_string ( VARBIND *vb,
OBJECT *obj,
unsigned character *ptr,
int len );
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)
ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_genErr An error occurred.
#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);
Loads a counter64 value into the VARBIND structure.
int o_counter64 ( VARBIND *vb,
OBJECT *obj,
uint64 value ); (for Alpha)
uint64_vax value; (for VAX))
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.
See the example for the o_integer routine.
ESNMP_MTHD_noError No error was generated. ESNMP_MTHD_genErr An error was generated.
Converts a null-terminated string OID in dot notation to an OID structure. The str2oid routine does not allocate an OID structure.
oid *str2oid ( oid *oid,
char *s );
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.
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.
null An error occurred. Otherwise, the pointer to the OID structure (its first argument) is returned.
include <esnmp.h> OID abc; if (stroid (&abc, "1.2.5.4.3.6") == NULL DPRINTF((WARNING, "It did not work...\n");
Converts an OID into a null-terminated string.
char *sprintoid ( char *buffer,
oid *oid );
An OID can have up to 128 elements. A full-sized OID can require a large buffer.
The return value points to its first argument.
#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));
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.
oid instance2oid ( oid *new,
object *obj,
unsigned int *instance,
int *len );
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.
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.
null An error occurred. Otherwise, the pointer to the OID structure ( new) is returned.
#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);
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.
int oid2instance ( oid *oid,
object *obj,
unsigned int *instance,
int *max_len );
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.
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.
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.
#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] .
Returns an IP address derived from an OID instance.
int inst2ip ( unsigned int *instance,
int *length,
unsigned int *ipaddr,
int *exact,
int *carry );
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.
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.
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.)
- 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;- 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);- 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; }
Compares two OID structures.
int cmp_oid ( oid *q,
oid *p );
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.
-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 .
Compares an OID against a prefix.
int cmp_oid_prefix ( oid *q,
oid *prefix );
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.
-1 The OID is less than the prefix. 0 The OID is in prefix. 1 The OID is greater than the prefix.
#include <esnmp.h> OID *q; OBJECT *object; if (cmp_oid_prefix(q, &object->oid) == 0) printf("matches prefix\n");
| Previous | Next | Contents | Index |