mirror/XQuilla
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity
XQuilla/include/xqc.h
King_DuckZ 4bc0157dcd v2.2.0
2020-02-17 22:17:06 +01:00

973 lines
36 KiB
C
Raw Permalink Blame History

/*
* Copyright (c) 2008, Matthias Brantner, John Snelson
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* * Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* * Neither the name of the developers nor the names of contributors may be
* used to endorse or promote products derived from this software without
* specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
#ifndef _XQUERY_C_API_H
#define _XQUERY_C_API_H
/* Include stdio for FILE */
#include <stdio.h>
#ifdef __cplusplus
extern "C" {
#endif
/** The version of the XQC API in this header file */
#define XQC_VERSION_NUMBER 1
typedef struct XQC_Implementation_s XQC_Implementation;
typedef struct XQC_StaticContext_s XQC_StaticContext;
typedef struct XQC_Expression_s XQC_Expression;
typedef struct XQC_DynamicContext_s XQC_DynamicContext;
typedef struct XQC_Sequence_s XQC_Sequence;
typedef struct XQC_InputStream_s XQC_InputStream;
typedef struct XQC_ErrorHandler_s XQC_ErrorHandler;
/**
* The error enumeration used by all XQC functions to designate error condition.
* All XQC functions return a value of type ::XQC_Error.
*/
typedef enum {
XQC_NO_ERROR = 0, ///< No error.
XQC_END_OF_SEQUENCE, ///< The end of the XQC_Sequence has been reached.
XQC_NO_CURRENT_ITEM,
XQC_PARSE_ERROR,
XQC_INVALID_ARGUMENT,
XQC_NOT_NODE,
XQC_INTERNAL_ERROR, ///< An implementation specific error has occurred.
XQC_NOT_IMPLEMENTED, ///< The implementation does not implement that function.
/**
* The encoding of the query has not been recognized, or is not supported by the
* implementation. All implementations must support queries in UTF-8.
*/
XQC_UNRECOGNIZED_ENCODING,
XQC_STATIC_ERROR, ///< A static error has occured while preparing the query
XQC_TYPE_ERROR, ///< A type error has occured while preparing or executing the query
XQC_DYNAMIC_ERROR, ///< A dynamic error has occured while preparing or executing the query
XQC_SERIALIZATION_ERROR ///< A serialization error has occured while serializing the output of a query
} XQC_Error;
/**
* The ::XQC_InputStream struct is designed to be populated by users for the purpose
* of streaming data into an XQC implementation.
*/
struct XQC_InputStream_s {
/**
* The text encoding of the input data as a UTF-8 string, or 0 if unknown. The value of the string
* should conform to the <code>EncName</code> grammar production as specified in XML 1.0:
*
* http://www.w3.org/TR/REC-xml/#NT-EncName
*/
const char *encoding;
/**
* Can be used for user specific purposes.
*/
void *user_data;
/**
* The function called to read more of the input query. The function should read
* the next chunk of input into the buffer provided, returning the length of the
* data read.
*
* \param stream The XQC_InputStream that this function pointer is a member of
* \param[out] buffer The buffer to read the data into
* \param length The length of the buffer
*
* \return The number of bytes read - this will be less than length if the end of the input is reached
*
* \todo Does this function need to be able to return an error condition?
*/
unsigned int (*read)(XQC_InputStream *stream, void *buffer, unsigned int length);
/**
* Called to free the resources associated with the XQC_InputStream.
*
* \param stream The XQC_InputStream that this function pointer is a member of
*
*/
void (*free)(XQC_InputStream *stream);
};
/**
* The ::XQC_ErrorHandler struct is designed to be populated by users for the purpose
* of collecting more detailed error messages from an XQC implementation. An XQC_ErrorHandler
* can be set for a query execution using the XQC_StaticContext::set_error_handler() and
* XQC_DynamicContext::set_error_handler() functions.
*
* The XQC_ErrorHandler
* struct has no free() function pointer because the user remains responsible for freeing
* the resources associated with this struct.
*
* \todo file/line/column information?
*/
struct XQC_ErrorHandler_s {
/**
* Can be used for user specific purposes.
*/
void *user_data;
/**
* The function called when an error occurs. The function receives the components of the
* error as arguments. When this function returns, the implementation will exit query preparation or
* execution with the error enumeration value passed as an argument.
*
* \param handler The XQC_ErrorHandler that this function pointer is a member of
* \param error An enumeration value representing the type of error. One of either XQC_STATIC_ERROR,
* XQC_TYPE_ERROR, XQC_DYNAMIC_ERROR, or XQC_SERIALIZATION_ERROR.
* \param error_uri The namespace URI of the error code QName as a UTF-8 string, or 0 if there
* is no namespace URI.
* \param error_localname The local name of the error code QName as a UTF-8 string.
* \param description The description of the error message as a UTF-8 string. The description may be
* absent, in which case this parameter will be 0.
* \param error_object The error object, potentially passed to the <code>fn:error()</code> function.
* The user owns this object, and is responsible for freeing it. The error_object may be absent, in
* which case this parameter will be 0. Some implementations may not provide this functionality,
* meaning that this parameter will always be 0.
*/
void (*error)(XQC_ErrorHandler *handler, XQC_Error error, const char *error_uri,
const char *error_localname, const char *description, XQC_Sequence *error_object);
};
typedef enum {
XQC_EMPTY_TYPE = 0,
XQC_DOCUMENT_TYPE,
XQC_ELEMENT_TYPE,
XQC_ATTRIBUTE_TYPE,
XQC_TEXT_TYPE,
XQC_PROCESSING_INSTRUCTION_TYPE,
XQC_COMMENT_TYPE,
XQC_NAMESPACE_TYPE,
XQC_ANY_SIMPLE_TYPE,
XQC_ANY_URI_TYPE,
XQC_BASE_64_BINARY_TYPE,
XQC_BOOLEAN_TYPE,
XQC_DATE_TYPE,
XQC_DATE_TIME_TYPE,
XQC_DAY_TIME_DURATION_TYPE,
XQC_DECIMAL_TYPE,
XQC_DOUBLE_TYPE,
XQC_DURATION_TYPE,
XQC_FLOAT_TYPE,
XQC_G_DAY_TYPE,
XQC_G_MONTH_TYPE,
XQC_G_MONTH_DAY_TYPE,
XQC_G_YEAR_TYPE,
XQC_G_YEAR_MONTH_TYPE,
XQC_HEX_BINARY_TYPE,
XQC_NOTATION_TYPE,
XQC_QNAME_TYPE,
XQC_STRING_TYPE,
XQC_TIME_TYPE,
XQC_UNTYPED_ATOMIC_TYPE,
XQC_YEAR_MONTH_DURATION_TYPE
} XQC_ItemType;
/**
* The ::XQC_Implementation struct provides factory functions for preparing queries. An XQC_Implementation object
* is thread-safe and can be used by multiple threads of execution at the same time.
*
* The method of creating an
* XQC_Implementation object is beyond the scope of this API, and will typically involve calling an
* implementation defined function. Once created, the user is responsible for freeing the object by calling
* the free() function. The XQC_Implementation object should not be freed before all objects created using it's
* functions have been freed - doing so may cause undefined behaviour.
*/
struct XQC_Implementation_s {
/**
* \name Functions for preparing queries
* @{
*/
/**
* Creates a static context suitable for use in the prepare(), prepare_file() and prepare_stream()
* functions. The user is responsible for freeing the ::XQC_StaticContext object returned by calling
* XQC_StaticContext::free().
*
* \param implementation The XQC_Implementation that this function pointer is a member of
* \param[out] context The newly created XQC_StaticContext object.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error (*create_context)(XQC_Implementation *implementation, XQC_StaticContext **context);
/**
* Prepares a query from a UTF-8 string, returning an ::XQC_Expression object. The user remains responsible
* for closing the file after preparation. The user is responsible for freeing the ::XQC_Expression object
* returned by calling XQC_Expression::free().
*
* \param implementation The XQC_Implementation that this function pointer is a member of.
* \param string The query to prepare as a UTF-8 string.
* \param context The initial static context for this query, or 0 to use the implementation defined
* default static context.
* \param[out] expression The resulting prepared expression.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
* \retval ::XQC_STATIC_ERROR
* \retval ::XQC_TYPE_ERROR
* \retval ::XQC_DYNAMIC_ERROR
*/
XQC_Error (*prepare)(XQC_Implementation *implementation, const char *string,
const XQC_StaticContext *context, XQC_Expression **expression);
/**
* Prepares a query from a FILE pointer, returning an ::XQC_Expression object. The encoding of the
* query in the file is determined by the implementation. The user remains responsible for closing
* the file after preparation. The user is responsible for freeing the ::XQC_Expression object returned by
* calling XQC_Expression::free().
*
* \param implementation The XQC_Implementation that this function pointer is a member of.
* \param file The file containing the query to prepare.
* \param context The initial static context for this query, or 0 to use the implementation defined
* default static context.
* \param[out] expression The resulting prepared expression.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
* \retval ::XQC_UNRECOGNIZED_ENCODING
* \retval ::XQC_STATIC_ERROR
* \retval ::XQC_TYPE_ERROR
* \retval ::XQC_DYNAMIC_ERROR
*/
XQC_Error (*prepare_file)(XQC_Implementation *implementation, FILE *file,
const XQC_StaticContext *context, XQC_Expression **expression);
/**
* Prepares a query from an ::XQC_InputStream, returning an ::XQC_Expression object. The encoding of the stream
* is determined by looking at XQC_InputStream::encoding, or by the implementation if
* XQC_InputStream::encoding is 0.
* The implementation is responsible for freeing the ::XQC_InputStream using the XQC_InputStream::free()
* function after it has finished with using it. The user is responsible for freeing the ::XQC_Expression
* object returned by calling XQC_Expression::free().
*
* \param implementation The XQC_Implementation that this function pointer is a member of
* \param stream The stream returning the query to prepare.
* \param context The initial static context for this query, or 0 to use the implementation defined
* default static context.
* \param[out] expression The resulting prepared expression
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
* \retval ::XQC_UNRECOGNIZED_ENCODING
* \retval ::XQC_STATIC_ERROR
* \retval ::XQC_TYPE_ERROR
* \retval ::XQC_DYNAMIC_ERROR
*/
XQC_Error (*prepare_stream)(XQC_Implementation *implementation, XQC_InputStream *stream,
const XQC_StaticContext *context, XQC_Expression **expression);
/// @}
/**
* \name Functions for parsing documents
* @{
*/
/// XQC_PARSE_ERROR
XQC_Error (*parse_document)(XQC_Implementation *implementation,
const char *string, XQC_Sequence **sequence);
/// XQC_PARSE_ERROR
XQC_Error (*parse_document_file)(XQC_Implementation *implementation,
FILE *file, XQC_Sequence **sequence);
/// XQC_PARSE_ERROR
XQC_Error (*parse_document_stream)(XQC_Implementation *implementation,
XQC_InputStream *stream, XQC_Sequence **sequence);
/// @}
/**
* \name Functions for creating sequences
* @{
*/
XQC_Error (*create_empty_sequence)(XQC_Implementation *implementation,
XQC_Sequence **sequence);
XQC_Error (*create_singleton_sequence)(XQC_Implementation *implementation,
XQC_ItemType type, const char *value,
XQC_Sequence **sequence);
XQC_Error (*create_string_sequence)(XQC_Implementation *implementation,
const char *values[], unsigned int count,
XQC_Sequence **sequence);
XQC_Error (*create_integer_sequence)(XQC_Implementation *implementation,
int values[], unsigned int count,
XQC_Sequence **sequence);
XQC_Error (*create_double_sequence)(XQC_Implementation *implementation,
double values[], unsigned int count,
XQC_Sequence **sequence);
/// @}
/**
* Called to retrieve an implementation specific interface.
*
* \param implementation The XQC_Implementation that this function pointer is a member of
* \param name The name that identifies the interface to return
*
* \return A pointer to the interface, or 0 if the name is not recognized by this
* implementation of XQC.
*/
void *(*get_interface)(const XQC_Implementation *implementation, const char *name);
/**
* Called to free the resources associated with the XQC_Implementation.
*
* \param implementation The XQC_Implementation that this function pointer is a member of
*
*/
void (*free)(XQC_Implementation *implementation);
};
/**
* XPath 1.0 compatibility mode as defined in
* http://www.w3.org/TR/xquery/#static_context
* \todo Are there better enumeration names?
*/
typedef enum { XQC_XPATH2_0, XQC_XPATH1_0 } XQC_XPath1Mode;
/**
* Ordering mode as defined in http://www.w3.org/TR/xquery/#static_context.
*/
typedef enum { XQC_ORDERED, XQC_UNORDERED } XQC_OrderingMode;
/**
* Default order for empty sequences as defined in
* http://www.w3.org/TR/xquery/#static_context.
*/
typedef enum { XQC_EMPTY_GREATEST, XQC_EMPTY_LEAST } XQC_OrderEmptyMode;
/**
* Inherit part of the Copy-namespace mode as defined in
* http://www.w3.org/TR/xquery/#static_context.
*/
typedef enum { XQC_INHERIT_NS, XQC_NO_INHERIT_NS } XQC_InheritMode;
/**
* Preserve part of the Copy-namespace mode as defined in
* http://www.w3.org/TR/xquery/#static_context.
*/
typedef enum { XQC_PRESERVE_NS, XQC_NO_PRESERVE_NS } XQC_PreserveMode;
/**
* Boundary-space policy as defined in http://www.w3.org/TR/xquery/#static_context.
*/
typedef enum { XQC_PRESERVE_SPACE, XQC_STRIP_SPACE } XQC_BoundarySpaceMode;
/**
* Construction mode as defined in http://www.w3.org/TR/xquery/#static_context.
*/
typedef enum { XQC_PRESERVE_CONS, XQC_STRIP_CONS } XQC_ConstructionMode;
/**
* The ::XQC_StaticContext struct provides a way to specify values for the static context of the query to be
* prepared. An ::XQC_StaticContext object is not thread-safe - threads should each use their own instance of a
* ::XQC_StaticContext object.
*
* ::XQC_StaticContext objects are created by calling the XQC_Implementation::create_context() function. Once
* created, the user is responsible for freeing the object by calling
* the free() function. The ::XQC_StaticContext object should be freed before the ::XQC_Implementation object that
* created it.
*/
struct XQC_StaticContext_s {
/**
* Creates a child context of the given static context.
* A child context contains the same information as it's parent context but
* it allows the user to override and add information.
* The user is responsible for freeing the ::XQC_StaticContext object returned by calling
* XQC_StaticContext::free().
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] child_context The newly created XQC_StaticContext object which is
* a child of the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*create_child_context)(XQC_StaticContext *context, XQC_StaticContext **child_context);
/**
* Adds a (prefix, uri) pair to the set of statically known namespaces of
* the given context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param prefix The prefix of the namespace to add to the given XQC_StaticContext.
* \param uri The uri of the namespace to add to the given XQC_StaticContext.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*declare_ns)(XQC_StaticContext *context, const char *prefix, const char *uri);
/**
* Returns the namespace uri that belongs to the given prefix.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param prefix The prefix of the namespace to add to the given XQC_StaticContext.
* \param[out] result_ns The namespace uri of the namespace registered with the given prefix,
* or 0 if none can be found.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_ns_by_prefix)(XQC_StaticContext *context, const char *prefix, const char **result_ns);
/**
* Sets the value of the default namespace for elements and types.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param uri The uri of the default element and type namespace to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_default_element_and_type_ns)(XQC_StaticContext *context, const char *uri);
/**
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] uri The uri of the default element and type namespace that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_default_element_and_type_ns)(XQC_StaticContext *context, const char **uri);
/**
* Sets the default namespace for functions.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param uri The uri of the default function namespace to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_default_function_ns)(XQC_StaticContext *context, const char *uri);
/**
* Returnsthe default namespace for functions set in this static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] uri The uri of the default function namespace that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_default_function_ns)(XQC_StaticContext *context, const char **uri);
/**
* Sets the XPath 1.0 compatibility mode to either XQC_XPATH1_0 or XQC_XPATH2_0.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param mode The XQC_XPath1Mode to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_xpath_compatib_mode)(XQC_StaticContext *context, XQC_XPath1Mode mode);
/**
* Returns the XPath 1.0 compatibility that is set in the given static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] mode The XQC_XPath1Mode that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_xpath_compatib_mode)(XQC_StaticContext *context, XQC_XPath1Mode* mode);
/**
* Sets the construction mode to either XQC_PRESERVE_CONS or XQC_StaticContext.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param mode The XQC_ConstructionMode to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_construction_mode)(XQC_StaticContext *context, XQC_ConstructionMode mode);
/**
* Returns the construction mode that is set in the given static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] mode The XQC_ConstructionMode that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_construction_mode)(XQC_StaticContext *context, XQC_ConstructionMode* mode);
/**
* Sets the ordering mode to either XQC_ORDERED or XQC_UNORDERED.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param mode The XQC_OrderingMode to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_ordering_mode)(XQC_StaticContext *context, XQC_OrderingMode mode);
/**
* Returns the ordering mode that is set in the given static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] mode The XQC_OrderingMode that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_ordering_mode)(XQC_StaticContext *context, XQC_OrderingMode* mode);
/**
* Sets the default order mode for empty sequences to either XQC_EMTPY_LEAST or
* XQC_EMPTY_GREATEST
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param mode The XQC_OrderEmptyMode to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_default_order_empty_sequences)(XQC_StaticContext *context, XQC_OrderEmptyMode mode);
/**
* Returns the default order mode for empty sequences that is set in the given
* static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] mode The XQC_OrderEmptyMode that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_default_order_empty_sequences)(XQC_StaticContext *context, XQC_OrderEmptyMode* mode);
/**
* Sets the boundary space policy to either XQC_PRESERVE_SPACE or XQC_STRIP_SPACE.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param mode The XQC_BoundarySpaceMode to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_boundary_space_policy)(XQC_StaticContext *context, XQC_BoundarySpaceMode mode);
/**
* Returns the boundary space policy that is set in the given static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] mode The XQC_BoundarySpaceMode that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_boundary_space_policy)(XQC_StaticContext *context, XQC_BoundarySpaceMode* mode);
/**
* Sets the copy namespace mode which consists of the preserve and the inherit mode.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param preserve The XQC_PreserveMode to set in the given context.
* \param inherit The XQC_InheritMode to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_copy_ns_mode)(XQC_StaticContext *context, XQC_PreserveMode preserve, XQC_InheritMode inherit);
/**
* Returns the copy namespace mode as a pair consisting of the preserve and the inherit
* mode.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] preserve The XQC_PreserveMode that is set in the given context.
* \param[out] inherit The XQC_InheritMode that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_copy_ns_mode)(XQC_StaticContext *context, XQC_PreserveMode* preserve, XQC_InheritMode* inherit);
/**
* Sets the base uri in the given static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param base_uri The base uri to set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*set_base_uri)(XQC_StaticContext *context, const char *base_uri);
/**
* Returns the base uri that is set in the given static context.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param[out] base_uri The base uri that is set in the given context.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error
(*get_base_uri)(XQC_StaticContext *context, const char **base_uri);
XQC_Error (*set_error_handler)(XQC_StaticContext *context, XQC_ErrorHandler *handler);
XQC_Error (*get_error_handler)(const XQC_StaticContext *context, XQC_ErrorHandler **handler);
/**
* Called to retrieve an implementation specific interface.
*
* \param context The XQC_StaticContext that this function pointer is a member of
* \param name The name that identifies the interface to return
*
* \return A pointer to the interface, or 0 if the name is not recognized by this
* implementation of XQC.
*/
void *(*get_interface)(const XQC_StaticContext *context, const char *name);
/**
* Called to free the resources associated with the XQC_StaticContext.
*
* \param context The XQC_StaticContext that this function pointer is a member of
*
*/
void (*free)(XQC_StaticContext *context);
};
/**
* The ::XQC_Expression struct represents a prepared query, and allows the user to execute that query any
* number of times. An ::XQC_Expression object is thread-safe and can be used by multiple threads of execution
* at the same time.
*
* ::XQC_Expression objects are created by calling the XQC_Implementation::prepare(), XQC_Implementation::prepare_file()
* and XQC_Implementation::prepare_stream() functions. Once created, the user is responsible for freeing the object
* by calling the free() function. The ::XQC_Expression object should be freed before the ::XQC_Implementation object
* that created it.
*
* \todo A way to serialize the query result
* \todo event api?
*/
struct XQC_Expression_s {
/**
* Creates a dynamic context suitable for use in the execute() function.
* The user is responsible for freeing the ::XQC_DynamicContext object returned by calling
* XQC_DynamicContext::free().
*
* \param expression The XQC_Expression that this function pointer is a member of.
* \param[out] context The newly created XQC_DynamicContext object.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*/
XQC_Error (*create_context)(const XQC_Expression *expression, XQC_DynamicContext **context);
/**
* Executes the query represented by the XQC_Expression object using the values in the
* ::XQC_DynamicContext if provided. An ::XQC_Sequence object is returned which can be used to
* examine the results of the query execution. The user is responsible for freeing the
* ::XQC_Sequence object returned by calling XQC_Sequence::free().
*
* \param expression The XQC_Expression that this function pointer is a member of.
* \param context The dynamic context information to use when executing the query, or 0 to
* use the implementation defined default dynamic context.
* \param[out] sequence The newly created XQC_Sequence object.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
* \retval ::XQC_TYPE_ERROR
* \retval ::XQC_DYNAMIC_ERROR
*/
XQC_Error (*execute)(const XQC_Expression *expression, const XQC_DynamicContext *context, XQC_Sequence **sequence);
/**
* Called to retrieve an implementation specific interface.
*
* \param expression The XQC_Expression that this function pointer is a member of.
* \param name The name that identifies the interface to return
*
* \return A pointer to the interface, or 0 if the name is not recognized by this
* implementation of XQC.
*/
void *(*get_interface)(const XQC_Expression *expression, const char *name);
/**
* Called to free the resources associated with the XQC_Expression.
*
* \param expression The XQC_Expression that this function pointer is a member of
*
*/
void (*free)(XQC_Expression *expression);
};
struct XQC_DynamicContext_s {
/**
* Sets the external variable to the value given. The implementation takes ownership
* of the XQC_Sequence passed in, and is responsible for freeing it.
*
* \param context The XQC_DynamicContext that this function pointer is a member of
* \param uri The namespace URI of the external variable to set.
* \param name The name of the external variable to set - this should be a valid lexical <code>xs:QName</code>.
* If <code>uri</code> is 0 and <code>name</code> has a prefix, that prefix is resolved using the in-scope
* namespace prefixes for the expression.
* \param value The XQC_Sequence value for the variable, or 0 to remove the existing
* binding for the variable.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
*
* \todo What happens if the variable value is the wrong type?
* \todo Do we allow the value to come from another implementation?
*/
XQC_Error (*set_variable)(XQC_DynamicContext *context, const char *uri, const char *name,
XQC_Sequence *value);
XQC_Error (*get_variable)(const XQC_DynamicContext *context, const char *uri, const char *name,
XQC_Sequence **value);
/**
* Sets the context item to the current item of the XQC_Sequence given. The user remains
* responsible for freeing the XQC_Sequence passed as the value - the XQC_Sequence must
* not be freed until the XQC_DynamicContext has been freed or it's context item set to
* a different value.
*
* \param context The XQC_DynamicContext that this function pointer is a member of
* \param value The XQC_Sequence value for the context item, or 0 to remove the existing
* context item value.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_INTERNAL_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item in the value.
*
* \todo What happens if the context item value is the wrong type?
* \todo Do we allow the value to come from another implementation?
*/
XQC_Error (*set_context_item)(XQC_DynamicContext *context, XQC_Sequence *value);
XQC_Error (*get_context_item)(const XQC_DynamicContext *context, XQC_Sequence **value);
/**
* The timezone given must be between -840 and +840 minutes (-14 and +14 hours).
*
* \param timezone The implicit timezone to set, as an offset in minutes from GMT
*/
XQC_Error (*set_implicit_timezone)(XQC_DynamicContext *context, int timezone);
XQC_Error (*get_implicit_timezone)(const XQC_DynamicContext *context, int *timezone);
XQC_Error (*set_error_handler)(XQC_DynamicContext *context, XQC_ErrorHandler *handler);
XQC_Error (*get_error_handler)(const XQC_DynamicContext *context, XQC_ErrorHandler **handler);
/**
* Called to retrieve an implementation specific interface.
*
* \param context The XQC_DynamicContext that this function pointer is a member of
* \param name The name that identifies the interface to return
*
* \return A pointer to the interface, or 0 if the name is not recognized by this
* implementation of XQC.
*/
void *(*get_interface)(const XQC_DynamicContext *context, const char *name);
/**
* Called to free the resources associated with the XQC_DynamicContext.
*
* \param context The XQC_DynamicContext that this function pointer is a member of
*
*/
void (*free)(XQC_DynamicContext *context);
};
/**
* \todo other data model node accessors (typed value, parent, attributes, children)?
* \todo accessor for the parts of an xs:QName ?
* \todo serialize a node
* \todo a way to concatenate two sequences?
*/
struct XQC_Sequence_s {
/**
* Moves the XQC_Sequence so that the current item is positioned at the next item in the sequence.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
*
* \retval ::XQC_NO_ERROR when the call is successful
* \retval ::XQC_END_OF_SEQUENCE when the end of the sequence is reached
* \retval ::XQC_TYPE_ERROR
* \retval ::XQC_DYNAMIC_ERROR
*/
XQC_Error (*next)(XQC_Sequence *sequence);
/**
* \name Functions on the current item
* @{
*/
/**
* Returns an item type enumeration for the type of the current item.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param[out] type the XQC_ItemType of the current item
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item, either because next()
* has not been called yet, or because the end of the sequence has been reached.
*/
XQC_Error (*item_type)(const XQC_Sequence *sequence, XQC_ItemType *type);
/**
* Returns the type name for the current item as a (URI, localname) pair.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param[out] uri The URI of the type of the current item. The memory for the string will be valid
* until a subsequent call to XQC_Sequence::next().
* \param[out] name The localname of the type of the current item. The memory for the string will be valid
* until a subsequent call to XQC_Sequence::next().
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item, either because next()
* has not been called yet, or because the end of the sequence has been reached.
*/
XQC_Error (*type_name)(const XQC_Sequence *sequence, const char **uri, const char **name);
/**
* Returns the string value of the current item in the sequence - this is equivalent to calling
* <code>fn:string()</code> (http://www.w3.org/TR/xpath-functions/#func-string) on the current item.
* This is available for all item types.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param[out] value The string value of the current item. The memory for the string will be valid
* until a subsequent call to XQC_Sequence::next().
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item, either because next()
* has not been called yet, or because the end of the sequence has been reached.
*/
XQC_Error (*string_value)(const XQC_Sequence *sequence, const char **value);
/**
* Returns the value of the current item in the sequence as an integer - this is equivalent to calling
* <code>fn:number()</code> (http://www.w3.org/TR/xpath-functions/#func-number) on the current item, and
* casting the result to an int. This is available for all item types.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param[out] value The value of the current item as an int.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item, either because next()
* has not been called yet, or because the end of the sequence has been reached.
*/
XQC_Error (*integer_value)(const XQC_Sequence *sequence, int *value);
/**
* Returns the value of the current item in the sequence as a double - this is equivalent to calling
* <code>fn:number()</code> (http://www.w3.org/TR/xpath-functions/#func-number) on the current item.
* This is available for all item types.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param[out] value The value of the current item as a double.
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item, either because next()
* has not been called yet, or because the end of the sequence has been reached.
*/
XQC_Error (*double_value)(const XQC_Sequence *sequence, double *value);
/**
* Returns the name for the current node as a (URI, localname) pair.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param[out] uri The URI of the name of the current node. The memory for the string will be valid
* until a subsequent call to XQC_Sequence::next().
* \param[out] name The localname of the name of the current node. The memory for the string will be valid
* until a subsequent call to XQC_Sequence::next().
*
* \retval ::XQC_NO_ERROR
* \retval ::XQC_NO_CURRENT_ITEM if there is no current item, either because next()
* has not been called yet, or because the end of the sequence has been reached.
* \retval ::XQC_NOT_NODE if the current item is not a node.
*/
XQC_Error (*node_name)(const XQC_Sequence *sequence, const char **uri, const char **name);
/** @} */
/**
* Called to retrieve an implementation specific interface.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
* \param name The name that identifies the interface to return
*
* \return A pointer to the interface, or 0 if the name is not recognized by this
* implementation of XQC.
*/
void *(*get_interface)(const XQC_Sequence *sequence, const char *name);
/**
* Called to free the resources associated with the XQC_Sequence.
*
* \param sequence The XQC_Sequence that this function pointer is a member of
*
*/
void (*free)(XQC_Sequence *sequence);
};
#ifdef __cplusplus
}
#endif
#endif
Reference in a new issue View git blame Copy permalink