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 zorba_implementation::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_Error::XQC_NO_ERROR 00060 * \retval XQC_INVALID_ARGUMENT 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_Error::XQC_NO_ERROR 00086 * \retval err::XQST0038 00087 * \retval XQC_Error::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_Error::XQC_NO_ERROR 00101 * \retval err::XQST0038 00102 * \retval XQC_Error::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_Error::XQC_NO_ERROR 00124 * \retval XQC_Error::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_Error::XQC_NO_ERROR 00137 * \retval XQC_Error::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_Error::XQC_NO_ERROR 00157 * \retval XQC_INVALID_ARGUMENT, 00158 * \retval XQC_Error::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: */