zorbac.h
Go to the documentation of this file.
00001 /*
00002  * Copyright 2006-2008 The FLWOR Foundation.
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  * 
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */ 
00016 #ifndef ZORBA_ZORBAC_API_H
00017 #define ZORBA_ZORBAC_API_H
00018 
00019 
00020 #include <stdio.h>
00021 #include <zorba/config.h>
00022 #include <xqc.h>
00023 
00024 typedef struct Zorba_StaticContext_s Zorba_StaticContext;
00025 
00026 typedef struct Zorba_ItemSetter_s Zorba_ItemSetter;
00027 
00028 typedef struct Zorba_OutputStream_s Zorba_OutputStream;
00029 
00030 typedef struct Zorba_ErrorHandler_s Zorba_ErrorHandler;
00031 
00032 
00033 // external functions
00034 typedef void (*external_function_init)
00035 (void** user_data, void* function_user_data);
00036 
00037 typedef XQC_Error (*external_function_next)
00038 (XQC_Sequence** args, unsigned int argc, Zorba_ItemSetter* setter,
00039   void* user_data, void* function_user_data);
00040 
00041 typedef void (*external_function_free)
00042 (void* user_data, void* function_user_data);
00043 
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif
00048 
00049   /**
00050    * The zorba_implementation function creates a new ::XQC_Implementation object.
00051    * Thereby, the Zorba processor is initialized.
00052    * The user is responsible for freeing the object by calling the free() function
00053    * of the XQC_Implementation struct.
00054    *
00055    * \param store A pointer to the store that is being used by the Zorba instance that is created
00056    *              by this call.
00057    * \param[out] impl The newly created XQC_Implementation object.
00058    *
00059    * \retval ::XQC_NO_ERROR
00060    * \retval ::ZXQP0019_INTERNAL_ERROR
00061    */
00062   ZORBA_DLL_PUBLIC XQC_Error
00063   zorba_implementation(XQC_Implementation **impl, void* store);
00064 
00065 
00066   struct Zorba_StaticContext_s {
00067     /**
00068      * Add a collation URI.
00069      * The URI specifies the locale and collation strength of the collation that is added.
00070      * A valid collation URI must begin with http://www.flworfound.org/collations/.
00071      * This prefix is followed by a collation strength (i.e. PRIMARY, SECONDARY, TERTIARY,
00072      * QUATTERNARY, or IDENTICAL) followed by a '/'.
00073      * After the strength a lower-case two- or three-letter ISO-639 language code must follow.
00074      * The URI may end with an upper-case two-letter ISO-3166.
00075      * For example, http://www.flworfound.org/collations/PRIMARY/en/US
00076      * specifies an english language with US begin the country..
00077      *
00078      * Internally, ICU is used for comparing strings. For detailed description see
00079      * http://www.icu-project.org/apiref/icu4c/classCollator.html
00080      * and http://www.icu-project.org/apiref/icu4c/classLocale.html
00081      * 
00082      * \param context The XQC_StaticContext that this function pointer is a member of
00083      * \param uri The URI of the collation to add.
00084      *
00085      * \retval ::XQC_NO_ERROR
00086      * \retval ::XQST0038
00087      * \retval ::XQC_INTERNAL_ERROR
00088      */
00089       // TODO add collation test cases
00090     XQC_Error
00091     (*add_collation)(Zorba_StaticContext *context, const char* uri);
00092 
00093     /** 
00094      * Set the URI of the default collation.
00095      * (see http://www.w3.org/TR/xquery/#static_context)
00096      *
00097      * \param context The XQC_StaticContext that this function pointer is a member of
00098      * \param uri The URI of the default collation to set
00099      *
00100      * \retval ::XQC_NO_ERROR
00101      * \retval ::XQST0038
00102      * \retval ::XQC_INTERNAL_ERROR
00103      */
00104     XQC_Error
00105     (*set_default_collation)(Zorba_StaticContext *context, const char* uri);
00106 
00107     /** 
00108      * Get the URI of the default collation. The uri returned is valid
00109      * as long as the corresponding XQC_StaticContext object is valid.
00110      *
00111      * \param context The XQC_StaticContext that this function pointer is a member of
00112      * \param[out] uri The URI of the default collation that is currently set in the given context.
00113      */
00114     XQC_Error
00115     (*get_default_collation)(Zorba_StaticContext *context, const char** uri);
00116 
00117     /**
00118      * Sets the XQuery processor's version to either xquery_version_1_0 or xquery_version_3_0.
00119      *
00120      * \param context The XQC_StaticContext that this function pointer is a member of
00121      * \param mode The xquery_version_t to set in the given context.
00122      *
00123      * \retval ::XQC_NO_ERROR
00124      * \retval ::XQC_INTERNAL_ERROR
00125      */
00126       // TODO add xquery version test cases
00127     XQC_Error
00128     (*set_xquery_version)(Zorba_StaticContext* context, XQC_XQueryVersion ver);
00129 
00130     /**
00131      * Returns the XQuery processor's version that is set in the given static context.
00132      *
00133      * \param context The XQC_StaticContext that this function pointer is a member of
00134      * \param[out] mode The xquery_version_t that is set in the given context.
00135      *
00136      * \retval ::XQC_NO_ERROR
00137      * \retval ::XQC_INTERNAL_ERROR
00138      */
00139     XQC_Error 
00140     (*get_xquery_version)(Zorba_StaticContext* context, XQC_XQueryVersion* ver);
00141  
00142     /**
00143      * Register an external function that can be called within a query.
00144      * One external function consists of three function parameters, i.e. init, next, and release.
00145      *
00146      * \param context The XQC_StaticContext that this function pointer is a member of
00147      * \param uri The URI of the external function to add.
00148      * \param localname The localname of the function to add.
00149      * \param init A callback function pointer that is called once when the external function
00150      *             is initialized. The init function gets the global_user_data pointer
00151      *             as parameter.
00152      * \param release A callback function pointer that is called once when the external function
00153      *                is deinitialized.
00154      * \param global_user_data User specific data that is passed to the init function as a parameter.
00155      *
00156      * \retval ::XQC_NO_ERROR
00157      * \retval ::ZAPI0019_FUNCTION_ALREADY_REGISTERED,
00158      * \retval ::XQC_INTERNAL_ERROR
00159      */
00160     XQC_Error
00161     (*register_external_function)(Zorba_StaticContext* context, 
00162       const char* uri, const char* localname, external_function_init init_fn,
00163       external_function_next next_fn, external_function_free free_fn,
00164       void* global_user_data);
00165   };
00166 
00167   /**
00168    * ::Zorba_ItemSetter is designed to allow external functions to set the
00169    * next XQuery data model item to be returned.
00170    */
00171   struct Zorba_ItemSetter_s
00172   {
00173       /**
00174        * Call this to specify the next item as a string. The Zorba
00175        * implementation will take ownership of the char* and free it
00176        * at an appropriate time.
00177        * QQQ is this true?
00178        */
00179       XQC_Error
00180       (*set_string)(Zorba_ItemSetter* setter, const char* value);
00181 
00182       /**
00183        * Call this to specify the next item as an integer.
00184        */
00185       XQC_Error
00186       (*set_integer)(Zorba_ItemSetter* setter, int value);
00187 
00188       /**
00189        * Call this to specify the next item as a double.
00190        */
00191       XQC_Error
00192       (*set_double)(Zorba_ItemSetter* setter, double value);
00193 
00194       /**
00195        * Call this to specify the next item as an arbitrary type,
00196        * providing the value as a string.
00197        */
00198       XQC_Error
00199       (*set_typed_value)(Zorba_ItemSetter* setter, XQC_ItemType type,
00200         const char* value);
00201   };
00202 
00203   /**
00204    * The ::Zorba_OutputStream struct is designed to be passed to an XQC implementation in order
00205    * to return streaming data (i.e. the result of a query).
00206    */
00207   struct Zorba_OutputStream_s
00208   {
00209     /**
00210      * The function is called to provide the streaming result of a query
00211      * in the buffer provided. 
00212      *
00213      * \param stream The Zorba_OutputStream that this function pointer is a member of
00214      * \param buf The buffer that contains the data
00215      * \param length The length of the contents in the buffer
00216      */
00217     void
00218     (*write)(Zorba_OutputStream stream, const char* buf, unsigned int length);
00219 
00220     /**
00221      * Called to free the resources associated with the Zorba_OutputStream.
00222      * Free is called by the implementation if it finished writing to the stream.
00223      * 
00224      * \param stream The Zorba_OutputStream that this function pointer is a member of
00225      *
00226      */
00227     void 
00228     (*free)(Zorba_OutputStream stream);
00229 
00230     /**
00231      * Can be used for user specific purposes.
00232      */
00233     void* user_data;
00234   };
00235 
00236 
00237   struct Zorba_ErrorHandler_s {
00238 
00239     void (*error)(Zorba_ErrorHandler* handler, 
00240                   XQC_Error error,
00241                   const char   *local_name,
00242                   const char   *description,
00243                   const char   *query_uri,
00244                   unsigned int line,
00245                   unsigned int column);
00246 
00247     /**
00248      * Can be used for user specific purposes.
00249      */
00250     void *user_data;
00251 
00252   };
00253 
00254 #ifdef __cplusplus
00255 }
00256 #endif
00257 
00258 #endif
00259 /* vim:set et sw=2 ts=2: */
blog comments powered by Disqus