## section-triples_source

section-triples_source

## Functions

int | (*rasqal_triples_source_factory_register_fn) ()
void | (*rasqal_triples_error_handler) ()
void | (*rasqal_triples_error_handler2) ()
int | rasqal_set_triples_source_factory ()

## Types and Values

| rasqal_triple_meta
| rasqal_triples_match
| rasqal_triples_source
| rasqal_triples_source_factory
enum | rasqal_triples_source_feature
#define | RASQAL_TRIPLES_SOURCE_FACTORY_MIN_VERSION
#define | RASQAL_TRIPLES_SOURCE_FACTORY_MAX_VERSION
#define | RASQAL_TRIPLES_SOURCE_MIN_VERSION
#define | RASQAL_TRIPLES_SOURCE_MAX_VERSION

## Description

## Functions

### rasqal_triples_source_factory_register_fn ()

    int
    (*rasqal_triples_source_factory_register_fn)
                                   (rasqal_triples_source_factory *factory);

Register a factory for generating triples sources rasqal_triples_source

#### Parameters

factory | factory to register |

#### Returns

non-0 on failure

### rasqal_triples_error_handler ()

    void
    (*rasqal_triples_error_handler) (rasqal_query *query,
                                     raptor_locator *locator,
                                     const char *message);

Triples source factory error handler callback.

#### Parameters

query | query object |
locator | error locator (or NULL) |
message | error message |

### rasqal_triples_error_handler2 ()

    void
    (*rasqal_triples_error_handler2) (rasqal_world *world,
                                      raptor_locator *locator,
                                      const char *message);

Triples source factory error handler callback.

#### Parameters

world | world object |
locator | error locator (or NULL) |
message | error message |

### rasqal_set_triples_source_factory ()

    int
    rasqal_set_triples_source_factory (rasqal_world *world,
                                       rasqal_triples_source_factory_register_fn register_fn,
                                       void *user_data);

Register a factory to generate triple sources.

Registers the factory that returns triples sources. Note that there is only one of these per runtime.

The rasqal_triples_source_factory factory method new_triples_source is called with the user data for some query and rasqal_triples_source.

#### Parameters

world | rasqal_world object |
register_fn | registration function |
user_data | user data for registration |

#### Returns

non-zero on failure

## Types and Values

### rasqal_triple_meta

    typedef struct {
      /* triple (subject, predicate, object) and origin */
      rasqal_variable* bindings[4];

      rasqal_triples_match *triples_match;

      void *context;

      rasqal_triple_parts parts;

      int is_exact;

      int executed;
    } rasqal_triple_meta;

Metadata for triple pattern matching for one triple pattern.

#### Members

rasqal_variable *`bindings`[4]; | Variable bindings for this triple+origin to set. |
rasqal_triples_match *`triples_match`; | The matcher that is setting these bindings. |
void *`context`; | Context data used by the matcher. |
rasqal_triple_parts `parts`; | Bitmask of rasqal_triple_parts flags describing the parts of the triple pattern that will bind to variables. There may also be variables mentioned that are bound in other triple patterns even if `parts` is 0. |
int `is_exact`; | unused |
int `executed`; | unused |

### rasqal_triples_match

    typedef struct {
      void *user_data;

      rasqal_triple_parts (*bind_match)(struct rasqal_triples_match_s* rtm, void *user_data, rasqal_variable *bindings[4], rasqal_triple_parts parts);

      void (*next_match)(struct rasqal_triples_match_s* rtm, void *user_data);

      int (*is_end)(struct rasqal_triples_match_s* rtm, void *user_data);

      void (*finish)(struct rasqal_triples_match_s* rtm, void *user_data);

      rasqal_world *world;
    } rasqal_triples_match;

Triples match structure as initialised by rasqal_triples_source method init_triples_match.

#### Members

void *`user_data`; | User data pointer for factory methods. |
`bind_match` () | The [4]array (s,p,o,origin) bindings against the current triple match only touching triple parts given. Returns parts that were bound or 0 on failure. |
`next_match` () | Move to next match. |
`is_end` () | Check for end of triple match - return non-0 if is end. |
`finish` () | Finish triples match and destroy any allocated memory. |
rasqal_world *`world`; | rasqal_world object |

### rasqal_triples_source

    typedef struct {
      rasqal_query* query;

      void *user_data;

      int (*init_triples_match)(rasqal_triples_match* rtm, struct rasqal_triples_source_s* rts, void *user_data, rasqal_triple_meta *m, rasqal_triple *t);

      int (*triple_present)(struct rasqal_triples_source_s* rts, void *user_data, rasqal_triple *t);

      void (*free_triples_source)(void *user_data);
    } rasqal_triples_source;

Triples source as initialised by a rasqal_triples_source_factory.

#### Members

rasqal_query *`query`; | Source for this query. |
void *`user_data`; | Context user data passed into the factory methods. |
`init_triples_match` () | Factory method to initalise a new rasqal_triples_match. |
`triple_present` () | Factory method to return presence or absence of a complete triple. |
`free_triples_source` () | Factory method to deallocate resources. |

### rasqal_triples_source_factory

    typedef struct {
      int version;

      void *user_data;
      size_t user_data_size;

      /* API v1 */
      int (*new_triples_source)(rasqal_query* query, void *factory_user_data, void *user_data, rasqal_triples_source* rts);
      /* API v2 onwards */
      int (*init_triples_source)(rasqal_query* query, void *factory_user_data, void *user_data, rasqal_triples_source* rts, rasqal_triples_error_handler handler);
      /* API v3 onwards */
      int (*init_triples_source2)(rasqal_world* world, raptor_sequence* data_graphs, void *factory_user_data, void *user_data, rasqal_triples_source *rts, rasqal_triples_error_handler2 handler, unsigned int flags);
    } rasqal_triples_source_factory;

A factory that initialises rasqal_triples_source structures to returning matches to a triple pattern across the dataset formed from the data graphs recorded in the `query` object.

#### Members

int `version`; | API factory version from 1 to 3 |
void *`user_data`; | User data for triples_source_factory. |
size_t `user_data_size`; | Size of `user_data` for new_triples_source. |
`new_triples_source` () | Create a new triples source - returns non-zero on failure < 0 is a 'no rdf data error', > 0 is an unspecified error. Error messages are generated by rasqal internally. (V1) |
`init_triples_source` () | Initialise a new triples source V2 for a particular source URI/base URI and syntax. Returns non-zero on failure with errors reported via the handler callback by the implementation. (V2) |
`init_triples_source2` () | Initialise a new triples source V3 for a particular source URI/base URI and syntax and given data graphs. Returns non-zero on failure with errors reported via the handler callback by the implementation. If bit 0 of flags is 1, enforce RAPTOR_FEATURE_NO_NET (V3) |

### enum rasqal_triples_source_feature

Optional features that may be supported by a triple source factory

#### Members

RASQAL_TRIPLES_SOURCE_FEATURE_NONE | No feature |
RASQAL_TRIPLES_SOURCE_FEATURE_IOSTREAM_DATA_GRAPH | Support raptor_iostream data graphs |

### RASQAL_TRIPLES_SOURCE_FACTORY_MIN_VERSION

    #define RASQAL_TRIPLES_SOURCE_FACTORY_MIN_VERSION 1

Lowest accepted `rasqal_triples_source_factory` API version

### RASQAL_TRIPLES_SOURCE_FACTORY_MAX_VERSION

    #define RASQAL_TRIPLES_SOURCE_FACTORY_MAX_VERSION 3

Highest accepted `rasqal_triples_source_factory` API version

### RASQAL_TRIPLES_SOURCE_MIN_VERSION

    #define RASQAL_TRIPLES_SOURCE_MIN_VERSION 1

Lowest accepted `rasqal_triples_source` API version

### RASQAL_TRIPLES_SOURCE_MAX_VERSION

    #define RASQAL_TRIPLES_SOURCE_MAX_VERSION 2

Highest accepted `rasqal_triples_source` API version