Query results

## Query results Query results — RDF query results. |

## Synopsis

    typedef     librdf_query_results;
    librdf_stream* librdf_query_results_as_stream
                                                (librdf_query_results *query_results);
    int         librdf_query_results_get_count  (librdf_query_results *query_results);
    int         librdf_query_results_next       (librdf_query_results *query_results);
    int         librdf_query_results_finished   (librdf_query_results *query_results);
    int         librdf_query_results_get_bindings
                                                (librdf_query_results *query_results,
                                                 const char ***names,
                                                 librdf_node **values);
    librdf_node* librdf_query_results_get_binding_value
                                                (librdf_query_results *query_results,
                                                 int offset);
    const char* librdf_query_results_get_binding_name
                                                (librdf_query_results *query_results,
                                                 int offset);
    librdf_node* librdf_query_results_get_binding_value_by_name
                                                (librdf_query_results *query_results,
                                                 const char *name);
    int         librdf_query_results_get_bindings_count
                                                (librdf_query_results *query_results);
    unsigned char* librdf_query_results_to_counted_string
                                                (librdf_query_results *query_results,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri,
                                                 size_t *length_p);
    unsigned char* librdf_query_results_to_string
                                                (librdf_query_results *query_results,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri);
    int         librdf_query_results_to_file_handle
                                                (librdf_query_results *query_results,
                                                 FILE *handle,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri);
    int         librdf_query_results_to_file    (librdf_query_results *query_results,
                                                 const char *name,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri);
    void        librdf_free_query_results       (librdf_query_results *query_results);
    int         librdf_query_results_is_bindings
                                                (librdf_query_results *query_results);
    int         librdf_query_results_is_boolean (librdf_query_results *query_results);
    int         librdf_query_results_is_graph   (librdf_query_results *query_results);
    int         librdf_query_results_get_boolean
                                                (librdf_query_results *query_results);

## Description

The results of an librdf_query execution as a sequence of individual results, an RDF graph as a sequence of triples or a boolean. For variable binding results, the binding names and values can be read in multiple forms and the number of results returned as well as the current result moved to the next. For an RDF graph result, the stream of triples can be returned. For a boolean result, the value can be returned. All results can be turned into a string XML format based on the SPARQL XML results format which can also be written to a file.

## Details

### librdf_query_results

    typedef struct librdf_query_results_s librdf_query_results;

Redland query results class.

### librdf_query_results_as_stream ()

    librdf_stream* librdf_query_results_as_stream
                                                (librdf_query_results *query_results);

The return value is only meaningful if this is an RDF graph query result - see librdf_query_results_is_graph

`query_results` : | librdf_query_results query_results
Returns : | RDF graph query result or NULL on error

### librdf_query_results_get_count ()

    int         librdf_query_results_get_count  (librdf_query_results *query_results);

Get number of bindings so far.

`query_results` : | librdf_query_results query results
Returns : | number of bindings found so far

### librdf_query_results_next ()

    int         librdf_query_results_next       (librdf_query_results *query_results);

Move to the next result.

`query_results` : | librdf_query_results query results
Returns : | non-0 if failed or results exhausted

### librdf_query_results_finished ()

    int         librdf_query_results_finished   (librdf_query_results *query_results);

Find out if binding results are exhausted.

`query_results` : | librdf_query_results query results
Returns : | non-0 if results are finished or query failed

### librdf_query_results_get_bindings ()

    int         librdf_query_results_get_bindings
                                                (librdf_query_results *query_results,
                                                 const char ***names,
                                                 librdf_node **values);

Get all binding names, values for current result.

If names is not NULL, it is set to the address of a shared array of names of the bindings (an output parameter). These names are shared and must not be freed by the caller

If values is not NULL, it is used as an array to store pointers to the librdf_node* of the results. These nodes must be freed by the caller. The size of the array is determined by the number of names of bindings, returned by librdf_query_get_bindings_count dynamically or will be known in advanced if hard-coded into the query string.

Example

const char **names=NULL; librdf_node* values[10];

if(librdf_query_results_get_bindings(results, &names, values)) ...

`query_results` : | librdf_query_results query results
`names` : | pointer to an array of binding names (or NULL)
`values` : | pointer to an array of binding value librdf_node (or NULL)
Returns : | non-0 if the assignment failed

### librdf_query_results_get_binding_value ()

    librdf_node* librdf_query_results_get_binding_value
                                                (librdf_query_results *query_results,
                                                 int offset);

Get one binding value for the current result.

`query_results` : | librdf_query_results query results
`offset` : | offset of binding name into array of known names
Returns : | a new librdf_node binding value or NULL on failure

### librdf_query_results_get_binding_name ()

    const char* librdf_query_results_get_binding_name
                                                (librdf_query_results *query_results,
                                                 int offset);

Get binding name for the current result.

`query_results` : | librdf_query_results query results
`offset` : | offset of binding name into array of known names
Returns : | a pointer to a shared copy of the binding name or NULL on failure

### librdf_query_results_get_binding_value_by_name ()

    librdf_node* librdf_query_results_get_binding_value_by_name
                                                (librdf_query_results *query_results,
                                                 const char *name);

Get one binding value for a given name in the current result.

`query_results` : | librdf_query_results query results
`name` : | variable name
Returns : | a new librdf_node binding value or NULL on failure

### librdf_query_results_get_bindings_count ()

    int         librdf_query_results_get_bindings_count
                                                (librdf_query_results *query_results);

Get the number of bound variables in the result.

`query_results` : | librdf_query_results query results
Returns : | <0 if failed or results exhausted

### librdf_query_results_to_counted_string ()

    unsigned char* librdf_query_results_to_counted_string
                                                (librdf_query_results *query_results,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri,
                                                 size_t *length_p);

Turn a query results into a string.

Values of format_uri currently supported (via Rasqal) are: http://www.w3.org/TR/2004/WD-rdf-sparql-XMLres-20041221/

The base URI may be used for the generated syntax, depending on the format.

The returned string must be freed by the caller

`query_results` : | librdf_query_results object
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax or NULL
`length_p` : | Pointer to where to store length of string or NULL
Returns : | new string value or NULL on failure

### librdf_query_results_to_string ()

    unsigned char* librdf_query_results_to_string
                                                (librdf_query_results *query_results,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri);

Turn a query results into a string.

See librdf_query_results_to_counted_string for information on the format_uri and base_uri parameters.

The returned string must be freed by the caller

`query_results` : | librdf_query_results object
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax
Returns : | new string value or NULL on failure

### librdf_query_results_to_file_handle ()

    int         librdf_query_results_to_file_handle
                                                (librdf_query_results *query_results,
                                                 FILE *handle,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri);

Write a query results to a FILE*.

See librdf_query_results_to_counted_string for information on the format_uri and base_uri parameters.

`query_results` : | librdf_query_results object
`handle` : | file handle to write to
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax
Returns : | non 0 on failure

### librdf_query_results_to_file ()

    int         librdf_query_results_to_file    (librdf_query_results *query_results,
                                                 const char *name,
                                                 librdf_uri *format_uri,
                                                 librdf_uri *base_uri);

Write a query results to a file.

See librdf_query_results_to_counted_string for information on the format_uri and base_uri parameters.

`query_results` : | librdf_query_results object
`name` : | filename to write to
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax
Returns : | non 0 on failure

### librdf_free_query_results ()

    void        librdf_free_query_results       (librdf_query_results *query_results);

Destructor - destroy a librdf_query_results object.

`query_results` : | librdf_query_results object

### librdf_query_results_is_bindings ()

    int         librdf_query_results_is_bindings
                                                (librdf_query_results *query_results);

Test if librdf_query_results is variable bindings format.

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_is_boolean ()

    int         librdf_query_results_is_boolean (librdf_query_results *query_results);

Test if librdf_query_results is boolean format.

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_is_graph ()

    int         librdf_query_results_is_graph   (librdf_query_results *query_results);

Test if librdf_query_results is RDF graph format.

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_get_boolean ()

    int         librdf_query_results_get_boolean
                                                (librdf_query_results *query_results);

Get boolean query result.

The return value is only meaningful if this is a boolean query result - see librdf_query_results_is_boolean

`query_results` : | librdf_query_results query_results
Returns : | boolean query result - >0 is true, 0 is false, <0 on error or finished