Query results

Query results — RDF query results.

Functions

librdf_stream * librdf_query_results_as_stream ()
int librdf_query_results_get_count ()
int librdf_query_results_next ()
int librdf_query_results_finished ()
int librdf_query_results_get_bindings ()
librdf_node * librdf_query_results_get_binding_value ()
const char * librdf_query_results_get_binding_name ()
librdf_node * librdf_query_results_get_binding_value_by_name ()
int librdf_query_results_get_bindings_count ()
unsigned char * librdf_query_results_to_counted_string ()
unsigned char * librdf_query_results_to_counted_string2 ()
unsigned char * librdf_query_results_to_string ()
unsigned char * librdf_query_results_to_string2 ()
int librdf_query_results_to_file_handle ()
int librdf_query_results_to_file_handle2 ()
int librdf_query_results_to_file ()
int librdf_query_results_to_file2 ()
void librdf_free_query_results ()
int librdf_query_results_is_bindings ()
int librdf_query_results_is_boolean ()
int librdf_query_results_is_graph ()
int librdf_query_results_is_syntax ()
int librdf_query_results_get_boolean ()
librdf_query_results_formatter * librdf_new_query_results_formatter ()
librdf_query_results_formatter * librdf_new_query_results_formatter_by_mime_type ()
librdf_query_results_formatter * librdf_new_query_results_formatter2 ()
void librdf_free_query_results_formatter ()
int librdf_query_results_formats_check ()
const raptor_syntax_description * librdf_query_results_formats_get_description ()
int librdf_query_results_formats_enumerate ()
int librdf_query_results_formatter_write ()

Types and Values

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.

Functions

librdf_query_results_as_stream ()

librdf_stream *
librdf_query_results_as_stream (librdf_query_results *query_results);

Get a query result as an RDF graph in librdf_stream form

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

Parameters

query_results

librdf_query_results query_results

 

Returns

a new librdf_stream 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.

Parameters

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.

Parameters

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.

Parameters

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)) ...

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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);

librdf_query_results_to_counted_string is deprecated and should not be used in newly-written code.

Turn a query results into a string.

The default query results format will be used if format_uri is NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

The returned string must be freed by the caller using librdf_free_memory().

deprecated : Use librdf_query_results_to_counted_string2() with extra name and mime-type args.

Parameters

query_results

librdf_query_results object

 

format_uri

URI of syntax to format to (or NULL)

 

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_counted_string2 ()

unsigned char *
librdf_query_results_to_counted_string2
                               (librdf_query_results *query_results,
                                const char *name,
                                const char *mime_type,
                                librdf_uri *format_uri,
                                librdf_uri *base_uri,
                                size_t *length_p);

Turn a query results into a string.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if name , mime_type and format_uri are all NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

The returned string must be freed by the caller using librdf_free_memory().

Parameters

query_results

librdf_query_results object

 

name

name of syntax to format to

 

mime_type

mime type of syntax to format to (or NULL)

 

format_uri

URI of syntax to format to (or NULL)

 

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);

librdf_query_results_to_string is deprecated and should not be used in newly-written code.

Turn a query results into a string.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if format_uri is NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

The returned string must be freed by the caller using librdf_free_memory().

Deprecated : use librdf_query_results_to_string2() with extra name and mime_type args.

Parameters

query_results

librdf_query_results object

 

format_uri

URI of syntax to format to

 

base_uri

Base URI of output formatted syntax (or NULL)

 

Returns

new string value or NULL on failure


librdf_query_results_to_string2 ()

unsigned char *
librdf_query_results_to_string2 (librdf_query_results *query_results,
                                 const char *name,
                                 const char *mime_type,
                                 librdf_uri *format_uri,
                                 librdf_uri *base_uri);

Turn a query results into a string.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if name , mime_type and format_uri are all NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

The returned string must be freed by the caller using librdf_free_memory().

Parameters

query_results

librdf_query_results object

 

name

format name

 

mime_type

format mime type (or NULL)

 

format_uri

URI of syntax to format to (or NULL)

 

base_uri

Base URI of output formatted syntax (or NULL)

 

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);

librdf_query_results_to_file_handle is deprecated and should not be used in newly-written code.

Write a query results to a FILE*.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if format_uri is NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

Deprecated : use librdf_query_results_to_file_handle() with extra name and mime_type args.

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 (or NULL)

 

Returns

non 0 on failure


librdf_query_results_to_file_handle2 ()

int
librdf_query_results_to_file_handle2 (librdf_query_results *query_results,
                                      FILE *handle,
                                      const char *name,
                                      const char *mime_type,
                                      librdf_uri *format_uri,
                                      librdf_uri *base_uri);

Write a query results to a FILE*.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if name , mime_type and format_uri are all NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

Parameters

query_results

librdf_query_results object

 

handle

file handle to write to

 

name

result format name (or NULL)

 

mime_type

result mime type (or NULL)

 

format_uri

URI of syntax to format to (or NULL)

 

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);

librdf_query_results_to_file is deprecated and should not be used in newly-written code.

Write a query results to a file.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if format_uri is NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

Deprecated : use librdf_query_results_to_file2() with extra mime_type arg.

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 (or NULL)

 

Returns

non 0 on failure


librdf_query_results_to_file2 ()

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

Write a query results to a file.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if name , mime_type and format_uri are all NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

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

Parameters

query_results

librdf_query_results object

 

name

filename to write to

 

mime_type

mime type (or NULL)

 

format_uri

URI of syntax to format to (or NULL)

 

base_uri

Base URI of output formatted syntax (or NULL)

 

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.

Parameters

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.

Parameters

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.

If this function returns true, the result can be retrieved by librdf_query_results_get_boolean().

Parameters

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.

Parameters

query_results

librdf_query_results object

 

Returns

non-0 if true


librdf_query_results_is_syntax ()

int
librdf_query_results_is_syntax (librdf_query_results *query_results);

Test if librdf_query_results is a syntax.

If this function returns true, the ONLY result available from this query is a syntax that can be serialized using one of the query_result_formatter class methods or with librdf_query_results_to_counted_string(), librdf_query_results_to_string(), librdf_query_results_to_file_handle() or librdf_query_results_to_file()

Parameters

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

Parameters

query_results

librdf_query_results query_results

 

Returns

boolean query result - >0 is true, 0 is false, <0 on error or finished


librdf_new_query_results_formatter ()

librdf_query_results_formatter *
librdf_new_query_results_formatter (librdf_query_results *query_results,
                                    const char *name,
                                    librdf_uri *uri);

librdf_new_query_results_formatter is deprecated and should not be used in newly-written code.

Constructor - create a new librdf_query_results_formatter object by identified format.

A query results format can be named or identified by a URI, both of which are optional. The default query results format will be used if name and uri are both NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

Deprecated : for librdf_new_query_results_formatter2() with the name, mime_type and format_uri args.

Parameters

query_results

librdf_query_results query_results

 

name

the query results format name (or NULL)

 

uri

librdf_uri query results format uri (or NULL)

 

Returns

a new librdf_query_results_formatter object or NULL on failure


librdf_new_query_results_formatter_by_mime_type ()

librdf_query_results_formatter *
librdf_new_query_results_formatter_by_mime_type
                               (librdf_query_results *query_results,
                                const char *mime_type);

librdf_new_query_results_formatter_by_mime_type is deprecated and should not be used in newly-written code.

Constructor - create a new librdf_query_results_formatter object by mime type.

A query results format generates a syntax with a mime type which may be requested with this constructor.

Note that there may be several formatters that generate the same MIME Type (such as SPARQL XML results format drafts) and in thot case the librdf_new_query_results_formatter() constructor allows selecting of a specific one by name or URI.

Deprecated : for librdf_new_query_results_formatter2() with the name, mime_type and format_uri args.

Parameters

query_results

librdf_query_results query_results

 

mime_type

mime type name

 

Returns

a new librdf_query_results_formatter object or NULL on failure


librdf_new_query_results_formatter2 ()

librdf_query_results_formatter *
librdf_new_query_results_formatter2 (librdf_query_results *query_results,
                                     const char *name,
                                     const char *mime_type,
                                     librdf_uri *uri);

Constructor - create a new librdf_query_results_formatter object by identified format.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if name , mime_type and uri are all NULL.

librdf_query_results_formats_enumerate() returns information on the known query results names, labels and URIs.

Parameters

query_results

librdf_query_results query_results

 

name

the query results format name (or NULL)

 

mime_type

the query results format mime type (or NULL)

 

uri

librdf_uri query results format uri (or NULL)

 

Returns

a new librdf_query_results_formatter object or NULL on failure


librdf_free_query_results_formatter ()

void
librdf_free_query_results_formatter (librdf_query_results_formatter *formatter);

Destructor - destroy a librdf_query_results_formatter object.

Parameters

formatter

librdf_query_results_formatter object

 

librdf_query_results_formats_check ()

int
librdf_query_results_formats_check (librdf_world *world,
                                    const char *name,
                                    librdf_uri *uri,
                                    const char *mime_type);

Check if a query results formatter exists for the requested format.

Parameters

world

librdf_world

 

name

the query results format name (or NULL)

 

uri

librdf_uri query results format uri (or NULL)

 

mime_type

mime type name

 

Returns

non-0 if a formatter exists.


librdf_query_results_formats_get_description ()

const raptor_syntax_description *
librdf_query_results_formats_get_description
                               (librdf_world *world,
                                unsigned int counter);

Get query result formats descriptive syntax information

Parameters

world

world object

 

counter

index into the list of query results formats

 

Returns

description or NULL if counter is out of range


librdf_query_results_formats_enumerate ()

int
librdf_query_results_formats_enumerate
                               (librdf_world *world,
                                const unsigned int counter,
                                const char **name,
                                const char **label,
                                const unsigned char **uri_string,
                                const char **mime_type);

librdf_query_results_formats_enumerate is deprecated and should not be used in newly-written code.

Get information on query result syntaxes.

All returned strings are shared and must be copied if needed to be used dynamically.

Deprecated : use librdf_query_results_formats_get_description() to return more information in a static structure.

Parameters

world

librdf_world

 

counter

index into the list of query result syntaxes

 

name

pointer to store the name of the query result syntax (or NULL)

 

label

pointer to store query result syntax readable label (or NULL)

 

uri_string

pointer to store query result syntax URI string (or NULL)

 

mime_type

pointer to store query result syntax mime type string (or NULL)

 

Returns

non 0 on failure of if counter is out of range


librdf_query_results_formatter_write ()

int
librdf_query_results_formatter_write (raptor_iostream *iostr,
                                      librdf_query_results_formatter *formatter,
                                      librdf_query_results *query_results,
                                      librdf_uri *base_uri);

Write the query results using the given formatter to an iostream

See librdf_query_results_formats_enumerate() to get the list of syntax URIs and their description.

Parameters

iostr

raptor_iostream to write the query to

 

formatter

librdf_query_results_formatter object

 

base_uri

librdf_uri base URI of the output format

 

Returns

non-0 on failure

Types and Values

librdf_query_results

typedef struct librdf_query_results_s librdf_query_results;

Redland query results class.


librdf_query_results_formatter

typedef struct librdf_query_results_formatter_s librdf_query_results_formatter;

Redland query results formatter class.