DR_ApDescribeBuffer

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `DR_ApDescribeBuffer`

`DR_ApDescribeBuffer` -- gets segment attribute information.

## Syntax

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

Prev | Home | Next
`DR_ApConnectIPC` | Up | `DR_ApDescribePnt`

Copyright 1995-2002 by Cogent Real-Time Systems, Inc.