int IDA_GetVars(idaServID_t *servID, ubyte getType
idaVarRecord_t *varRecs,
ulong *errorIndex, ulong *errorStatus);
Parameters
servID
[in] Pointer to SERVER_IDENTIFIERstructure returned from IDA_OpenSession.
getType
[in] IDA_GET, IDA_GETBULK, IDA_GET_BULK_RE, IDA_GET_BULK_TE. A zero for this parm defaults to IDA_GET_BULK_TE.
varRecs
[in/out] Pointer to the user's array of populated VARIABLE_RECORDstructures. IDA_GetVars will use the data in this structure to build the actual GET/GET_BULK request to be sent to the server. The structure is also used to place results from the get operation.
errorIndex
[out] If an error occurs this parm will be populated with the index of the entry in the BulkRec structure that generated an error code.
errorStatus
[out] The error code will be placed here. You should be able to find this error code in the IDAApis.h file to help determine the problem.
Return Value
0 indicates a successful IDA_GetVars().
Non-zero return codes are documented in the IDAApis.h file.
Remarks
This method is called to obtain data from the InSight server agent. IDA_GetVars() may be used to return data of multiple mibVars and/or multiple iterations of table variables.
Application users may utilize an array of idaVarRecord_t structures to specify each variable to Get (retrieve). For each variable, user must specify where each variable's data should be placed (datap) and the length of the users datap buffer (dataLen). Also may specify Instance data and varType of each variable.
Users array of IdaVarRecords may contain a maximum of 48 user Variable IDs (entries).
For each varId, the user must specify a pointer to a result/data field, the len of the data field, and the length of each iteration of the data field. The internal API will calculate the maximum number of instances returned by dividing length of result field (dataLen) by length of each result field (dataItemLen). The API will parse the response from the controller agent and place each instance (iteration) of the varId into the users data field at the appropriate offset. The appropriate offset is determined by iteration times dataItemLen. This is especially useful for repeating (table) mibVars where GetVars() may be used to retrieve all instances of a specific table mibVar (see IDA_GET_BULK_TE). Keep in mind that GetVars API will only populate your data field with the calculated maximum number of instances.
For each varid that is a table mibVar, user may specify the instance and instance length that the user is requesting. If the user wants the instance data of each response data, then user must specify an instanceItemLen. As with the data field, the instanceItemLen is used by the internals of the API to specify the length of each response instance to be place into the users instance field.
Note: for scaler variables an instance of .0 is implied.
Also, the user may specify a pointer to a long integer field that will contain the resulting InstanceCount returned for the specified varId. This value may be set to NULL if user doesnt desire the InstanceCount.
User may also specify the varType for each varId in the idaVarRecord structure. The specified varType will be used by the server for validation purposes. This field is often set to zero indicating no validation required.
If user is requesting repeating mibVars (Table data), the user must list the non-repeating MibVars first, then an IDAV_ENDOFNONREP entry, then the repeating mibVars. The IDAV_ENDOFNONREP entry is required if the user is requesting repeating table data. (See example, IDAApis.h and findServ.c sample code).
The last idaVarRecord entry must always be zeros. This null idaVarRecord is used by the internals of the Apis to determine the end of your request data.
IDA_GET:
IDA_GET: Usually used to get specific
piece(s) of data. This getType may be used to get a single instance
of a list of mibVars. This may be used to obtain scalar
(non-repeating) and/or table (repeating) mibVars.
IDA_GET_BULK_TE:
IDA_GET_BULK_TE will likely become the getType of choice once the developer becomes comfortable with the IDA_GetVars() api. This may be used to retrieve data for multiple mibVars and multiple iterations of each mibVar with one IDA_GetVars() request. User may specify a list of scalar mibVar records, delimited by the IDAV_ENDOFNONREP record, followed by a list of repeating mibVar records.
The server implements a GetNext mentality for IDA_GET_BULK_TE. GetNext implies the NEXT piece of data in the mib which follows the specified instance in the request.
The TE (Table End) indicates to the server to Stop At Table End for each specified repeating mibVar in your idaVarRecords array of structures. Unlike an IDA_GET_BULK, once the end of the table for each specified mibVar is reached, no additional data for that mibVar is populated into your idaVarRecords structure. You must specify a datap, dataLen, and dataItemLen for each repeating var in your structure. These variables specify where the resulting data should be placed (datap), the total length of your resulting datap buffer (dataLen), and the maximum length of each iteration of your data. The internals of the IDA_GetVars() use these variables to determine maximum number of iterations that will fit into your buffer. A instances of the mibVar (up to Table End or maximum number of iterations) will be placed into your buffer.
If you specify a pointer to instanceCountp, the resulting number of iterations of that mibVar will be specified in your instanceCountp long variable.
The power of the IDA_GET_BULK_TE is that you are able to retrieve all data for several tables in one request via IDA_GetVars(). And instanceCountp indicates the number of iterations for each mibVar requested.
IDA_GET_BULK_RE:
IDA_GET_BULK_RE is the same idea as IDA_GET_BULK_TE, except the server stops at the Row End for the specified mibVar.
IDA_GET_BULK:
IDA_GET_BULK: This getType is similar to the IDA_GET_BULK_TE and IDA_GET_BULK_RE, however the servers GetNext does not stop at the end of a table or row.
IDA_GET_BULK may be used to obtain
scalar (non-repeating) and/or table (repeating) mibVars. This may
be used as a GetNext to retrieve the next piece of data in the mib.
Therefore, IDA_GET_BULK requests may be used to perform a walk of
the mib. (See sample source mibWalk.c).
Specifying repeating mibVars as idaVarRecords in a IDA_GET_BULK request should be used with caution, as the GetNext theory may return data that a novice SNMP user may not expect. Refer to SNMP documentation related to GetNext. If a user uses this to request repeating mibVars, the mibVarId for the returned data will be placed as the first four bytes of the returned instance data. This will be indicated in the response by the IDAVAR_InstHasVarId bit being set for that mibVar.
IdaVarRecord.varResponseFlags:
The mibVar responses for IdaGetVars() may have one or more of several bits turned on to indicate specific conditions.
IDAVAR_EndOfView: For IDA_GET_BULK_TE and IDA_GET_BULK_RE, this bit indicates that the last instance of this repeating var has been returned even though more room was available in datap for additional response instances.
IDAVAR_DataLostDataLen: Response data has been lost because the users buffer (dataLen) was not large enough to contain the data. Partial data has been placed into the users data buffer.
IDAVAR_DataLostItemLen: Response data has been lost because the users item length (dataItemLen) was smaller than the amount of data returned for this instance. Partial data has been placed into the users data buffer.
IDAVAR_DataLostInstLen: Response instance data has been lost because the users instance buffer (instanceLen) was not large enough to contain the instance data. Partial instance data has been placed into the users instance buffer.
IDAVAR_DataLostInstItemLen: Response instance data has been lost because the users instance item length (instanceItemLen) was smaller than the amount of instance data returned. Partial instance data has been placed into the users instance buffer.
IDAVAR_InstHasVarId: The user requested repeating mibVars on an IDA_GetVars() request. In this case, all repeating mibVar responses will have the varId placed into the first four bytes of the users instance data buffer.
Example
char gVarBuff[3000];
char gInstBuff[80] = { 0 };
ulong gInstanceCnt = 0;
ulong errorIndex = 0;
uchar FuncCodes[133];
struct
{
uchar TermDotKeyswitch[10];
} FuncCodeInst[133] = { 0 };
ulong FuncCodeCount = 0;
idaVarRecord_t gGetBulkVar[] =
{
{ IDAN_PgmName,
gVarBuff , sizeof(gVarBuff) , sizeof(gVarBuff),
gInstBuff, sizeof(gInstBuff), sizeof(gInstBuff),
&gInstanceCnt, 0},
{ IDAV_ENDOFNONREP, 0, 0, 0, 0, 0, 0, 0, 0 },
{ IDAV_TermKeySwitchNormFCode,
FuncCodes, sizeof(FuncCodes), sizeof(FuncCodes[0]),
&FuncCodeInst, sizeof(FuncCodeInst), sizeof(FuncCodeInst[0]),
&FuncCodeCount, 0 },
{ 0, 0, 0, 0, 0, 0, 0, 0, 0 }
};
rc = IDA_GetVars(&gServID, IDA_GET_BULK, gGetBulkVar,
&errorIndex, &errorStatus);
| Converted from CHM to HTML with chm2web Pro 2.85 (unicode) |