![]() |
![]() |
![]() |
Xesam GLib Reference Manual | ![]() |
---|---|---|---|---|
XesamGQueryBuilderXesamGQueryBuilder — Used to compile a query from the output of a XesamGQueryParser or XesamGUserSearchParser, or to programmatically construct a query |
XesamGQueryBuilder; XesamGQueryBuilderIface; enum XesamGQueryBuilderError; gboolean xesam_g_query_builder_start_query (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *content_cat, const gchar *source_cat, GError **error); gboolean xesam_g_query_builder_add_clause (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *boost, const gboolean *negate, const gchar **attr_names, const gchar **attr_vals, GError **error); gboolean xesam_g_query_builder_add_field (XesamGQueryBuilder *self, XesamGQueryToken token, const char *name, GError **error); gboolean xesam_g_query_builder_add_value (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *value, const gchar **attr_names, const gchar **attr_vals, GError **error); gboolean xesam_g_query_builder_close_clause (XesamGQueryBuilder *self, GError **error); gboolean xesam_g_query_builder_close_query (XesamGQueryBuilder *self, GError **error); #define XESAM_G_QUERY_BUILDER_ERROR
XesamGQueryBuilder is a callback interface invoked from either a
XesamGQueryParser or XesamGUserSearchParser. Users familiar with
a SAX parser should get the idea. Builders are registered on a parser
via the method xesam_g_query_parser_add_builder()
or
xesam_g_user_search_parser_add_builder()
.
As the parser scans through the input it will invoke the relevant callbacks on the builder. The callbacks are guaranteed to be invoked in such a way as to produce a relevant query.
It is important to note that this interface does not define any way for consumers to retrieve the compiled query from the builder when the parser is done. Implementors of this interface should add that if needed.
XesamGQueryBuilder is available since 1.0
typedef struct { GTypeInterface parent_iface; gboolean (*start_query) (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *content_cat, const gchar *source_cat, GError **error); gboolean (*add_clause) (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *boost, const gboolean *negate, const gchar **attr_names, const gchar **attr_vals, GError** error); gboolean (*add_field) (XesamGQueryBuilder *self, XesamGQueryToken token, const char *name, GError **error); gboolean (*add_value) (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *value, const gchar **attr_names, const gchar **attr_vals, GError **error); gboolean (*close_clause) (XesamGQueryBuilder *self, GError **error); gboolean (*close_query) (XesamGQueryBuilder *self, GError **error); } XesamGQueryBuilderIface;
typedef enum { XESAM_G_QUERY_BUILDER_ERROR_INVALID_FIELD, XESAM_G_QUERY_BUILDER_ERROR_INVALID_VALUE, XESAM_G_QUERY_BUILDER_ERROR_INVALID_ATTRIBUTE, XESAM_G_QUERY_BUILDER_ERROR_INVALID_ATTRIBUTE_LIST, XESAM_G_QUERY_BUILDER_ERROR_INVALID_TOKEN_TYPE, XESAM_G_QUERY_BUILDER_ERROR_INVALID_PARENT } XesamGQueryBuilderError;
A field was created without a name,
or a field name supplied to
xesam_g_query_builder_add_field()
was not known or invalid
|
|
An invalid value declaration was
encountered. The typical example
is the case where the name argument
to xesam_g_query_builder_add_value()
is NULL
|
|
An attribute, passed to one
of
xesam_g_query_builder_start_query()
xesam_g_query_builder_add_clause()
xesam_g_query_builder_add_field()
or
xesam_g_query_builder_add_value()
was invalid
|
|
The attr_vals and
attr_names arguments
of
xesam_g_query_builder_add_value()
does not have the same
length
|
|
When passing a token of invalid type to any of the builder methods | |
When trying to close either a query or clause and the builder detects that you are going to close an element of another type |
gboolean xesam_g_query_builder_start_query (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *content_cat, const gchar *source_cat, GError **error);
A parser invokes this method when it starts parsing a new query.
The builder will reset its internal state when this method is invoked. In other words it is guaranteed that this call will always start building a new query from scratch and not clobber up with another half-finished query inside the builder.
|
The builder receiving the event |
|
The token defining the query type. This is either XESAM_G_QUERY_TOKEN_QUERY or XESAM_G_QUERY_TOKEN_USER_QUERY |
|
The Content category to query or NULL if unset
|
|
The Source category to query or NULL if unset
|
|
Place to store a errors or NULL to not receive notification of errors
|
Returns : |
FALSE on error, TRUE otherwise
|
gboolean xesam_g_query_builder_add_clause (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *boost, const gboolean *negate, const gchar **attr_names, const gchar **attr_vals, GError **error);
A parser invokes this method when it encounters a new clause type token.
Following this method call fields and values will be added to the clause
via xesam_g_query_builder_add_field()
and xesam_g_query_builder_add_value()
.
Finally xesam_g_query_builder_close_clause()
will be invoked to signal
that all info relevant for the clause has been transfered.
|
The builder receiving the event |
|
The token defining the clause type. See
xesam_g_query_token_is_clause_type() for a list of clause type tokens
|
|
Boost factor for the clause. This string is parseable as a float.
This paramter may be NULL in which case a default boost of 1.0
should be assumed
|
|
Whether to negate the matching of this clause. NULL specifies
that this parameter is undefined in which case the default value
FALSE should be assumed
|
|
A NULL -terminated array of attribute names
|
|
A NULL -terminated array of attribute values with indices
corresponding to those of attr_names
|
|
Place to store errors or NULL to not receive notification of errors
|
Returns : |
FALSE on error, TRUE otherwise
|
gboolean xesam_g_query_builder_add_field (XesamGQueryBuilder *self, XesamGQueryToken token, const char *name, GError **error);
A parser invokes this method when it encounters a field type token. This
will normally happen following a xesam_g_query_builder_add_clause()
.
Following this call either more fields will be added by calling
xesam_g_query_builder_add_field()
or value specifications will start
with invocations to xesam_g_query_builder_add_value()
.
|
The builder receiving the event |
|
The token defining the field type. This is either XESAM_G_QUERY_TOKEN_FIELD or XESAM_G_QUERY_TOKEN_FULL_TEXT_FIELDS |
|
The name of the field. For example 'xesam:title'. In case
token is XESAM_G_QUERY_TOKEN_FULL_TEXT_FIELDS name will be NULL
|
|
Place to store errors or NULL to not receive notification of errors
|
Returns : |
FALSE on error, TRUE otherwise
|
gboolean xesam_g_query_builder_add_value (XesamGQueryBuilder *self, XesamGQueryToken token, const gchar *value, const gchar **attr_names, const gchar **attr_vals, GError **error);
A parser invokes this method when it encounters a value type token. This
will normally happen following a xesam_g_query_builder_add_field()
.
|
The builder receiving the event |
|
The token defining the value type. A full list of value types
can be found in xesam_g_query_token_is_value_type()
|
|
A string containing the specific value to match |
|
|
|
|
|
Place to store errors or NULL to not receive notification of errors
|
Returns : |
FALSE on error, TRUE otherwise
|
gboolean xesam_g_query_builder_close_clause (XesamGQueryBuilder *self, GError **error);
A parser invokes this method when the end of a clause has been reached.
Following this either a new clause will be added with
xesam_g_query_builder_add_clause()
or the query will be closed with
xesam_g_query_builder_close_query()
.
|
The builder receiving the event |
|
Place to store errors or NULL to not receive notification of errors
|
Returns : |
FALSE on error, TRUE otherwise
|
gboolean xesam_g_query_builder_close_query (XesamGQueryBuilder *self, GError **error);
A parser invokes this method when the current query is fully parsed and no more tokens will be emitted on it.
After this invocation the builder should be ready to deliver any feedback (such as a compiled query or other) if it has any output.
Following this method the builder will either be finalized or restarted
with an invocation of xesam_g_query_builder_start_query()
.
|
The builder receiving the event |
|
Place to store errors or NULL to not receive notification of errors
|
Returns : |
FALSE on error, TRUE otherwise
|