Cogent C API and Utilities : Version 6.4
	Cogent Driver Functions

`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 */
        }
}

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


DR_ApListBuffers		DR_ApPointBufAddress