Triples Source

## Triples Source Triples Source — Source of matches to a triple pattern. |

## Synopsis

                        rasqal_triple_meta;
                        rasqal_triples_match;
                        rasqal_triples_source;
                        rasqal_triples_source_factory;
    int                 (*rasqal_triples_source_factory_register_fn)
                                                            (rasqal_triples_source_factory *factory);
    enum                rasqal_triples_source_feature;
    void                (*rasqal_triples_error_handler)     (rasqal_query *query,
                                                             raptor_locator *locator,
                                                             const char *message);
    int                 rasqal_set_triples_source_factory   (rasqal_world *world,
                                                             rasqal_triples_source_factory_register_fn register_fn,
                                                             void *user_data);
    #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

A factory that provides the raw triple matches for a triple pattern against some RDF graph. The rasqal_triples_source_factory must create use a new rasqal_triples_source that can be used to initialise and build a rasqal_triples_match for some rasqal_triple (subject, predicate, object, origin URI).

## Details

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

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.

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.

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

int `version`; | API factory version from 1 to 2
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)

### 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

`factory` : | factory to register
Returns : | non-0 on failure

### enum rasqal_triples_source_feature

    typedef enum {
      RASQAL_TRIPLES_SOURCE_FEATURE_NONE,
      RASQAL_TRIPLES_SOURCE_FEATURE_IOSTREAM_DATA_GRAPH
    } rasqal_triples_source_feature;

Optional features that may be supported by a triple source factory

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

### rasqal_triples_error_handler ()

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

Triples source factory error handler callback.

`query` : | query 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.

`world` : | rasqal_world object
`register_fn` : | registration function
`user_data` : | user data for registration
Returns : | non-zero on failure

### 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 2

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