# guththila_xml_writer.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_XML_WRITER_H
    00019 #define GUTHTHILA_XML_WRITER_H
    00020
    00021 #include <guththila_token.h>
    00022 #include <guththila_defines.h>
    00023 #include <guththila_buffer.h>
    00024 #include <guththila.h>
    00025 #include <axutil_utils.h>
    00026
    00027 EXTERN_C_START()
    00028 #define GUTHTHILA_XML_WRITER_TOKEN
    00029
    00030 /*
    00031 Design notes:-
    00032 namesp member of guththila_xml_writer_s is populated with malloc created objects.
    00033 Providing a list for this seems expensive because most of the times only few
    00034 namespaces are present in a XML document.
    00035
    00036 element member of guththila_xml_writer_s must be povided the list capablity. This
    00037 is particularly important in very deep XML documents.
    00038 */
    00039 typedef enum guththila_writer_type_s
    00040 {
    00041     GUTHTHILA_WRITER_FILE = 1,
    00042     GUTHTHILA_WRITER_MEMORY
    00043 } guththila_writer_type_t;
    00044
    00045 typedef struct guththila_writer_s
    00046 {
    00047     short type;
    00048     FILE *out_stream;
    00049     guththila_buffer_t *buffer;
    00050     int next;
    00051 }
    00052 guththila_writer_t;
    00053
    00054 typedef enum guththila_writer_status_s
    00055 {
    00056     /*Started writing a non empty element */
    00057     START = 1,
    00058     /*Started writing a empty element */
    00059     START_EMPTY,
    00060     /*We are in a position to begin wrting an element */
    00061     BEGINING
    00062 } guththila_writer_status_t;
    00063
    00064 /*Main structure which provides the writer capability*/
    00065 typedef struct guththila_xml_writer_s
    00066 {
    00067     guththila_stack_t element;
    00068     guththila_stack_t namesp;
    00069     guththila_writer_t *writer;
    00070 #ifdef GUTHTHILA_XML_WRITER_TOKEN
    00071     guththila_tok_list_t tok_list;
    00072 #endif
    00073     /* Type of this writer. Can be file writer or memory writer */
    00074     guththila_writer_type_t type;
    00075
    00076     FILE *out_stream;
    00077     guththila_buffer_t buffer;
    00078     guththila_writer_status_t status;
    00079     int next;
    00080 } guththila_xml_writer_t;
    00081
    00082 /*TODO: we need to came up with common implementation of followng two structures in writer and reader*/
    00083
    00084 /*
    00085 This is a private structure for keeping track of the elements. When we start to write an element this structure will be pop
    00086 */
    00087 typedef struct guththila_xml_writer_element_s
    00088 {
    00089 #ifdef GUTHTHILA_XML_WRITER_TOKEN
    00090     guththila_token_t *prefix;
    00091     guththila_token_t *name;
    00092 #else
    00093     guththila_char_t *prefix;
    00094     guththila_char_t *name;
    00095 #endif
    00096     /* contains the number of the stack which holds the namespaces
    00097        for this element. When we close this element all the namespaces
    00098        that are below this should also must be closed */
    00099     int name_sp_stack_no;
    00100 }
    00101 guththila_xml_writer_element_t;
    00102
    00103 typedef struct guththila_xml_writer_namesp_s
    00104 {
    00105     /* These are double pointers because a single element may contain multple
    00106        namespace declarations */
    00107 #ifdef GUTHTHILA_XML_WRITER_TOKEN
    00108     guththila_token_t **name;
    00109     guththila_token_t **uri;
    00110 #else
    00111     guththila_char_t **name;
    00112     guththila_char_t **uri;
    00113 #endif
    00114     int no;             /*number of namespaces */
    00115     int size;
    00116 }
    00117 guththila_xml_writer_namesp_t;
    00118
    00119 #define GUTHTHILA_XML_WRITER_NAMESP_DEF_SIZE 4
    00120
    00121 /*Writer functions*/
    00122
    00123 /*
    00124  * Create a writer which writes to a file.
    00125  * @param file_name name of the file
    00126  * @param env pointer to the environment
    00127  */
    00128 GUTHTHILA_EXPORT guththila_xml_writer_t *GUTHTHILA_CALL
    00129 guththila_create_xml_stream_writer(
    00130     char *file_name,
    00131     const axutil_env_t * env);
    00132
    00133 /*
    00134  * Create a writer which writes to a memory buffer.
    00135  * @param env pointer to the environment
    00136  */
    00137 GUTHTHILA_EXPORT guththila_xml_writer_t *GUTHTHILA_CALL
    00138 guththila_create_xml_stream_writer_for_memory(
    00139     const axutil_env_t * env);
    00140
    00141 /*
    00142  * Jus write what ever the content in the buffer. If the writer was in
    00143  * a start of a element it will close it.
    00144  * @param wr pointer to the writer
    00145  * @param buff buffer containing the data
    00146  * @param size size of the buffer
    00147  * @param env pointer to the environment
    00148  */
    00149 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_to_buffer(
    00150     guththila_xml_writer_t * wr,
    00151     char *buff,
    00152     int size,
    00153     const axutil_env_t * env);
    00154
    00155 /*
    00156  * Write the name space with the given prifix and namespace.
    00157  * @param wr pointer to the writer
    00158  * @param prefix prefix of the namespace
    00159  * @param uri uri of the namespace
    00160  * @param env pointer to the environment
    00161  */
    00162 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_namespace(
    00163     guththila_xml_writer_t * wr,
    00164     char *prefix,
    00165     char *uri,
    00166     const axutil_env_t * env);
    00167
    00168 /*
    00169  * Write the name space with the given prifix and namespace.
    00170  * @param wr pointer to the writer
    00171  * @param prefix prefix of the namespace
    00172  * @param uri uri of the namespace
    00173  * @param local_name name of the attribute
    00174  * @param value value of the attribute
    00175  * @param env pointer to the environment
    00176  */
    00177 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00178 guththila_do_write_attribute_with_prefix_and_namespace(
    00179     guththila_xml_writer_t * wr,
    00180     char *prefix,
    00181     char *uri,
    00182     char *local_name,
    00183     char *value,
    00184     const axutil_env_t * env);
    00185
    00186
    00187 /*
    00188  * Write the start document element with the xml version and encoding.
    00189  * @param wr pointer to the writer
    00190  * @param env pointer to the environment
    00191  * @param encoding encoding of the XML.
    00192  * @param version xml version
    00193  */
    00194 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_start_document(
    00195     guththila_xml_writer_t * wr,
    00196     const axutil_env_t * env,
    00197     char *encoding,
    00198     char *version);
    00199
    00200 /*
    00201  * Write the start element.
    00202  * @param wr pointer to the writer
    00203  * @param name name of the element
    00204  * @param env pointer to the environment
    00205  */
    00206 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_start_element(
    00207     guththila_xml_writer_t * wr,
    00208     char *name,
    00209     const axutil_env_t * env);
    00210
    00211 /*
    00212  * Write the end element.
    00213  * @param wr pointer to the writer
    00214  * @param env pointer to the environment
    00215  */
    00216 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_end_element(
    00217     guththila_xml_writer_t * wr,
    00218     const axutil_env_t * env);
    00219
    00220 /*
    00221  * Not implemented.
    00222  * @param wr pointer to the writer
    00223  * @param env pointer to the environment
    00224  */
    00225 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_close(
    00226     guththila_xml_writer_t * wr,
    00227     const axutil_env_t * env);
    00228
    00229 /*
    00230  * Write the text content of a element.
    00231  * @param wr pointer to the writer
    00232  * @param buff character string
    00233  * @param env pointer to the environment
    00234  */
    00235 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_characters(
    00236     guththila_xml_writer_t * wr,
    00237     char *buff,
    00238     const axutil_env_t * env);
    00239
    00240 /*
    00241  * Write comment with the given text data.
    00242  * @param wr pointer to the writer
    00243  * @param buff character string
    00244  * @param env pointer to the environment
    00245  */
    00246 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_comment(
    00247     guththila_xml_writer_t * wr,
    00248     char *buff,
    00249     const axutil_env_t * env);
    00250
    00251 /*
    00252  * Write scape character.
    00253  * @param wr pointer to the writer
    00254  * @param buff character string
    00255  * @param env pointer to the environment
    00256  */
    00257 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_escape_character(
    00258     guththila_xml_writer_t * wr,
    00259     char *buff,
    00260     const axutil_env_t * env);
    00261
    00262 /*
    00263  * Start to write an empty element with the given name.
    00264  * @param wr pointer to the writer
    00265  * @param name name of the element
    00266  * @param env pointer to the environment
    00267  */
    00268 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_empty_element(
    00269     guththila_xml_writer_t * wr,
    00270     char *name,
    00271     const axutil_env_t * env);
    00272
    00273 /*
    00274  * Write a defualt namespace.
    00275  * @param wr pointer to the writer
    00276  * @param uri uri of the namespace
    00277  * @param env pointer to the environment
    00278  */
    00279 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_default_namespace(
    00280     guththila_xml_writer_t * wr,
    00281     char *uri,
    00282     const axutil_env_t * env);
    00283
    00284 /*
    00285  * Write a attribute with the given name and value.
    00286  * @param wr pointer to the writer
    00287  * @param localname name of the attribute
    00288  * @param value value of the attribute
    00289  * @param env pointer to the environment
    00290  */
    00291 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_attribute(
    00292     guththila_xml_writer_t * wr,
    00293     char *localname,
    00294     char *value,
    00295     const axutil_env_t * env);
    00296
    00297 /*
    00298  * Write a attribute with the given name and value and namespace.
    00299  * @param wr pointer to the writer
    00300  * @param prefix prefix of the attribute
    00301  * @param namespace_uri uri of the namespace
    00302  * @param localname name of the attribute
    00303  * @param value value of the attribute
    00304  * @param env pointer to the environment
    00305  */
    00306 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00307 guththila_write_attribute_with_prefix_and_namespace(
    00308     guththila_xml_writer_t * wr,
    00309     char *prefix,
    00310     char *namespace_uri,
    00311     char *localname,
    00312     char *value,
    00313     const axutil_env_t * env);
    00314
    00315 /*
    00316  * Write a attribute with the given name, value and prefix. If the prefix
    00317  * is not defined previously as a namespace this method will fail.
    00318  * @param wr pointer to the writer
    00319  * @param prefix prefix of the attribute
    00320  * @param localname name of the attribute
    00321  * @param value value of the attribute
    00322  * @param env pointer to the environment
    00323  */
    00324 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_attribute_with_prefix(
    00325     guththila_xml_writer_t * wr,
    00326     char *prefix,
    00327     char *localname,
    00328     char *value,
    00329     const axutil_env_t * env);
    00330
    00331 /*
    00332  * Write a attribute with the given name, value and namespace uri.
    00333  * If the namespace is not defined previously as a namespace this
    00334  * method will fail. The prefix corresponding to the namespace uri
    00335  * will be used.
    00336  * @param wr pointer to the writer
    00337  * @param namesp namespace uri
    00338  * @param localname name of the attribute
    00339  * @param value value of the attribute
    00340  * @param env pointer to the environment
    00341  */
    00342 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_attribute_with_namespace(
    00343     guththila_xml_writer_t * wr,
    00344     char *namesp,
    00345     char *localname,
    00346     char *value,
    00347     const axutil_env_t * env);
    00348
    00349 /*
    00350  * Write a start element with prefix and namespace. If the namespace is not
    00351  * defined previoully new namespace will be written.
    00352  * @param wr pointer to the writer
    00353  * @param prefix prefix of the attribute
    00354  * @param namespace_uri uri
    00355  * @param localname name of the attribute
    00356  * @param env pointer to the environment
    00357  */
    00358 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00359 guththila_write_start_element_with_prefix_and_namespace(
    00360     guththila_xml_writer_t * wr,
    00361     char *prefix,
    00362     char *namespace_uri,
    00363     char *local_name,
    00364     const axutil_env_t * env);
    00365
    00366 /*
    00367  * Write a start element with the namespace. If the namespace is not
    00368  * defined previously method will fail.
    00369  * @param wr pointer to the writer
    00370  * @param namespace_uri uri
    00371  * @param localname name of the attribute
    00372  * @param env pointer to the environment
    00373  */
    00374 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00375 guththila_write_start_element_with_namespace(
    00376     guththila_xml_writer_t * wr,
    00377     char *namespace_uri,
    00378     char *local_name,
    00379     const axutil_env_t * env);
    00380
    00381 /*
    00382  * Write a start element with the prefix. If the prefix is not
    00383  * defined previously method will fail.
    00384  * @param wr pointer to the writer
    00385  * @param namespace_uri uri
    00386  * @param localname name of the attribute
    00387  * @param env pointer to the environment
    00388  */
    00389 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00390 guththila_write_start_element_with_prefix(
    00391     guththila_xml_writer_t * wr,
    00392     char *prefix,
    00393     char *local_name,
    00394     const axutil_env_t * env);
    00395
    00396 /*
    00397  * Write a empty element with prefix and namespace. If the namespace is not
    00398  * defined previoully new namespace will be written.
    00399  * @param wr pointer to the writer
    00400  * @param prefix prefix of the attribute
    00401  * @param namespace_uri uri
    00402  * @param localname name of the attribute
    00403  * @param env pointer to the environment
    00404  */
    00405 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00406 guththila_write_empty_element_with_prefix_and_namespace(
    00407     guththila_xml_writer_t * wr,
    00408     char *prefix,
    00409     char *namespace_uri,
    00410     char *local_name,
    00411     const axutil_env_t * env);
    00412
    00413 /*
    00414  * Write a empty element with the namespace. If the namespace is not
    00415  * defined previously method will fail.
    00416  * @param wr pointer to the writer
    00417  * @param namespace_uri uri
    00418  * @param localname name of the attribute
    00419  * @param env pointer to the environment
    00420  */
    00421 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00422 guththila_write_empty_element_with_namespace(
    00423     guththila_xml_writer_t * wr,
    00424     char *namespace_uri,
    00425     char *local_name,
    00426     const axutil_env_t * env);
    00427
    00428 /*
    00429  * Write a empty element with the prefix. If the prefix is not
    00430  * defined previously method will fail.
    00431  * @param wr pointer to the writer
    00432  * @param namespace_uri uri
    00433  * @param localname name of the attribute
    00434  * @param env pointer to the environment
    00435  */
    00436 GUTHTHILA_EXPORT int GUTHTHILA_CALL
    00437 guththila_write_empty_element_with_prefix(
    00438     guththila_xml_writer_t * wr,
    00439     char *prefix,
    00440     char *local_name,
    00441     const axutil_env_t * env);
    00442
    00443 /*
    00444  * Close all the elements that were started by writing the end elements.
    00445  * @param wr pointer to the writer
    00446  * @param env pointer to the environment
    00447  */
    00448 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_end_document(
    00449     guththila_xml_writer_t * wr,
    00450     const axutil_env_t * env);
    00451 /*
    00452  * Write a new element with the name, then write the characters as text,
    00453  * then close the element and write a new line.
    00454  * @param wr pointer to the writer
    00455  * @element_name name of the element
    00456  * @characters text of the new element
    00457  * @param env pointer to the environment
    00458  */
    00459 GUTHTHILA_EXPORT int GUTHTHILA_CALL guththila_write_line(
    00460     guththila_xml_writer_t * wr,
    00461     char *element_name,
    00462     char *characters,
    00463     const axutil_env_t * env);
    00464
    00465 /*
    00466  * Get the memory buffer that is written.
    00467  * @param wr pointer to the writer
    00468  * @param env pointer to the environment
    00469  * @return memory buffer
    00470  */
    00471 GUTHTHILA_EXPORT char *GUTHTHILA_CALL guththila_get_memory_buffer(
    00472     guththila_xml_writer_t * wr,
    00473     const axutil_env_t * env);
    00474
    00475 /*
    00476  * Get the size of the memory buffer.
    00477  * @param wr pointer to the writer
    00478  * @param env pointer to the environment
    00479  * @return size of the buffer
    00480  */
    00481 GUTHTHILA_EXPORT unsigned int GUTHTHILA_CALL
    00482 guththila_get_memory_buffer_size(
    00483     guththila_xml_writer_t * wr,
    00484     const axutil_env_t * env);
    00485
    00486 /*
    00487  * Free the writer.
    00488  * @param wr pointer to the writer
    00489  * @param env pointer to the environment
    00490  */
    00491 GUTHTHILA_EXPORT void GUTHTHILA_CALL guththila_xml_writer_free(
    00492     guththila_xml_writer_t * wr,
    00493     const axutil_env_t * env);
    00494 /*
    00495  * Get the prefix for the namespace.
    00496  * @param wr pointer to the writer
    00497  * @namespace namespace uri
    00498  * @param env pointer to the environment
    00499  * @return prefix for the namspace uri
    00500  */
    00501 GUTHTHILA_EXPORT char *GUTHTHILA_CALL guththila_get_prefix_for_namespace(
    00502     guththila_xml_writer_t * wr,
    00503     char *namespace,
    00504     const axutil_env_t * env);
    00505
    00506 EXTERN_C_END()
    00507 #endif