XesamGQueryBuilder

XesamGQueryBuilder — Used to compile a query from the output of a XesamGQueryParser or XesamGUserSearchParser, or to programmatically construct a query

Synopsis

                    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

Object Hierarchy

  GInterface
   +----XesamGQueryBuilder

Prerequisites

XesamGQueryBuilder requires GObject.

Known Implementations

XesamGQueryBuilder is implemented by XesamGXmlQueryBuilder.

Description

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

Details

XesamGQueryBuilder

typedef struct _XesamGQueryBuilder XesamGQueryBuilder;


XesamGQueryBuilderIface

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;


enum XesamGQueryBuilderError

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;

XESAM_G_QUERY_BUILDER_ERROR_INVALID_FIELD

A field was created without a name, or a field name supplied to xesam_g_query_builder_add_field() was not known or invalid

XESAM_G_QUERY_BUILDER_ERROR_INVALID_VALUE

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

XESAM_G_QUERY_BUILDER_ERROR_INVALID_ATTRIBUTE

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

XESAM_G_QUERY_BUILDER_ERROR_INVALID_ATTRIBUTE_LIST

The attr_vals and attr_names arguments of xesam_g_query_builder_add_value() does not have the same length

XESAM_G_QUERY_BUILDER_ERROR_INVALID_TOKEN_TYPE

When passing a token of invalid type to any of the builder methods

XESAM_G_QUERY_BUILDER_ERROR_INVALID_PARENT

When trying to close either a query or clause and the builder detects that you are going to close an element of another type

xesam_g_query_builder_start_query ()

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.

self :

The builder receiving the event

token :

The token defining the query type. This is either XESAM_G_QUERY_TOKEN_QUERY or XESAM_G_QUERY_TOKEN_USER_QUERY

content_cat :

The Content category to query or NULL if unset

source_cat :

The Source category to query or NULL if unset

error :

Place to store a errors or NULL to not receive notification of errors

Returns :

FALSE on error, TRUE otherwise

xesam_g_query_builder_add_clause ()

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.

self :

The builder receiving the event

token :

The token defining the clause type. See xesam_g_query_token_is_clause_type() for a list of clause type tokens

boost :

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

negate :

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

attr_names :

A NULL-terminated array of attribute names

attr_vals :

A NULL-terminated array of attribute values with indices corresponding to those of attr_names

error :

Place to store errors or NULL to not receive notification of errors

Returns :

FALSE on error, TRUE otherwise

xesam_g_query_builder_add_field ()

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

self :

The builder receiving the event

token :

The token defining the field type. This is either XESAM_G_QUERY_TOKEN_FIELD or XESAM_G_QUERY_TOKEN_FULL_TEXT_FIELDS

name :

The name of the field. For example 'xesam:title'. In case token is XESAM_G_QUERY_TOKEN_FULL_TEXT_FIELDS name will be NULL

error :

Place to store errors or NULL to not receive notification of errors

Returns :

FALSE on error, TRUE otherwise

xesam_g_query_builder_add_value ()

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

self :

The builder receiving the event

token :

The token defining the value type. A full list of value types can be found in xesam_g_query_token_is_value_type()

value :

A string containing the specific value to match

attr_names :

attr_vals :

error :

Place to store errors or NULL to not receive notification of errors

Returns :

FALSE on error, TRUE otherwise

xesam_g_query_builder_close_clause ()

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

self :

The builder receiving the event

error :

Place to store errors or NULL to not receive notification of errors

Returns :

FALSE on error, TRUE otherwise

xesam_g_query_builder_close_query ()

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

self :

The builder receiving the event

error :

Place to store errors or NULL to not receive notification of errors

Returns :

FALSE on error, TRUE otherwise

XESAM_G_QUERY_BUILDER_ERROR

#define XESAM_G_QUERY_BUILDER_ERROR xesam_g_query_builder_error_quark ()