DR_ApListPoints
DR_ApListPoints — lists points defined to the driver.
Syntax
#include <cogent.h>
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 */
}
}
