DR_ApDescribeBuffer
DR_ApDescribeBuffer — gets segment attribute information.
Syntax
#include <cogent.h>
int DR_ApDescribeBuffer( | int | card_id, |
| | int | buffer_id, |
| | int | initial_seg, |
| | int | max_attr, |
| | int* | num_attr, |
| | DR_ApSegAttributes_t* | attributes, |
| | char** | error); |
Arguments
- card-id
- The
card ID of the requested buffer.
- buffer_id
- The buffer ID of the requested
buffer.
- initial_seg
- The ID of the first segment to be described.
This parameter, in combination with
max_attr, permits only a portion of the
segments to be listed. This is useful if there are a large
number of segments and limited memory space to contain
them. Segments can be referenced as 0 to
n-1.
- max_attr
- The maximum number of segments to be
described, which must be less than or equal to the length of
the array of DR_ApSegAttributes_t
structures.
- attributes
- A pointer to an array of
DR_ApSegAttributes_t
structures, of length at least
max_attr, that will receive the
segment attribute information. Each element in the
array (a segment attribute structure) describes a
segment of the buffer with a particular data type and
r/w capability. Multiple segments can exist in a
buffer, so that more than one set of attributes may be
returned for each buffer. Each segment description
includes an offset in the buffer and length in bytes,
the segment type and the readable and writeable
attributes.
- error
- The
address of a string pointer. In case of error (non-zero
return), the string pointer is set to the corresponding error
description string. The error string is contained in a static
buffer and remains valid only until the next API call. The
parameter may be NULL if no error string
is required.
Returns
The integer value
0 if the function was successful, otherwise one
of the following error codes:
DR_API_IPC_ERRORS
DR_API_STATUS_ERRORS
DR_ERR_CARD_INVALID
DR_ERR_BLK_INVALID
DR_ERR_BLK_NOT_FOUND
DR_ERR_NO_USER_OBJECT
Description
This function gets information on
the segment attributes of the specified buffer.
Example
int i, j, n_attr, num_blks;
DR_ApSegAttributes_t seg_attr[4][32];
/* continued from example of DR_ApListBuffers */
for (i=0; i<num_blks; i++)
{
if (!(result = DR_ApDescribeBuffer (0, i, 0, 32, &n_attr,
&(seg_attr[i][0]), &error_str)))
{
printf (" Buffer %d:\n", i);
for (j=0; j<n_attr; j++)
{
printf ("[%d] %s%s %s data from %d for %d bytes\n",
(seg_attr[i][j].buf_id),
(seg_attr[i][j].readable?"reads":""),
(seg_attr[i][j].writeable?"writes":""),
((DR_API_BIT_TYPE == seg_attr[i][j].type)
?"digital":
((DR_API_INT16_TYPE ==seg_attr[i][j].type)
?"analog":"unknown")),
seg_attr[i][j].offset,
seg_attr[i][j].size);
}
}
else
printf (" Error@DescribeBuffer (%d,%s)\n",
result, error_str);
}
printf (" Digital read requires blocks: ");
for (i=0; i<num_blks; i++)
for (j=0; j<n_attr; j++)
{
if (seg_attr[i][j].readable &&
seg_attr[i][j].type==DR_API_BIT_TYPE)
{
printf(" %d[%d] for %d, ",
seg_attr[i][j].buf_id,
seg_attr[i][j].offset,
seg_attr[i][j].size);
}
}
printf ("\n");
printf (" Analog write requires blocks: ");
for (i=0; i<num_blks; i++)
for (j=0; j<n_attr; j++)
{
if (seg_attr[i][j].writeable &&
seg_attr[i][j].type==DR_API_INT16_TYPE)
{
printf(" %d[%d] for %d, ",
seg_attr[i][j].buf_id,
seg_attr[i][j].offset,
seg_attr[i][j].size);
}
}
printf ("\n");
