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");