6.3 Output

The dico_output_result method is called when the server needs to output the result of a ‘define’ or ‘match’ command. It must be defined as follows:

int output_result (dico_result_t rp, size_t n,
                   dico_stream_t str);

The rp argument points to the result in question. From the server’s point of view it is an opaque pointer. The application shall define its own result structure, so normally the first operation the dico_output_result method does is typecasting rp to a pointer to that structure in order to be able to access its members.

A result can conceptually contain several parts. For example, the result of a ‘DEFINE’ command can contain several definitions of the term. Similarly, the result of ‘MATCH’ contains one or more matches. The server obtains the exact number of parts in a result by calling the dico_result_count method (see dico_result_count).

When outputting a result, the server calls the dico_output_result in a loop, once for each result part. It passes the ordinal (zero-based) number of the part that needs to be output in the n parameter. It is guaranteed that n increases by one for each subsequent call of dico_output_result with the same rp parameter.

The str parameter identifies the output stream. The dico_output_result function must format the requested part from the result and output it to that stream. To do so it should use one of the following functions:

Function: int dico_stream_write (dico_stream_t str, const void *buf, size_t count) ¶

Writes count bytes from the buffer pointed to by buf to the output stream str. Returns 0 on success, and non-zero on error.

Function: int dico_stream_writeln (dico_stream_t str, const char *buf, size_t size) ¶

Same as dico_stream_write, but ends the output with a newline character (ASCII 10).