/*----------------------------------------------------------------------------*\ * Copyright (c) 2001-2003 CubeWerx Inc. Licensed under the GNU LGPL. * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Lesser General Public License as published * by the Free Software Foundation, either version 2.1 of the License, * or any later version. This library is distributed in the hope that * it will be useful, but WITHOUT ANY WARRANTY, without even the implied * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * See the GNU Lesser General Public License for more details, either * in the "LICENSE.LGPL.txt" file distributed with this software or at * web page "http://www.fsf.org/licenses/lgpl.html". * * MODULE: cw_xmlgen.h * PURPOSE: XML/BXML generator * HISTORY: * DATE PROGRAMMER DESCRIPTION * 05-Apr-2001 Craig Bruce Initial creation * 01-May-2003 Craig Bruce Updated for new interface *---------------------------------------------------------------------------- * $Id: cw_xmlgen.h,v 1.9 2004/02/26 16:44:25 pomakis Exp $ \*----------------------------------------------------------------------------*/ #include #include #include #ifndef _CW_XML_GEN_H #define _CW_XML_GEN_H #ifdef __cplusplus extern "C" { #endif /*----------------------------------------------------------------------------*\ * CW_XML_GEN_TAG_TYPE - type of element to generate \*----------------------------------------------------------------------------*/ typedef enum { CW_XML_GEN_TAG_OPEN, /* */ CW_XML_GEN_TAG_CLOSE, /* */ CW_XML_GEN_TAG_OPEN_CLOSE, /* */ CW_XML_GEN_TAG_QUESTION, /* */ CW_XML_GEN_TAG_BANG, /* */ CW_XML_GEN_TAG_COMMENT, /* */ CW_XML_GEN_TAG_TEXT /* text */ } CW_XML_GEN_TAG_TYPE; /*----------------------------------------------------------------------------*\ * CW_XML_GEN_STATE - current state of generator \*----------------------------------------------------------------------------*/ typedef enum { CW_XML_GEN_STATE_AT_TAG_START, /* at start of element-opening tag */ CW_XML_GEN_STATE_AT_ATTR_START, /* at start of attribute, no content(yet)*/ CW_XML_GEN_STATE_IN_ATTR_CONTENT,/* inside attribute, content */ CW_XML_GEN_STATE_IN_TAG, /* inside of element-opening tag, w/attrs*/ CW_XML_GEN_STATE_IN_CONTENT, /* inside of general content */ CW_XML_GEN_STATE_AFTER_MARKUP /* immediately after structural tag */ } CW_XML_GEN_STATE; /*----------------------------------------------------------------------------*\ * CW_XML_GEN - context for generating - do not access directly \*----------------------------------------------------------------------------*/ typedef struct { /** stream **/ FILE *stream; /* file object to generate to */ bool localGZipActive; /* gzip compression activated locally */ int gzipLevel; /* level for GZIP compression */ /** formatting **/ bool foldEmptyElements; /* fold open/close tags of empty elements hint */ bool genBxml; /* generate BXML binary=TRUE or text=FALSE */ long bxmlVersion; /* BXML version number to generate */ bool tryRefBxmlStrings; /* try to generate BXML text content as str ref*/ bool storeAllBxmlStrings; /* add all BXML text content to string table */ bool textPack; /* pack text output */ long textBaseIndent; /* base for text indentation, usually 0 */ long textLevelIndent; /* xml-level indentation (# spaces) */ long textWidth; /* width to generate text for, 0=unlimited */ long tabReplacementSize;/* tab indentation size, 0 = no tabs */ /** state **/ CW_XML_GEN_STATE genState; /* current generator state */ CW_XML_STR_TAB_ENT *tagNameSymbolRef; /* reference to tag name */ bool tagHasContent; /* tag being generated will have content */ long xmlLevel; /* current level of xml-code nesting (from 0) */ long textPos; /* position on line (only 0 or 1 for now) */ void *stringTable; /* string table */ } CW_XML_GEN; /*============================================================================*\ * INITIALIZATION & SHUTDOWN METHODS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_Init() - start XML generator on a file stream * DESCRIPTION: * Starts the XML generator on a file stream. * ARGUMENTS: * file - file to generate XML output to * RETURNS: * xmlGen - xml-generator control object, or NULL on error * ERRORS: * - malloc errors are possible if they are enabled * - otherwise, no errors are possible \*----------------------------------------------------------------------------*/ CWEXP CW_XML_GEN *CwXmlGen_Init( FILE *file ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_Finish() - finish generating XML stream * DESCRIPTION: * Finishes generating XML output to a file stream. Writes out the * BXML trailer token if necessary, finishes generating GZIP output * if necessary, flushes the output file, and checks for file errors. * Note that this call does not close the file (since the gen-init * function doesn't open it). The xml-gen object will be destroyed * regardless of whether an error occurs. * ARGUMENTS: * xmlGen - xml-generator control object, allowed to be NULL * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file/gzip errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_Finish( CW_XML_GEN *xmlGen ); /*============================================================================*\ * FORMAT-SELECTION METHODS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_SetTextFormatting() - select text formatting & set text params * DESCRIPTION: * Selects text formatting and sets various parameters for compression * and 'pretty' text appearance. Parameters are provided for the base * indent level, per-XML-level indent level, tab-replacement size, * and text width. The tab-replacement size tells how many spaces * to replace with a TAB (0x09) character. A value of 0 means that * no TAB characters will be used, only spaces. A text width of * 0 is interpreted as lines being infinite length. A value of -1 * to any of the parameters means not to change the present value. * The default values in the xml-gen environment are: baseIndent=0, * perLevelIndent=2, tabReplacementSize=0, textWidth=80. * ARGUMENTS: * xmlGen - xml-generation environment object * compress - flag to generate compressed output * baseIndent - base indentation for root XML-level; normally 0 * perLevelIndent - the amount to indent for each XML level * tabReplacementSize- number of space to replace with TAB char, or 0 * textWidth - text/page width to format output for, 0=inf * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file error writing GZIP-compression header \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_SetTextFormatting( CW_XML_GEN *xmlGen, bool compress, long baseIndent, long perLevelIndent, long tabReplacementSize, long textWidth); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_SetPackedTextFormatting() - select packed-text formatting * DESCRIPTION: * Selects packed-text formatting & sets line length and compression * mode. Packed-text XML means to output XML with no whitespace * between the tags, except to format for the text width (line length). * A text width of 0 is interpreted as being infinity. A text width * of -1 will leave the current setting unchanged. * ARGUMENTS: * xmlGen - xml-generation environment object * compress - flag to generate compressed output * textWidth - text/page width to format output for, 0=infinity * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file error writing GZIP-compression header \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_SetPackedTextFormatting( CW_XML_GEN *xmlGen, bool compress, long textWidth ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_SetBxmlFormatting() - select BXML formatting * DESCRIPTION: * This selects the BXML (Binary-XML) format for output and writes the * BXML header to the output stream. The output stream must be set * for binary writing. The default character encoding is "ISO-8859-1". * ARGUMENTS: * xmlGen - xml-generation environment object * bxmlVersion - BXML format version 'xxyyzz', or -1=default * compress - flag whether to compress the BXML stream * charEncoding - character-set encoding for BXML stream, NULL=default * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors * - invalid arguments \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_SetBxmlFormatting( CW_XML_GEN *xmlGen, long bxmlVersion, bool compress, const char *charEncoding ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_SetFormattingFromCmdArgs() - set formatting from cmd args * DESCRIPTION: * This function sets the formatting parameters from a given set * of command-line arguments, as parsed by the CmdArgs mechanism. * The following arguments are utilized: * * NAME TYPE MEANING * ----------------- ---- -------- * xml.bxml bool select binary BXML formatting * xml.bxmlVersion str BXML version to use in "x.y.z" format * xml.refAllStrings bool reference all BXML strings * xml.compress bool select GZIP compression * xml.gzipLevel int GZIP compression level to use if selected * xml.pack bool select packed-text formatting * xml.baseIndent long base tag indentation * xml.indent long tag indentation * xml.textWidth long text width * xml.tabSize long tab substitution * * You may use simpler argument names in your application by using * cmd-arg aliases. * ARGUMENTS: * xmlGen - xml-generation environment object * bxmlVersion - BXML format version, or -1=default * compress - flag whether to compress the BXML stream * charEncoding - character-set encoding for BXML stream, NULL=default * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - invalid cmd-arg values * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_SetFormattingFromCmdArgs( CW_XML_GEN *xmlGen, CMDARG_CTL *cmdArgs ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_DetermineFormattingForHttp() - determine formatting for HTTP * DESCRIPTION: * This function determines (but does not set) XML-reply formatting * parameters according to requested HTTP MIME-type and HTTP * "Accept-Encoding" parameters. This function does not set up * the formatting itself since this must be called before the * HTTP reply header is emitted and the setting up of BXML or GZIP * encoding will emit the format header immediately. The normal * flow of activity will be to call this function, then to emit the * HTTP-reply header, then call CwXmlGen_Init(), and then to call * either CwXmlGen_SetBxmlFormatting() or CwXmlGen_SetTextFormatting(). * * A specific HTTP-reply MIME type and content encoding value will * be selected. The input MIME types may be a comma-separated list * including types with extensions "+xml", "+x-bxml", "+bxml", or * with additional extension "+gzip". (An underscore is accepted in * place of the '+' for WMS-mistake compatibility.) Plain-text XML * will be selected unless GZIP or BXML encoding is specifically * allowed. The 'httpAcceptEncodings' follows the syntax of the * HTTP "Accept-Encoding" header tag and controls the selection * between uncompressed ("identity") and GZIP-compressed output. * If a NULL is passed for this parameter, the environment variable * "HTTP_ACCEPT_ENCODING" will be consulted instead, if it exists. * * The 'remoteNetAddress' value is used to determine if compression * should be used if it is requested in an optional way. Compression * will be selected in this case only if the remote machine is on a * "different network", since compressing output sent to the same * network or the same machine is most likely to be wasteful of * resources. If the 'remoteNetAddress' value is NULL, the environment * variable "REMOTE_ADDR" will be consulted instead, if it exists. * * The HTTP information that is selected is returned in the * 'outMimeType' and 'outHttpContentEncoding' parameters. The MIME * type will be StrCpy()d into the 'outMimeType' which must have a size * of at least CW_NAME_SIZE. The MIME type should be reported in the * "Content-Type" HTTP reply-header tag. The content-encoding value * is returned as a const-string pointer. If it is not NULL, then its * value should be generated into the HTTP reply header as the value * of either the "Content-Encoding" or the "Transfer-Encoding" tag. * If the value is NULL, then these tags don't need to be generated. * * Finally, the 'outIsXml', 'outSelectBxmlVersion', and * 'outSelectCompression' returned values should be used to set * the XML formatting at the appropriate time. The 'outIsXml' flag * indicates whether the MIME format(s) given indicate XML at all. * If 'outSelectBxmlVersion' is != 0, then CwXmlGen_SetBxmlFormatting() * should be used with the given version number (which may be -1 * for 'default'); otherwise, text formatting should be selected. * The 'outSelectCompression' value should be passed as the * 'compress' argument to the format-selection call. Note that * 'outSelectCompression' may have a different meaning from the * 'outHttpContentEncoding' value since in different cases, compression * may be considered to be either an inherent part of the stream data * or as an add-on encoding. * ARGUMENTS: * mimeTypes - comma-separated list of suitable, equivalent MIME types * httpAcceptEncodings - list of HTTP "Accept-Encoding" parameters, NULL * remoteNetAddress - net address that output is to be sent to, NULL * outMimeType - (out) MIME type selected [CW_NAME_SIZE], or NULL * outHttpContentEncoding - (out) "Content-Encoding" value or NULL * outIsXml - (out) flag indicating that MIME format is for XML * outSelectBxmlVersion - (out) version of BXML to use if >= 0, else text * outSelectCompression - (out) flag to pass to formatting setter * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - invalid arguments * - malloc errors are possible if they are enabled \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_DetermineFormattingForHttp( const char *mimeTypes, const char *httpAcceptEncodings, const char *remoteNetAddress, char *outMimeType, const char **outHttpContentEncoding, bool *outIsXml, long *outSelectBxmlVersion, bool *outSelectCompression ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_SetBxmlStringTableUsage() - set BXML string-table usage for text * DESCRIPTION: * This selects the mode of usage of the string table for text content. * Normally, all string content is generated in-line, but setting * 'tryToRefAllContentStrings' will make it so that the string table is * searched for the content string every time, and if the content string * is found in the string table, then a string-table reference will * be emitted into the BXML string. Strings may be added manually to * the string table using CwXmlGen_AddStringsToStringTable() or all * content strings can be added to the string table automatically * by setting the 'storeAllBxmlStrings' flag. The processing and * file-size overhead is not that large even for strings that occur * only once and some files will be significantly smaller and will also * compress significantly better in this mode. The runtime penalty * for storing all strings is also quite small. This function has * no effect if BXML encoding has not been selected. * ARGUMENTS: * xmlGen - xml-generation environment object * tryToRefAllContentStrings - try to ref all BXML string content * storeAllBxmlStrings - store all BXML content strings into string table * RETURNS: * (nothing) * ERRORS: * (no errors are possible) \*----------------------------------------------------------------------------*/ CWEXP void CwXmlGen_SetBxmlStringTableUsage( CW_XML_GEN *xmlGen, bool tryToRefAllContentStrings, bool storeAllBxmlStrings ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_FlushStream() - flush out any buffered data to stream * DESCRIPTION: * Flushes out any buffered data. * ARGUMENTS: * xmlGen - (in-out) xml-generation environment object * RETURNS: * (nothing) * ERRORS: * (no errors are possible) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_FlushStream( CW_XML_GEN *xmlGen ); /*============================================================================*\ * ELEMENT-LEVEL 'CONVENIENCE' METHODS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_OpenTagAttr() - generate XML opening element, e.g., * DESCRIPTION: * This generates an XML opening element to the output with a given * variable-length list of attribute name/value pairs. If an attribute * name is preceded with the character '#', then a numeric attribute * will be generated, and the argument value will need to be passed as * a 'double'. Much of the time, you will need to cast the numeric * value to (double) explicitly. Be very careful to do this, since * the compiler cannot do this for you. If an attribute name is * preceded with the character '!', then a boolean attribute will be * generated and the argument value will need to be passed as a 'bool'. * Otherwise, if there is no preceding character, the attribute * will be for a string value, logically of type 'const char *'. * If a NULL pointer is given for the attribute string value, then * that attribute will not be generated. The attribute names must not * be NULL. The value-type-identifying prefix characters for numeric * and boolean attribute namess are stripped off in the XML output, * of course. * * * For example, calling with: * * CwXmlGen_OpenTagAttr( xmlGen, "MyElement", 3, * "stringAttr", "string_value", * "#numericAttr", (double) 42, * "!booleanAttr", (bool) TRUE ); * * will generate attributes of the three respective types. Note that * the numeric values should always be explicitly cast to type (double) * since this is the type that numbers are accepted in, and since these * values are passed using a variable-length argument list ("..."), * C cannot enforce any type conversions. Though they are passed as * type 'double', numeric values will be represented in BXML using the * most efficient type; in this case, 42 would be represented using a * single-byte BXML 'SmallNum' value. Even actual 'double' will be * represented as 'float's if there is no loss of precision (e.g., * 100.25). Boolean values should probably be explicitly cast as well. * * ARGUMENTS: * xmlGen - (in-out) xml-generation environment object * tagName - the name of the element tag * nAttributes - the number of attributes given * ... - variable argument list of attribute name/value pairs * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_OpenTagAttr( CW_XML_GEN *xmlGen, const char *tagName, long nAttributes, ... ); #define CwXmlGen_OpenTag(xmlGen,tagName) \ CwXmlGen_OpenTagAttr( (xmlGen), (tagName), 0 ) /*----------------------------------------------------------------------------*\ * CwXmlGen_CloseTag() - generate XML closing element to output * - err return (file/xml-formatting errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_CloseTag( CW_XML_GEN *xmlGen, const char *tagName ); /*----------------------------------------------------------------------------*\ * CwXmlGen_EmptyTagAttr() - generate XML open/close element to output w/attrs * - the attributes are handled in the same was as CwXmlGen_OpenTagAttr() * - err return (file/xml-formatting errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_EmptyTagAttr( CW_XML_GEN *xmlGen, const char *tagName, long nAttributes, ... ); #define CwXmlGen_EmptyTag(xmlGen,tagName) \ CwXmlGen_EmptyTagAttr( (xmlGen), (tagName), 0 ) /*----------------------------------------------------------------------------*\ * CwXmlGen_LeafTagAttr() - generate text w/attrs * - the attributes are handled in the same was as in CwXmlGen_OpenTagAttr() * - null text causes no content to be generated * - err return (file errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_LeafTagAttr( CW_XML_GEN *xmlGen, const char *tagName, const char *text, long nAttributes, ... ); #define CwXmlGen_LeafTag(xmlGen,tagName,text) \ CwXmlGen_LeafTagAttr( (xmlGen), (tagName), (text), 0 ) /*----------------------------------------------------------------------------*\ * CwXmlGen_NumberLeafTagAttr() - generate number w/attrs * - the attributes are handled in the same was as in CwXmlGen_OpenTagAttr() * - the tag will have numeric content * - err return (file errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_NumberLeafTagAttr( CW_XML_GEN *xmlGen, const char *tagName, double number, long nAttributes, ... ); #define CwXmlGen_NumberLeafTag(xmlGen,tagName,number) \ CwXmlGen_NumberLeafTagAttr( (xmlGen), (tagName), (number), 0 ) /*----------------------------------------------------------------------------*\ * CwXmlGen_BoolLeafTagAttr() - generate boolean w/attrs * - the attributes are handled in the same was as in CwXmlGen_OpenTagAttr() * - the tag will have boolean content * - err return (file errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_BoolLeafTagAttr( CW_XML_GEN *xmlGen, const char *tagName, bool content, long nAttributes, ... ); #define CwXmlGen_BoolLeafTag(xmlGen,tagName,content) \ CwXmlGen_BoolLeafTagAttr( (xmlGen), (tagName), (content), 0 ) /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_TextAttribute() - generate attribute with text content * DESCRIPTION: * This generates an attribute with text content. Because of current * architectural limitations, this can only be called when the current * element-opening tag is still open, i.e., after CwXmlGen_OpenTag() * or CwXmlGen_StartElement(). If the value is a NULL pointer, * then nothing will be generated. * ARGUMENTS: * xmlGen - xml-generation environment object * name - attribute name * value - text content for attribute * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors * - xml formatting \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_TextAttribute( CW_XML_GEN *xmlGen, const char *attrName, const char *value ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_NumberAttribute() - generate attribute with numeric value * DESCRIPTION: * This generates an attribute with numeric content. Usage of this * function has the same limitations as CwXmlGen_TextAttribute(). * ARGUMENTS: * xmlGen - xml-generation environment object * name - attribute name * value - numeric content for attribute * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors * - xml formatting \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_NumberAttribute( CW_XML_GEN *xmlGen, const char *name, double value ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_BoolAttribute() - generate attribute with boolean value * DESCRIPTION: * This generates an attribute with boolean content. Usage of this * function has the same limitations as CwXmlGen_TextAttribute(). * ARGUMENTS: * xmlGen - xml-generation environment object * name - attribute name * value - boolean value for attribute * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors * - xml formatting \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_BoolAttribute( CW_XML_GEN *xmlGen, const char *name, bool value ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_XmlString() - generate from arbitrary XML string * DESCRIPTION: * This function scans the given XML string and regenerates XML output * from it. * ARGUMENTS: * xmlGen - xml-generation environment object * xmlString - arbitrary XML string * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors * - xml formatting \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_XmlString( CW_XML_GEN *xmlGen, const char *xmlString ); /*============================================================================*\ * ELEMENT & ATTRIBUTE MICRO-MANAGEMENT METHODS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * CwXmlGen_StartElement() - start generating a new element * - 'hasContent' tells if tag structurally will have content/be empty * - err return (file errors/malloc if enabled) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_StartElement( CW_XML_GEN *xmlGen, const char *name, bool hasContent ); /*----------------------------------------------------------------------------*\ * CwXmlGen_StartAttribute() - start generating an attribute * - err return (file/xml-formatting errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_StartAttribute( CW_XML_GEN *xmlGen, const char *name ); /*----------------------------------------------------------------------------*\ * CwXmlGen_FinishAttribute() - finish generating an attribute * - err return (file/xml-formatting errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_FinishAttribute( CW_XML_GEN *xmlGen ); /*----------------------------------------------------------------------------*\ * CwXmlGen_FinishElement() - finish generating current element * - err return (file/xml-formatting errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_FinishElement( CW_XML_GEN *xmlGen, const char *name ); /*============================================================================*\ * CONTENT-GENERATION METHODS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * CwXmlGen_Text() - generate text content * - NULL text will generate empty content * - err return (file errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_Text( CW_XML_GEN *xmlGen, const char *text ); /*----------------------------------------------------------------------------*\ * CwXmlGen_Number() - generate a scalar number as content * - the most efficient representation will be selected for BXML output * - err return (file errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_Number( CW_XML_GEN *xmlGen, double value ); /*----------------------------------------------------------------------------*\ * CwXmlGen_Bool() - generate a scalar boolean value as content * - err return (file errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_Bool( CW_XML_GEN *xmlGen, bool value ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_Array() - generate an array as content * DESCRIPTION: * Generates an array of numbers or booleans as content. An array * is output as a space-separated list in textual XML as defined by * XML Schema and as a special Array token in BXML. An array of zero * elements will be generated into BXML but no content will be emitted * in XML (since XML has no representation for the empty string). * If the optimize flag is given, the array will be examined to * determine the minimum-size element type that may be used to store * the given data. * ARGUMENTS: * xmlGen - xml-generation environment object * elementType - type of element * elements - array data * nElements - number of array elements * optimize - flag to optimize element representation * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - malloc errors are possible if they are enabled * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_Array( CW_XML_GEN *xmlGen, CW_XML_VALTYPE elementType, const void *elements, long nElements, bool optimize ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_AddStringsToStringTable() - manually add strings to string table * DESCRIPTION: * This allows you to manually add strings to the string table. * The updated string table will not be flushed to the BXML string * until necessary. A variable-length list of arguments is used to * pass in the strings with a prefixing count. You don't need to worry * about adding a string more than once or about referencing every * string that you add, though unreferenced strings will be wasteful. * * When used in combination with CwXmlGen_SetBxmlStringTableUsage(), * you can manually specify which content strings will be generated * by reference instead of in-line. * ARGUMENTS: * xmlGen - xml-generation environment object * nStrings - number of strings in variable-length list * ... - variable-length list of 'const char *' strings * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - malloc errors are possible if they are enabled * - otherwise, no errors are possible \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_AddStringsToStringTable( CW_XML_GEN *xmlGen, long nStrings, ... ); /*============================================================================*\ * SPECIAL-MARKUP-GENERATION METHODS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_XmlDeclaration() - generate tag * DESCRIPTION: * Generate the XML-Declaration tag or BXML equivalent. * This should be the first content generated into an XML document. * In the case that the output format is BXML, the 'charEncoding' * string here will be ignored and the one provided to the * CwXmlGen_SetBinaryFormatting() will be authoritative. * ARGUMENTS: * xmlGen - xml-generation environment object * xmlVersion - XML version number, or NULL=default * charEncoding - char-encoding identifier, or NULL=default (ISO-8859-1) * isStandalone - 1=yes, 0=no, -1=unknown * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors * - invalid arguments \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_XmlDeclaration( CW_XML_GEN *xmlGen, const char *xmlVersion, const char *charEncoding, int isStandalone ); /*----------------------------------------------------------------------------*\ * CwXmlGen_Comment() - generate a comment * - a null string will skip comment generation * - err return (file/xml-formatting errors) \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_Comment( CW_XML_GEN *xmlGen, const char *comment ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_BlankLines() - write a blank line in the output, if suitable * DESCRIPTION: * Writes a sequence of blank lines, or equivalent, in the XML output. * This can be viewed as a special kind of comment. Nothing is output * when generating in 'packed' text mode. * ARGUMENTS: * xmlGen - (in-out) xml-generation environment object * nBlankLines - number of blank lines to generate * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_BlankLines( CW_XML_GEN *xmlGen, long nBlankLines ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_BangTag() - generate tag * DESCRIPTION: * Writes out a 'bang' tag. * ARGUMENTS: * xmlGen - xml-generation environment object * name - tag name immediately after '!' character in XML * body - text body content of tag * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_BangTag( CW_XML_GEN *xmlGen, const char *name, const char *body ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_ProcessingInstructionTag() - generate tag * DESCRIPTION: * Writes out a processing instruction tag. Note that this is distinct * from the XML-declaration tag and isn't used much. * BUGS: * XXX NOT IMPLEMENTED; this is a no-op for now. * ARGUMENTS: * xmlGen - xml-generation environment object * name - tag name immediately after first '?' character in XML * body - text body content of tag * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_ProcessingInstructionTag( CW_XML_GEN *xmlGen, const char *name, const char *body ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_BangBracketTag() - generate tag * DESCRIPTION: * Writes out a 'bang-bracket' tag. Note that this is distinct from * the CDATA-section tag and isn't used much. * BUGS: * XXX NOT IMPLEMENTED; this is a no-op for now. * ARGUMENTS: * xmlGen - xml-generation environment object * name - tag name immediately after first '[' character in XML * body - text body content of tag * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_BangBracketTag( CW_XML_GEN *xmlGen, const char *name, const char *body ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_ScannedNode() - generate output for XML-scan node object * DESCRIPTION: * Generates the output for an XML-scan node object. Nothing is * generated if either 'xmlGen' or 'node' is NULL. * ARGUMENTS: * xmlGen - xml-generation environment object * node - xml-scan node object * RETURNS: * err - 0 on success or -1 on error * ERRORS: * - file errors \*----------------------------------------------------------------------------*/ CWEXP int CwXmlGen_ScannedNode( CW_XML_GEN *xmlGen, const CW_XML_NODE *node ); /*============================================================================*\ * UTILITY FUNCTIONS \*============================================================================*/ /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_ProtectText() - escape the text of a string for XML content * DESCRIPTION: * Replaces '<', '>', and '&' characters of a string with XML entities * "<", ">", and "&", respectively. For attribute strings, * it also replaces '"' with """. (Implying that generated * attributes should be enclosed in double quotes instead of * apostrophes, which the CwXmlGen environment does.) The interface * is complicated because the output string may be longer than the * input string. The function returns a pointer to the result string. * The returned pointer will be of the input string if the string * does not contain any of the special characters, or it will be a * dynamically-allocated string if the input string did contain any * of the characters. An output flag indicates if the returned string * needs to be free()d by the caller. * ARGUMENTS: * source - source string * forAttribute - flag for string being part of XML attribute * outMustFree - (out) flag indicating if caller must free result string * RETURNS: * dest - result string, or NULL on error * ERRORS: * - malloc errors are possible if they are enabled * - otherwise, no errors are possible \*----------------------------------------------------------------------------*/ CWEXP char *CwXmlGen_ProtectText( const char *source, bool forAttribute, bool *outMustFree ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_ProtectTextObsolete() - escape XML text; DO NOT USE! * DESCRIPTION: * THIS FUNCTION IS OBSOLETE AND SHOULD NOT BE USED BY ANY NEW CODE. * Use CwXmlGen_ProtectText() instead. * ARGUMENTS: * dest - (out) dest-string buffer * source - source string * destSize - size of dest-string buffer * RETURNS: * destLen - byte length of dest string * ERRORS: * (no errors are possible) \*----------------------------------------------------------------------------*/ CWEXP long CwXmlGen_ProtectTextObsolete( char *dest, char *source, long destSize ); /*----------------------------------------------------------------------------*\ * NAME: * CwXmlGen_InstallNetworkCallouts() - install callouts for network ops * DESCRIPTION: * Installs the callouts for network functionality to use remote-URL * contents as regular files. * ARGUMENTS: * net_IsInLocalDomain - method to determine if hostname addr is local * RETURNS: * (nothing) * ERRORS: * (no errors are possible) \*----------------------------------------------------------------------------*/ void CwXmlGen_InstallNetworkCallouts( bool (*net_IsInLocalDomain)(const char *hostname) ); #ifdef __cplusplus }; #endif #endif /*----------------------------------------------------------------------------*\ * END OF MODULE: cw_xmlgen.h \*----------------------------------------------------------------------------*/