zorbac.h
Go to the documentation of this file.
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 
25 
27 
29 
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 
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
162  const char* uri, const char* localname, external_function_init init_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  */
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  */
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
229 
230  /**
231  * Can be used for user specific purposes.
232  */
233  void* user_data;
234  };
235 
236 
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: */