71 lines
1.9 KiB
Text
71 lines
1.9 KiB
Text
|
UPSCLI_LIST_NEXT(3)
|
||
|
|
===================
|
||
|
|
|
||
|
|
NAME
|
||
|
|
----
|
||
|
|
|
||
|
|
upscli_list_next - retrieve list items from a UPS
|
||
|
|
|
||
|
|
SYNOPSIS
|
||
|
|
--------
|
||
|
|
|
||
|
|
#include <upsclient.h>
|
||
|
|
|
||
|
|
int upscli_list_next(UPSCONN_t *ups, int numq, const char **query,
|
||
|
|
int *numa, char ***answer)
|
||
|
|
|
||
|
|
DESCRIPTION
|
||
|
|
-----------
|
||
|
|
|
||
|
|
The *upscli_list_next()* function takes the pointer 'ups' to a
|
||
|
|
`UPSCONN_t` state structure, and the pointer 'query' to an array of
|
||
|
|
'numq' query elements. It performs a read from the network and
|
||
|
|
expects to find either another list item or the end of a list.
|
||
|
|
|
||
|
|
You must call linkman:upscli_list_start[3] before calling this function.
|
||
|
|
|
||
|
|
This function will return 1 and set values in 'numa' and
|
||
|
|
'answer' if a list item is received. If the list is done, it will
|
||
|
|
return 0, and the values in 'numa' and 'answer' are undefined.
|
||
|
|
|
||
|
|
Calling this function after it returns something other than 1 is
|
||
|
|
undefined.
|
||
|
|
|
||
|
|
QUERY FORMATTING
|
||
|
|
----------------
|
||
|
|
|
||
|
|
You may not change the values of 'numq' or 'query' between the
|
||
|
|
call to linkman:upscli_list_start[3] and the first call to this function.
|
||
|
|
You also may not change the values between calls to this function.
|
||
|
|
|
||
|
|
ANSWER FORMATTING
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
The contents of 'numa' and 'answer' work just like a call to
|
||
|
|
linkman:upscli_get[3]. The values returned by linkman:upsd[8] are identical to
|
||
|
|
a single item request, so this is not surprising.
|
||
|
|
|
||
|
|
ERROR CHECKING
|
||
|
|
--------------
|
||
|
|
|
||
|
|
This function checks the response from linkman:upsd[8] against your query.
|
||
|
|
If the response is not part of the list you have requested, it will
|
||
|
|
return an error code.
|
||
|
|
|
||
|
|
When this happens, linkman:upscli_upserror[3] will return
|
||
|
|
`UPSCLI_ERR_PROTOCOL`.
|
||
|
|
|
||
|
|
RETURN VALUE
|
||
|
|
------------
|
||
|
|
|
||
|
|
The *upscli_list_next()* function returns 1 when list data is
|
||
|
|
present, 0 if the list is finished, or -1 if an error occurs.
|
||
|
|
|
||
|
|
It is possible to have an empty list. The function will return 0 for
|
||
|
|
its first call in that case.
|
||
|
|
|
||
|
|
SEE ALSO
|
||
|
|
--------
|
||
|
|
linkman:upscli_list_start[3],
|
||
|
|
linkman:upscli_strerror[3], linkman:upscli_upserror[3]
|