1 /* 2 * Copyright 2006-2008 The FLWOR Foundation. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 #ifndef ZORBA_ZORBAC_API_H 17 #define ZORBA_ZORBAC_API_H 18 19 20 #include <stdio.h> 21 #include <zorba/config.h> 22 #include <xqc.h> 23 24 typedef struct Zorba_StaticContext_s Zorba_StaticContext; 25 26 typedef struct Zorba_ItemSetter_s Zorba_ItemSetter; 27 28 typedef struct Zorba_OutputStream_s Zorba_OutputStream; 29 30 typedef struct Zorba_ErrorHandler_s Zorba_ErrorHandler; 31 32 33 // external functions 34 typedef void (*external_function_init) 35 (void** user_data, void* function_user_data); 36 37 typedef XQC_Error (*external_function_next) 38 (XQC_Sequence** args, unsigned int argc, Zorba_ItemSetter* setter, 39 void* user_data, void* function_user_data); 40 41 typedef void (*external_function_free) 42 (void* user_data, void* function_user_data); 43 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * The zorba_implementation function creates a new zorba_implementation::XQC_Implementation object. 51 * Thereby, the Zorba processor is initialized. 52 * The user is responsible for freeing the object by calling the free() function 53 * of the XQC_Implementation struct. 54 * 55 * \param store A pointer to the store that is being used by the Zorba instance that is created 56 * by this call. 57 * \param[out] impl The newly created XQC_Implementation object. 58 * 59 * \retval XQC_Error::XQC_NO_ERROR 60 * \retval XQC_INVALID_ARGUMENT 61 */ 62 ZORBA_DLL_PUBLIC XQC_Error 63 zorba_implementation(XQC_Implementation **impl, void* store); 64 65 66 struct Zorba_StaticContext_s { 67 /** 68 * Add a collation URI. 69 * The URI specifies the locale and collation strength of the collation that is added. 70 * A valid collation URI must begin with http://www.flworfound.org/collations/. 71 * This prefix is followed by a collation strength (i.e. PRIMARY, SECONDARY, TERTIARY, 72 * QUATTERNARY, or IDENTICAL) followed by a '/'. 73 * After the strength a lower-case two- or three-letter ISO-639 language code must follow. 74 * The URI may end with an upper-case two-letter ISO-3166. 75 * For example, http://www.flworfound.org/collations/PRIMARY/en/US 76 * specifies an english language with US begin the country.. 77 * 78 * Internally, ICU is used for comparing strings. For detailed description see 79 * http://www.icu-project.org/apiref/icu4c/classCollator.html 80 * and http://www.icu-project.org/apiref/icu4c/classLocale.html 81 * 82 * \param context The XQC_StaticContext that this function pointer is a member of 83 * \param uri The URI of the collation to add. 84 * 85 * \retval XQC_Error::XQC_NO_ERROR 86 * \retval err::XQST0038 87 * \retval XQC_Error::XQC_INTERNAL_ERROR 88 */ 89 // TODO add collation test cases 90 XQC_Error 91 (*add_collation)(Zorba_StaticContext *context, const char* uri); 92 93 /** 94 * Set the URI of the default collation. 95 * (see http://www.w3.org/TR/xquery/#static_context) 96 * 97 * \param context The XQC_StaticContext that this function pointer is a member of 98 * \param uri The URI of the default collation to set 99 * 100 * \retval XQC_Error::XQC_NO_ERROR 101 * \retval err::XQST0038 102 * \retval XQC_Error::XQC_INTERNAL_ERROR 103 */ 104 XQC_Error 105 (*set_default_collation)(Zorba_StaticContext *context, const char* uri); 106 107 /** 108 * Get the URI of the default collation. The uri returned is valid 109 * as long as the corresponding XQC_StaticContext object is valid. 110 * 111 * \param context The XQC_StaticContext that this function pointer is a member of 112 * \param[out] uri The URI of the default collation that is currently set in the given context. 113 */ 114 XQC_Error 115 (*get_default_collation)(Zorba_StaticContext *context, const char** uri); 116 117 /** 118 * Sets the XQuery processor's version to either xquery_version_1_0 or xquery_version_3_0. 119 * 120 * \param context The XQC_StaticContext that this function pointer is a member of 121 * \param mode The xquery_version_t to set in the given context. 122 * 123 * \retval XQC_Error::XQC_NO_ERROR 124 * \retval XQC_Error::XQC_INTERNAL_ERROR 125 */ 126 // TODO add xquery version test cases 127 XQC_Error 128 (*set_xquery_version)(Zorba_StaticContext* context, XQC_XQueryVersion ver); 129 130 /** 131 * Returns the XQuery processor's version that is set in the given static context. 132 * 133 * \param context The XQC_StaticContext that this function pointer is a member of 134 * \param[out] mode The xquery_version_t that is set in the given context. 135 * 136 * \retval XQC_Error::XQC_NO_ERROR 137 * \retval XQC_Error::XQC_INTERNAL_ERROR 138 */ 139 XQC_Error 140 (*get_xquery_version)(Zorba_StaticContext* context, XQC_XQueryVersion* ver); 141 142 /** 143 * Register an external function that can be called within a query. 144 * One external function consists of three function parameters, i.e. init, next, and release. 145 * 146 * \param context The XQC_StaticContext that this function pointer is a member of 147 * \param uri The URI of the external function to add. 148 * \param localname The localname of the function to add. 149 * \param init A callback function pointer that is called once when the external function 150 * is initialized. The init function gets the global_user_data pointer 151 * as parameter. 152 * \param release A callback function pointer that is called once when the external function 153 * is deinitialized. 154 * \param global_user_data User specific data that is passed to the init function as a parameter. 155 * 156 * \retval XQC_Error::XQC_NO_ERROR 157 * \retval XQC_INVALID_ARGUMENT, 158 * \retval XQC_Error::XQC_INTERNAL_ERROR 159 */ 160 XQC_Error 161 (*register_external_function)(Zorba_StaticContext* context, 162 const char* uri, const char* localname, external_function_init init_fn, 163 external_function_next next_fn, external_function_free free_fn, 164 void* global_user_data); 165 }; 166 167 /** 168 * ::Zorba_ItemSetter is designed to allow external functions to set the 169 * next XQuery data model item to be returned. 170 */ 171 struct Zorba_ItemSetter_s 172 { 173 /** 174 * Call this to specify the next item as a string. The Zorba 175 * implementation will take ownership of the char* and free it 176 * at an appropriate time. 177 * QQQ is this true? 178 */ 179 XQC_Error 180 (*set_string)(Zorba_ItemSetter* setter, const char* value); 181 182 /** 183 * Call this to specify the next item as an integer. 184 */ 185 XQC_Error 186 (*set_integer)(Zorba_ItemSetter* setter, int value); 187 188 /** 189 * Call this to specify the next item as a double. 190 */ 191 XQC_Error 192 (*set_double)(Zorba_ItemSetter* setter, double value); 193 194 /** 195 * Call this to specify the next item as an arbitrary type, 196 * providing the value as a string. 197 */ 198 XQC_Error 199 (*set_typed_value)(Zorba_ItemSetter* setter, XQC_ItemType type, 200 const char* value); 201 }; 202 203 /** 204 * The ::Zorba_OutputStream struct is designed to be passed to an XQC implementation in order 205 * to return streaming data (i.e. the result of a query). 206 */ 207 struct Zorba_OutputStream_s 208 { 209 /** 210 * The function is called to provide the streaming result of a query 211 * in the buffer provided. 212 * 213 * \param stream The Zorba_OutputStream that this function pointer is a member of 214 * \param buf The buffer that contains the data 215 * \param length The length of the contents in the buffer 216 */ 217 void 218 (*write)(Zorba_OutputStream stream, const char* buf, unsigned int length); 219 220 /** 221 * Called to free the resources associated with the Zorba_OutputStream. 222 * Free is called by the implementation if it finished writing to the stream. 223 * 224 * \param stream The Zorba_OutputStream that this function pointer is a member of 225 * 226 */ 227 void 228 (*free)(Zorba_OutputStream stream); 229 230 /** 231 * Can be used for user specific purposes. 232 */ 233 void* user_data; 234 }; 235 236 237 struct Zorba_ErrorHandler_s { 238 239 void (*error)(Zorba_ErrorHandler* handler, 240 XQC_Error error, 241 const char *local_name, 242 const char *description, 243 const char *query_uri, 244 unsigned int line, 245 unsigned int column); 246 247 /** 248 * Can be used for user specific purposes. 249 */ 250 void *user_data; 251 252 }; 253 254 #ifdef __cplusplus 255 } 256 #endif 257 258 #endif 259 /* vim:set et sw=2 ts=2: */ 260