libxml2/libxml/xmlreader.h

0001 /**
0002  * @file
0003  *
0004  * @brief the XMLReader implementation
0005  *
0006  * API of the XML streaming API based on C\# interfaces.
0007  *
0008  * @copyright See Copyright for the status of this software.
0009  *
0010  * @author Daniel Veillard
0011  */
0012
0013 #ifndef __XML_XMLREADER_H__
0014 #define __XML_XMLREADER_H__
0015
0016 #include <libxml/xmlversion.h>
0017 #include <libxml/tree.h>
0018 #include <libxml/xmlerror.h>
0019 #include <libxml/xmlIO.h>
0020 #ifdef LIBXML_RELAXNG_ENABLED
0021 #include <libxml/relaxng.h>
0022 #endif
0023 #ifdef LIBXML_SCHEMAS_ENABLED
0024 #include <libxml/xmlschemas.h>
0025 #endif
0026 #include <libxml/parser.h>
0027
0028 #ifdef __cplusplus
0029 extern "C" {
0030 #endif
0031
0032 /**
0033  * How severe an error callback is when the per-reader error callback API
0034  * is used.
0035  */
0036 typedef enum {
0037     XML_PARSER_SEVERITY_VALIDITY_WARNING = 1,
0038     XML_PARSER_SEVERITY_VALIDITY_ERROR = 2,
0039     XML_PARSER_SEVERITY_WARNING = 3,
0040     XML_PARSER_SEVERITY_ERROR = 4
0041 } xmlParserSeverities;
0042
0043 #ifdef LIBXML_READER_ENABLED
0044
0045 /**
0046  * Internal state values for the reader.
0047  */
0048 typedef enum {
0049     XML_TEXTREADER_MODE_INITIAL = 0,
0050     XML_TEXTREADER_MODE_INTERACTIVE = 1,
0051     XML_TEXTREADER_MODE_ERROR = 2,
0052     XML_TEXTREADER_MODE_EOF =3,
0053     XML_TEXTREADER_MODE_CLOSED = 4,
0054     XML_TEXTREADER_MODE_READING = 5
0055 } xmlTextReaderMode;
0056
0057 /**
0058  * Some common options to use with #xmlTextReaderSetParserProp, but it
0059  * is better to use xmlParserOption and the xmlReaderNewxxx and
0060  * xmlReaderForxxx APIs now.
0061  */
0062 typedef enum {
0063     /* load external DTD */
0064     XML_PARSER_LOADDTD = 1,
0065     /* use default attributes */
0066     XML_PARSER_DEFAULTATTRS = 2,
0067     /* DTD validation */
0068     XML_PARSER_VALIDATE = 3,
0069     /* substitute entities */
0070     XML_PARSER_SUBST_ENTITIES = 4
0071 } xmlParserProperties;
0072
0073 /**
0074  * Predefined constants for the different types of nodes.
0075  */
0076 typedef enum {
0077     /** unknown or error */
0078     XML_READER_TYPE_NONE = 0,
0079     /** element */
0080     XML_READER_TYPE_ELEMENT = 1,
0081     /** attribute */
0082     XML_READER_TYPE_ATTRIBUTE = 2,
0083     /** text */
0084     XML_READER_TYPE_TEXT = 3,
0085     /** CDATA section */
0086     XML_READER_TYPE_CDATA = 4,
0087     /** entity reference */
0088     XML_READER_TYPE_ENTITY_REFERENCE = 5,
0089     /** unused */
0090     XML_READER_TYPE_ENTITY = 6,
0091     /** processing instruction */
0092     XML_READER_TYPE_PROCESSING_INSTRUCTION = 7,
0093     /** comment */
0094     XML_READER_TYPE_COMMENT = 8,
0095     /** document */
0096     XML_READER_TYPE_DOCUMENT = 9,
0097     /** unused */
0098     XML_READER_TYPE_DOCUMENT_TYPE = 10,
0099     /** document fragment */
0100     XML_READER_TYPE_DOCUMENT_FRAGMENT = 11,
0101     /** notation, unused */
0102     XML_READER_TYPE_NOTATION = 12,
0103     /** whitespace */
0104     XML_READER_TYPE_WHITESPACE = 13,
0105     /** significant whitespace */
0106     XML_READER_TYPE_SIGNIFICANT_WHITESPACE = 14,
0107     /** end of element */
0108     XML_READER_TYPE_END_ELEMENT = 15,
0109     /** unused */
0110     XML_READER_TYPE_END_ENTITY = 16,
0111     /** unused */
0112     XML_READER_TYPE_XML_DECLARATION = 17
0113 } xmlReaderTypes;
0114
0115 /** xmlReader context */
0116 typedef struct _xmlTextReader xmlTextReader;
0117 typedef xmlTextReader *xmlTextReaderPtr;
0118
0119 /*
0120  * Constructors & Destructor
0121  */
0122 XMLPUBFUN xmlTextReader *
0123             xmlNewTextReader    (xmlParserInputBuffer *input,
0124                                              const char *URI);
0125 XMLPUBFUN xmlTextReader *
0126             xmlNewTextReaderFilename(const char *URI);
0127
0128 XMLPUBFUN void
0129             xmlFreeTextReader   (xmlTextReader *reader);
0130
0131 XMLPUBFUN int
0132             xmlTextReaderSetup(xmlTextReader *reader,
0133                    xmlParserInputBuffer *input, const char *URL,
0134                    const char *encoding, int options);
0135 XMLPUBFUN void
0136             xmlTextReaderSetMaxAmplification(xmlTextReader *reader,
0137                    unsigned maxAmpl);
0138 XMLPUBFUN const xmlError *
0139             xmlTextReaderGetLastError(xmlTextReader *reader);
0140
0141 /*
0142  * Iterators
0143  */
0144 XMLPUBFUN int
0145             xmlTextReaderRead   (xmlTextReader *reader);
0146
0147 #ifdef LIBXML_WRITER_ENABLED
0148 XMLPUBFUN xmlChar *
0149             xmlTextReaderReadInnerXml(xmlTextReader *reader);
0150
0151 XMLPUBFUN xmlChar *
0152             xmlTextReaderReadOuterXml(xmlTextReader *reader);
0153 #endif
0154
0155 XMLPUBFUN xmlChar *
0156             xmlTextReaderReadString (xmlTextReader *reader);
0157 XMLPUBFUN int
0158             xmlTextReaderReadAttributeValue(xmlTextReader *reader);
0159
0160 /*
0161  * Attributes of the node
0162  */
0163 XMLPUBFUN int
0164             xmlTextReaderAttributeCount(xmlTextReader *reader);
0165 XMLPUBFUN int
0166             xmlTextReaderDepth  (xmlTextReader *reader);
0167 XMLPUBFUN int
0168             xmlTextReaderHasAttributes(xmlTextReader *reader);
0169 XMLPUBFUN int
0170             xmlTextReaderHasValue(xmlTextReader *reader);
0171 XMLPUBFUN int
0172             xmlTextReaderIsDefault  (xmlTextReader *reader);
0173 XMLPUBFUN int
0174             xmlTextReaderIsEmptyElement(xmlTextReader *reader);
0175 XMLPUBFUN int
0176             xmlTextReaderNodeType   (xmlTextReader *reader);
0177 XMLPUBFUN int
0178             xmlTextReaderQuoteChar  (xmlTextReader *reader);
0179 XMLPUBFUN int
0180             xmlTextReaderReadState  (xmlTextReader *reader);
0181 XMLPUBFUN int
0182                         xmlTextReaderIsNamespaceDecl(xmlTextReader *reader);
0183
0184 XMLPUBFUN const xmlChar *
0185             xmlTextReaderConstBaseUri   (xmlTextReader *reader);
0186 XMLPUBFUN const xmlChar *
0187             xmlTextReaderConstLocalName (xmlTextReader *reader);
0188 XMLPUBFUN const xmlChar *
0189             xmlTextReaderConstName  (xmlTextReader *reader);
0190 XMLPUBFUN const xmlChar *
0191             xmlTextReaderConstNamespaceUri(xmlTextReader *reader);
0192 XMLPUBFUN const xmlChar *
0193             xmlTextReaderConstPrefix    (xmlTextReader *reader);
0194 XMLPUBFUN const xmlChar *
0195             xmlTextReaderConstXmlLang   (xmlTextReader *reader);
0196 XMLPUBFUN const xmlChar *
0197             xmlTextReaderConstString    (xmlTextReader *reader,
0198                          const xmlChar *str);
0199 XMLPUBFUN const xmlChar *
0200             xmlTextReaderConstValue (xmlTextReader *reader);
0201
0202 /*
0203  * use the Const version of the routine for
0204  * better performance and simpler code
0205  */
0206 XMLPUBFUN xmlChar *
0207             xmlTextReaderBaseUri    (xmlTextReader *reader);
0208 XMLPUBFUN xmlChar *
0209             xmlTextReaderLocalName  (xmlTextReader *reader);
0210 XMLPUBFUN xmlChar *
0211             xmlTextReaderName   (xmlTextReader *reader);
0212 XMLPUBFUN xmlChar *
0213             xmlTextReaderNamespaceUri(xmlTextReader *reader);
0214 XMLPUBFUN xmlChar *
0215             xmlTextReaderPrefix (xmlTextReader *reader);
0216 XMLPUBFUN xmlChar *
0217             xmlTextReaderXmlLang    (xmlTextReader *reader);
0218 XMLPUBFUN xmlChar *
0219             xmlTextReaderValue  (xmlTextReader *reader);
0220
0221 /*
0222  * Methods of the XmlTextReader
0223  */
0224 XMLPUBFUN int
0225             xmlTextReaderClose      (xmlTextReader *reader);
0226 XMLPUBFUN xmlChar *
0227             xmlTextReaderGetAttributeNo (xmlTextReader *reader,
0228                          int no);
0229 XMLPUBFUN xmlChar *
0230             xmlTextReaderGetAttribute   (xmlTextReader *reader,
0231                          const xmlChar *name);
0232 XMLPUBFUN xmlChar *
0233             xmlTextReaderGetAttributeNs (xmlTextReader *reader,
0234                          const xmlChar *localName,
0235                          const xmlChar *namespaceURI);
0236 XMLPUBFUN xmlParserInputBuffer *
0237             xmlTextReaderGetRemainder   (xmlTextReader *reader);
0238 XMLPUBFUN xmlChar *
0239             xmlTextReaderLookupNamespace(xmlTextReader *reader,
0240                          const xmlChar *prefix);
0241 XMLPUBFUN int
0242             xmlTextReaderMoveToAttributeNo(xmlTextReader *reader,
0243                          int no);
0244 XMLPUBFUN int
0245             xmlTextReaderMoveToAttribute(xmlTextReader *reader,
0246                          const xmlChar *name);
0247 XMLPUBFUN int
0248             xmlTextReaderMoveToAttributeNs(xmlTextReader *reader,
0249                          const xmlChar *localName,
0250                          const xmlChar *namespaceURI);
0251 XMLPUBFUN int
0252             xmlTextReaderMoveToFirstAttribute(xmlTextReader *reader);
0253 XMLPUBFUN int
0254             xmlTextReaderMoveToNextAttribute(xmlTextReader *reader);
0255 XMLPUBFUN int
0256             xmlTextReaderMoveToElement  (xmlTextReader *reader);
0257 XMLPUBFUN int
0258             xmlTextReaderNormalization  (xmlTextReader *reader);
0259 XMLPUBFUN const xmlChar *
0260             xmlTextReaderConstEncoding  (xmlTextReader *reader);
0261
0262 /*
0263  * Extensions
0264  */
0265 XMLPUBFUN int
0266             xmlTextReaderSetParserProp  (xmlTextReader *reader,
0267                          int prop,
0268                          int value);
0269 XMLPUBFUN int
0270             xmlTextReaderGetParserProp  (xmlTextReader *reader,
0271                          int prop);
0272 XMLPUBFUN xmlNode *
0273             xmlTextReaderCurrentNode    (xmlTextReader *reader);
0274
0275 XMLPUBFUN int
0276             xmlTextReaderGetParserLineNumber(xmlTextReader *reader);
0277
0278 XMLPUBFUN int
0279             xmlTextReaderGetParserColumnNumber(xmlTextReader *reader);
0280
0281 XMLPUBFUN xmlNode *
0282             xmlTextReaderPreserve   (xmlTextReader *reader);
0283 #ifdef LIBXML_PATTERN_ENABLED
0284 XMLPUBFUN int
0285             xmlTextReaderPreservePattern(xmlTextReader *reader,
0286                          const xmlChar *pattern,
0287                          const xmlChar **namespaces);
0288 #endif /* LIBXML_PATTERN_ENABLED */
0289 XMLPUBFUN xmlDoc *
0290             xmlTextReaderCurrentDoc (xmlTextReader *reader);
0291 XMLPUBFUN xmlNode *
0292             xmlTextReaderExpand     (xmlTextReader *reader);
0293 XMLPUBFUN int
0294             xmlTextReaderNext       (xmlTextReader *reader);
0295 XMLPUBFUN int
0296             xmlTextReaderNextSibling    (xmlTextReader *reader);
0297 XMLPUBFUN int
0298             xmlTextReaderIsValid    (xmlTextReader *reader);
0299 #ifdef LIBXML_RELAXNG_ENABLED
0300 XMLPUBFUN int
0301             xmlTextReaderRelaxNGValidate(xmlTextReader *reader,
0302                          const char *rng);
0303 XMLPUBFUN int
0304             xmlTextReaderRelaxNGValidateCtxt(xmlTextReader *reader,
0305                          xmlRelaxNGValidCtxt *ctxt,
0306                          int options);
0307
0308 XMLPUBFUN int
0309             xmlTextReaderRelaxNGSetSchema(xmlTextReader *reader,
0310                          xmlRelaxNG *schema);
0311 #endif
0312 #ifdef LIBXML_SCHEMAS_ENABLED
0313 XMLPUBFUN int
0314             xmlTextReaderSchemaValidate (xmlTextReader *reader,
0315                          const char *xsd);
0316 XMLPUBFUN int
0317             xmlTextReaderSchemaValidateCtxt(xmlTextReader *reader,
0318                          xmlSchemaValidCtxt *ctxt,
0319                          int options);
0320 XMLPUBFUN int
0321             xmlTextReaderSetSchema  (xmlTextReader *reader,
0322                          xmlSchema *schema);
0323 #endif
0324 XMLPUBFUN const xmlChar *
0325             xmlTextReaderConstXmlVersion(xmlTextReader *reader);
0326 XMLPUBFUN int
0327             xmlTextReaderStandalone     (xmlTextReader *reader);
0328
0329
0330 /*
0331  * Index lookup
0332  */
0333 XMLPUBFUN long
0334         xmlTextReaderByteConsumed   (xmlTextReader *reader);
0335
0336 /*
0337  * New more complete APIs for simpler creation and reuse of readers
0338  */
0339 XMLPUBFUN xmlTextReader *
0340         xmlReaderWalker     (xmlDoc *doc);
0341 XMLPUBFUN xmlTextReader *
0342         xmlReaderForDoc     (const xmlChar * cur,
0343                      const char *URL,
0344                      const char *encoding,
0345                      int options);
0346 XMLPUBFUN xmlTextReader *
0347         xmlReaderForFile    (const char *filename,
0348                      const char *encoding,
0349                      int options);
0350 XMLPUBFUN xmlTextReader *
0351         xmlReaderForMemory  (const char *buffer,
0352                      int size,
0353                      const char *URL,
0354                      const char *encoding,
0355                      int options);
0356 XMLPUBFUN xmlTextReader *
0357         xmlReaderForFd      (int fd,
0358                      const char *URL,
0359                      const char *encoding,
0360                      int options);
0361 XMLPUBFUN xmlTextReader *
0362         xmlReaderForIO      (xmlInputReadCallback ioread,
0363                      xmlInputCloseCallback ioclose,
0364                      void *ioctx,
0365                      const char *URL,
0366                      const char *encoding,
0367                      int options);
0368
0369 XMLPUBFUN int
0370         xmlReaderNewWalker  (xmlTextReader *reader,
0371                      xmlDoc *doc);
0372 XMLPUBFUN int
0373         xmlReaderNewDoc     (xmlTextReader *reader,
0374                      const xmlChar * cur,
0375                      const char *URL,
0376                      const char *encoding,
0377                      int options);
0378 XMLPUBFUN int
0379         xmlReaderNewFile    (xmlTextReader *reader,
0380                      const char *filename,
0381                      const char *encoding,
0382                      int options);
0383 XMLPUBFUN int
0384         xmlReaderNewMemory  (xmlTextReader *reader,
0385                      const char *buffer,
0386                      int size,
0387                      const char *URL,
0388                      const char *encoding,
0389                      int options);
0390 XMLPUBFUN int
0391         xmlReaderNewFd      (xmlTextReader *reader,
0392                      int fd,
0393                      const char *URL,
0394                      const char *encoding,
0395                      int options);
0396 XMLPUBFUN int
0397         xmlReaderNewIO      (xmlTextReader *reader,
0398                      xmlInputReadCallback ioread,
0399                      xmlInputCloseCallback ioclose,
0400                      void *ioctx,
0401                      const char *URL,
0402                      const char *encoding,
0403                      int options);
0404 /*
0405  * Error handling extensions
0406  */
0407 typedef void *  xmlTextReaderLocatorPtr;
0408
0409 /**
0410  * Signature of an error callback from a reader parser
0411  *
0412  * @param arg  the user argument
0413  * @param msg  the message
0414  * @param severity  the severity of the error
0415  * @param locator  a locator indicating where the error occurred
0416  */
0417 typedef void (*xmlTextReaderErrorFunc)(void *arg,
0418                            const char *msg,
0419                            xmlParserSeverities severity,
0420                            xmlTextReaderLocatorPtr locator);
0421 XMLPUBFUN int
0422         xmlTextReaderLocatorLineNumber(xmlTextReaderLocatorPtr locator);
0423 XMLPUBFUN xmlChar *
0424         xmlTextReaderLocatorBaseURI (xmlTextReaderLocatorPtr locator);
0425 XMLPUBFUN void
0426         xmlTextReaderSetErrorHandler(xmlTextReader *reader,
0427                      xmlTextReaderErrorFunc f,
0428                      void *arg);
0429 XMLPUBFUN void
0430         xmlTextReaderSetStructuredErrorHandler(xmlTextReader *reader,
0431                            xmlStructuredErrorFunc f,
0432                            void *arg);
0433 XMLPUBFUN void
0434         xmlTextReaderGetErrorHandler(xmlTextReader *reader,
0435                      xmlTextReaderErrorFunc *f,
0436                      void **arg);
0437
0438 XMLPUBFUN void
0439         xmlTextReaderSetResourceLoader(xmlTextReader *reader,
0440                        xmlResourceLoader loader,
0441                        void *data);
0442
0443 #endif /* LIBXML_READER_ENABLED */
0444
0445 #ifdef __cplusplus
0446 }
0447 #endif
0448
0449 #endif /* __XML_XMLREADER_H__ */
0450