DR_ApListPoints

Cogent API and Utilities: Version 4.1
Prev |  | Next

# `DR_ApListPoints`

`DR_ApListPoints` -- lists points defined to the driver.

## Syntax

``int DR_ApListPoints`(char * filter, int * num_names, char ** pnt_names, int max_names, char * data, int max_data_length, char ** error);`

## Arguments

`filter`

  A string containing a filter specification for the points, including name pattern, and point status and type. If `NULL` is provided, then all points will be requested (the equivalent of using a filter pattern of "*"). The filter syntax is as follows:

          name_pattern [w][r][e][d][t type]

  where:

  - `name_pattern` is required and supports wildcard characters `*` and `?`.

  - The optional status filters `w`, `r`, `e`, and `d` correspond to the points writeable, readable, enabled, and disabled status respectively.

  - The optional type filter `t` must be followed by a valid type name: `digital`, `integer`, `group`, `string`, `heartbeat` or `real`.

`num_names`

  If not `NULL`, then the number of names found is returned here.

`pnt_names`

  If not `NULL`, a pointer to an array of `char` pointers (at least `max_names` long), to be filled with pointers to the name strings returned by the driver in the data buffer. The pointers will point to parsed data contained in the buffer specified by the `data` parameter (if provided). Otherwise the data will remain in the internal message buffers (referenced by the `char` pointers) and can only be guaranteed to remain valid until the next API function call.

`max_names`

  The length of the `pnt_names` array (maximum number of names that can be returned).

`data`

  If not `NULL`, then the string of point names returned by the driver is copied to this buffer, prior to parsing and assigning name pointers. Since the point names are returned as an array of pointers to a parsed buffer, this parameter provides a mechanism to ensure the contents of `pnt_names` will continue to be valid beyond the next API function call. In some cases, you may wish to simply check or explicitly copy out just a few names, and not require that the `names` data persist. In these cases, copying the data is not required, and a `NULL` can be supplied for this parameter.

`max_data_length`

  The length of the data buffer in bytes.

`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

## Description

This function provides a list of the points currently defined to the driver. The result can be used to determine the individual point characteristics.

## Example

        int         j, nargs, type, result;
        char        data[1024];
        char        *nargv[128];
        char        *error_str;

        result = DR_ApListPoints (NULL, &nargs, nargv, 128, data, 1024,
                                  &error_str);
        if (!result)
        {
                for (j = 1; j<nargs; j++)
                {
                        DR_ApReadPoint(nargv[j], &type, &value, &error_str);
                        /* process point */
                }
        }

Prev | Home | Next
`DR_ApListBuffers` | Up | `DR_ApPointBufAddress`

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