# guththila.h

    00001
    00002 /*
    00003  * Licensed to the Apache Software Foundation (ASF) under one or more
    00004  * contributor license agreements.  See the NOTICE file distributed with
    00005  * this work for additional information regarding copyright ownership.
    00006  * The ASF licenses this file to You under the Apache License, Version 2.0
    00007  * (the "License"); you may not use this file except in compliance with
    00008  * the License.  You may obtain a copy of the License at
    00009  *
    00010  *      http://www.apache.org/licenses/LICENSE-2.0
    00011  *
    00012  * Unless required by applicable law or agreed to in writing, software
    00013  * distributed under the License is distributed on an "AS IS" BASIS,
    00014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    00015  * See the License for the specific language governing permissions and
    00016  * limitations under the License.
    00017  */
    00018 #ifndef GUTHTHILA_H
    00019 #define GUTHTHILA_H
    00020
    00021 #include <guththila_defines.h>
    00022 #include <guththila_token.h>
    00023 #include <guththila_reader.h>
    00024 #include <guththila_xml_writer.h>
    00025 #include <guththila_attribute.h>
    00026 #include <guththila_namespace.h>
    00027 #include <guththila_buffer.h>
    00028 #include <guththila_stack.h>
    00029 #include <guththila_error.h>
    00030
    00031 #include <axutil_utils.h>
    00032
    00033 /*
    00034 All the functions in this library does not check weather the given arguments are NULL.
    00035 It is the responsblity of the user to check weather the arguments contain NULL values.
    00036 */
    00037 EXTERN_C_START()
    00038
    00039 enum guththila_status
    00040 {
    00041     S_0 = 0,
    00042         S_1,
    00043         S_2,
    00044         S_3
    00045 };
    00046
    00047 enum guththila_UTF16_endianess
    00048 {
    00049     None = 1,
    00050         LE,
    00051         BE
    00052 };
    00053
    00054 typedef enum guththila_type
    00055 {
    00056     type_file_name = 0,
    00057         type_memory_buffer,
    00058         type_reader,
    00059         type_io
    00060 } guththila_type_t;
    00061
    00062 enum guththila_event_types
    00063 {
    00064     GUTHTHILA_START_DOCUMENT =0,
    00065         GUTHTHILA_END_ELEMENT,
    00066         GUTHTHILA_CHARACTER,
    00067     GUTHTHILA_ENTITY_REFERANCE,
    00068         GUTHTHILA_COMMENT,
    00069     GUTHTHILA_SPACE,
    00070         GUTHTHILA_START_ELEMENT,
    00071     GUTHTHILA_EMPTY_ELEMENT
    00072 };
    00073
    00074 typedef struct guththila_s
    00075 {
    00076     guththila_tok_list_t tokens; /* Token cache */
    00077
    00078     guththila_buffer_t buffer;  /* Holding incoming xml string */
    00079
    00080     guththila_reader_t *reader; /* Reading the data */
    00081
    00082     guththila_token_t *prefix; /* Prefix of the xml element */
    00083
    00084     guththila_token_t *name; /* xml element local name */
    00085
    00086     guththila_token_t *value; /* text of a xml element */
    00087
    00088     guththila_stack_t elem; /* elements are put in a stack */
    00089
    00090     guththila_stack_t attrib; /* Attributes are put in a stack */
    00091
    00092     guththila_stack_t namesp; /* namespaces are put in a stack */
    00093
    00094     int status;
    00095
    00096     int guththila_event; /* Current event */
    00097
    00098     size_t next;    /* Keep track of the position in the xml string */
    00099
    00100     int last_start; /* Keep track of the starting position of the last token */
    00101
    00102     guththila_token_t *temp_prefix; /* Temporery location for prefixes */
    00103
    00104     guththila_token_t *temp_name;   /* Temporery location for names */
    00105
    00106     guththila_token_t *temp_tok;   /* We don't know this until we close it */
    00107 } guththila_t;
    00108
    00109 /*
    00110  * An element will contain one of these things if it has namespaces
    00111  * */
    00112 typedef struct guththila_elem_namesp_s
    00113 {
    00114     guththila_namespace_t *namesp; /* Array of namespaces */
    00115     int no;                        /*Number of namespace in the element */
    00116     int size;                      /* Allocated size */
    00117 } guththila_elem_namesp_t;
    00118
    00119 /*
    00120  * Element.
    00121  */
    00122 typedef struct guththila_element_s
    00123 {
    00124     guththila_token_t *name;    /* local name */
    00125
    00126     guththila_token_t *prefix;  /* prefix */
    00127
    00128         int is_namesp;              /* Positive if a namespace is present */
    00129 } guththila_element_t;
    00130
    00131 /* Initialize the parser */
    00132 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00133 guththila_init(guththila_t * m, void *reader,
    00134                            const axutil_env_t * env);
    00135
    00136 /* Uninitialize the parser */
    00137 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00138 guththila_un_init(guththila_t * m, const axutil_env_t * env);
    00139
    00140 /* Still not used */
    00141 typedef void(GUTHTHILA_CALL * guththila_error_func)(void *arg,
    00142                                                                                                         const guththila_char_t *msg,
    00143                                                                                                         guththila_error_level level,
    00144                                                                                                         void *locator);
    00145
    00146 /*
    00147  * Parse the xml and return an event. If something went wrong it will return -1.
    00148  * The events are of the type guththila_event_types. According to the event
    00149  * user can get the required information using the appriate functions.
    00150  * @param g pointer to a guththila_t structure
    00151  * @param env the environment
    00152  */
    00153 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00154 guththila_next(guththila_t * g, const axutil_env_t * env);
    00155
    00156 /*
    00157  * Return the number of attributes in the current element.
    00158  * @param g pointer to a guththila_t structure
    00159  * @param env the environment
    00160  */
    00161 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00162 guththila_get_attribute_count(guththila_t * g, const axutil_env_t * env);
    00163
    00164 /*
    00165  * Return the attribute name.
    00166  * @param g pointer to a guththila_t structure
    00167  * @param att pointer to a attribute
    00168  * @param env the environment
    00169  */
    00170 GUTHTHILA_EXPORT guththila_char_t * GUTHTHILA_CALL
    00171 guththila_get_attribute_name(guththila_t * g, guththila_attr_t * att,
    00172                                                          const axutil_env_t * env);
    00173
    00174 /*
    00175  * Return the attribute value.
    00176  * @param g pointer to a guththila_t structure
    00177  * @param att pointer to a attribute
    00178  * @param env the environment
    00179  */
    00180 GUTHTHILA_EXPORT guththila_char_t * GUTHTHILA_CALL
    00181 guththila_get_attribute_value(guththila_t * g,
    00182                                                           guththila_attr_t * att,
    00183                                                           const axutil_env_t * env);
    00184
    00185 /*
    00186  * Return the attribute prefix.
    00187  * @param g pointer to a guththila_t structure
    00188  * @param att pointer to a attribute
    00189  * @param env the environment
    00190  */
    00191 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00192 guththila_get_attribute_prefix(guththila_t * g,
    00193                                                            guththila_attr_t * att,
    00194                                                            const axutil_env_t * env);
    00195
    00196 /*
    00197  * Return the attribute
    00198  * @param g pointer to a guththila_t structure
    00199  * @param env the environment
    00200  */
    00201 GUTHTHILA_EXPORT guththila_attr_t *GUTHTHILA_CALL
    00202 guththila_get_attribute(guththila_t * g, const axutil_env_t * env);
    00203
    00204 /*
    00205  * Return the name of the attribute by the attribute bumber.
    00206  * First attribute will be 1.
    00207  * @param g pointer to a guththila_t structure
    00208  * @param index position of the attribute
    00209  * @param env the environment
    00210  */
    00211 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00212 guththila_get_attribute_name_by_number(guththila_t * g, int index,
    00213                                                                            const axutil_env_t *env);
    00214
    00215 /*
    00216  * Return the attribute value by number.
    00217  * First attribute will be 1.
    00218  * @param g pointer to a guththila_t structure
    00219  * @param index position of the attribute
    00220  * @param env the environment
    00221  */
    00222 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00223 guththila_get_attribute_value_by_number(guththila_t * g, int index,
    00224                                                                                 const axutil_env_t *env);
    00225
    00226 /*
    00227  * Return the prefix of the attribute.
    00228  * First attribute will be 1.
    00229  * @param g pointer to a guththila_t structure
    00230  * @param index position of the attribute
    00231  * @param env the environment
    00232  */
    00233 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00234 guththila_get_attribute_prefix_by_number(guththila_t * g, int index,
    00235                                                                                  const axutil_env_t *env);
    00236
    00237 /*
    00238  * Return the name of the element.
    00239  * @param g pointer to a guththila_t structure
    00240  * @param env the environment
    00241  */
    00242 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00243 guththila_get_name(guththila_t * g, const axutil_env_t * env);
    00244
    00245 /*
    00246  * Return the prefix of the element.
    00247  * @param g pointer to a guththila_t structure
    00248  * @param env the environment
    00249  */
    00250 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00251 guththila_get_prefix(guththila_t * g, const axutil_env_t * env);
    00252
    00253 /*
    00254  * Return the text of the element.
    00255  * @param g pointer to a guththila_t structure
    00256  * @param env the environment
    00257  */
    00258 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00259 guththila_get_value(guththila_t * g, const axutil_env_t * env);
    00260
    00261 /*
    00262  * Return the namespace of the element.
    00263  * @param g pointer to a guththila_t structure
    00264  * @param env the environment
    00265  */
    00266 GUTHTHILA_EXPORT guththila_namespace_t *GUTHTHILA_CALL
    00267 guththila_get_namespace(guththila_t * g, const axutil_env_t * env);
    00268
    00269 /*
    00270  * Return the number of namespaces in the element.
    00271  * @param g pointer to a guththila_t structure
    00272  * @param env the environment
    00273  */
    00274 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00275 guththila_get_namespace_count(guththila_t * g, const axutil_env_t * env);
    00276
    00277 /*
    00278  * Return the namespace uri of the given namespace.
    00279  * @param g pointer to a guththila_t structure
    00280  * @param ns pointer to a namespace
    00281  * @param env the environment
    00282  */
    00283 GUTHTHILA_EXPORT guththila_char_t * GUTHTHILA_CALL
    00284 guththila_get_namespace_uri(guththila_t * g, guththila_namespace_t * ns,
    00285                                                         const axutil_env_t * env);
    00286
    00287 /*
    00288  * Return the prefix of the namespace.
    00289  * @param g pointer to a guththila_t structure
    00290  * @param ns pointer to a namespace
    00291  * @param env the environment
    00292  */
    00293 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00294 guththila_get_namespace_prefix(guththila_t * p, guththila_namespace_t * ns,
    00295                                                            const axutil_env_t * env);
    00296
    00297 /*
    00298  * Return the prefix of the namespace at the given position.
    00299  * First namespace will have the value 1.
    00300  * @param g pointer to a guththila_t structure
    00301  * @param index position of the namespace
    00302  * @param env the environment
    00303  */
    00304 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00305 guththila_get_namespace_prefix_by_number(guththila_t * g, int index,
    00306                                                                                  const axutil_env_t *env);
    00307
    00308 /*
    00309  * Get the uri of the namespace at the given position.
    00310  * First namespace will have the value 1.
    00311  * @param g pointer to a guththila_t structure
    00312  * @param index position of the namespace
    00313  * @param env the environment
    00314  */
    00315 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00316 guththila_get_namespace_uri_by_number(guththila_t * g, int index,
    00317                                                                           const axutil_env_t *env);
    00318
    00319 /*
    00320  * Get the attribute namespace of the attribute at the given position.
    00321  * @param g pointer to a guththila_t structure
    00322  * @param index position of the namespace
    00323  * @param env the environment
    00324  */
    00325 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00326 guththila_get_attribute_namespace_by_number(guththila_t *g, int index,
    00327                                                                                         const axutil_env_t *env);
    00328
    00329 /*
    00330  * Get the encoding. at the moment we don't support UNICODE
    00331  * @param g pointer to a guththila_t structure
    00332  * @param env the environment
    00333  */
    00334 GUTHTHILA_EXPORT guththila_char_t *GUTHTHILA_CALL
    00335 guththila_get_encoding(guththila_t * p, const axutil_env_t * env);
    00336
    00337 /*
    00338  * To do. Implement a proper error handling mechanism.
    00339  * @param g pointer to a guththila_t structure
    00340  * @param env the environment
    00341  */
    00342 GUTHTHILA_EXPORT void GUTHTHILA_CALL
    00343 guththila_set_error_handler(guththila_t * m, guththila_error_func,
    00344                                                         const axutil_env_t * env);
    00345 EXTERN_C_END()
    00346 #endif
    00347