Prev Up Home Next libxml2 Reference Manual

xmlIO

xmlIO - interface for the I/O interfaces used by the parser

interface for the I/O interfaces used by the parser

Author(s): Daniel Veillard

Synopsis

xmlOutputBufferPtr	xmlAllocOutputBuffer	(xmlCharEncodingHandlerPtr encoder);
xmlParserInputBufferPtr	xmlAllocParserInputBuffer	(xmlCharEncoding enc);
int	xmlCheckFilename		(const char * path);
xmlParserInputPtr	xmlCheckHTTPInput	(xmlParserCtxtPtr ctxt, 
						 xmlParserInputPtr ret);
void	xmlCleanupInputCallbacks	(void);
void	xmlCleanupOutputCallbacks	(void);
int	xmlFileClose			(void * context);
int	xmlFileMatch			(const char * filename);
void *	xmlFileOpen			(const char * filename);
int	xmlFileRead			(void * context, 
					 char * buffer, 
					 int len);
void	xmlFreeParserInputBuffer	(xmlParserInputBufferPtr in);
int	xmlIOFTPClose			(void * context);
int	xmlIOFTPMatch			(const char * filename);
void *	xmlIOFTPOpen			(const char * filename);
int	xmlIOFTPRead			(void * context, 
					 char * buffer, 
					 int len);
int	xmlIOHTTPClose			(void * context);
int	xmlIOHTTPMatch			(const char * filename);
void *	xmlIOHTTPOpen			(const char * filename);
void *	xmlIOHTTPOpenW			(const char * post_uri, 
					 int compression);
int	xmlIOHTTPRead			(void * context, 
					 char * buffer, 
					 int len);
typedef int xmlInputCloseCallback		(void * context);
typedef int xmlInputMatchCallback		(char const * filename);
typedef void * xmlInputOpenCallback		(char const * filename);
typedef int xmlInputReadCallback		(void * context, 
					 char * buffer, 
					 int len);
xmlParserInputPtr	xmlNoNetExternalEntityLoader	(const char * URL, 
							 const char * ID, 
							 xmlParserCtxtPtr ctxt);
xmlChar *	xmlNormalizeWindowsPath	(const xmlChar * path);
int	xmlOutputBufferClose		(xmlOutputBufferPtr out);
xmlOutputBufferPtr	xmlOutputBufferCreateBuffer	(xmlBufferPtr buffer, 
							 xmlCharEncodingHandlerPtr encoder);
xmlOutputBufferPtr	xmlOutputBufferCreateFd	(int fd, 
						 xmlCharEncodingHandlerPtr encoder);
xmlOutputBufferPtr	xmlOutputBufferCreateFile	(FILE * file, 
							 xmlCharEncodingHandlerPtr encoder);
xmlOutputBufferPtr	xmlOutputBufferCreateFilename	(const char * URI, 
							 xmlCharEncodingHandlerPtr encoder, 
							 int compression);
xmlOutputBufferPtr	xmlOutputBufferCreateIO	(xmlOutputWriteCallback iowrite, 
						 xmlOutputCloseCallback ioclose, 
						 void * ioctx, 
						 xmlCharEncodingHandlerPtr encoder);
int	xmlOutputBufferFlush		(xmlOutputBufferPtr out);
const xmlChar *	xmlOutputBufferGetContent	(xmlOutputBufferPtr out);
size_t	xmlOutputBufferGetSize		(xmlOutputBufferPtr out);
int	xmlOutputBufferWrite		(xmlOutputBufferPtr out, 
					 int len, 
					 const char * buf);
int	xmlOutputBufferWriteEscape	(xmlOutputBufferPtr out, 
					 const xmlChar * str, 
					 xmlCharEncodingOutputFunc escaping);
int	xmlOutputBufferWriteString	(xmlOutputBufferPtr out, 
					 const char * str);
typedef int xmlOutputCloseCallback		(void * context);
typedef int xmlOutputMatchCallback		(char const * filename);
typedef void * xmlOutputOpenCallback		(char const * filename);
typedef int xmlOutputWriteCallback		(void * context, 
					 const char * buffer, 
					 int len);
char *	xmlParserGetDirectory		(const char * filename);
xmlParserInputBufferPtr	xmlParserInputBufferCreateFd	(int fd, 
							 xmlCharEncoding enc);
xmlParserInputBufferPtr	xmlParserInputBufferCreateFile	(FILE * file, 
							 xmlCharEncoding enc);
xmlParserInputBufferPtr	xmlParserInputBufferCreateFilename	(const char * URI, 
							 xmlCharEncoding enc);
xmlParserInputBufferPtr	xmlParserInputBufferCreateIO	(xmlInputReadCallback ioread, 
							 xmlInputCloseCallback ioclose, 
							 void * ioctx, 
							 xmlCharEncoding enc);
xmlParserInputBufferPtr	xmlParserInputBufferCreateMem	(const char * mem, 
							 int size, 
							 xmlCharEncoding enc);
xmlParserInputBufferPtr	xmlParserInputBufferCreateStatic	(const char * mem, 
							 int size, 
							 xmlCharEncoding enc);
int	xmlParserInputBufferGrow	(xmlParserInputBufferPtr in, 
					 int len);
int	xmlParserInputBufferPush	(xmlParserInputBufferPtr in, 
					 int len, 
					 const char * buf);
int	xmlParserInputBufferRead	(xmlParserInputBufferPtr in, 
					 int len);
int	xmlPopInputCallbacks		(void);
int	xmlPopOutputCallbacks		(void);
void	xmlRegisterDefaultInputCallbacks	(void);
void	xmlRegisterDefaultOutputCallbacks	(void);
void	xmlRegisterHTTPPostCallbacks	(void);
int	xmlRegisterInputCallbacks	(xmlInputMatchCallback matchFunc, 
					 xmlInputOpenCallback openFunc, 
					 xmlInputReadCallback readFunc, 
					 xmlInputCloseCallback closeFunc);
int	xmlRegisterOutputCallbacks	(xmlOutputMatchCallback matchFunc, 
					 xmlOutputOpenCallback openFunc, 
					 xmlOutputWriteCallback writeFunc, 
					 xmlOutputCloseCallback closeFunc);

Description

Details

Function type xmlInputCloseCallback

int	xmlInputCloseCallback		(void * context)

Callback used in the I/O Input API to close the resource

context: an Input context
Returns: 0 or -1 in case of error

Function type xmlInputMatchCallback

int	xmlInputMatchCallback		(char const * filename)

Callback used in the I/O Input API to detect if the current handler can provide input functionality for this resource.

filename: the filename or URI
Returns: 1 if yes and 0 if another Input module should be used

Function type xmlInputOpenCallback

void *	xmlInputOpenCallback		(char const * filename)

Callback used in the I/O Input API to open the resource

filename: the filename or URI
Returns: an Input context or NULL in case or error

Function type xmlInputReadCallback

int	xmlInputReadCallback		(void * context, 
					 char * buffer, 
					 int len)

Callback used in the I/O Input API to read the resource

context: an Input context
buffer: the buffer to store data read
len: the length of the buffer in bytes
Returns: the number of bytes read or -1 in case of error

Function type xmlOutputCloseCallback

int	xmlOutputCloseCallback		(void * context)

Callback used in the I/O Output API to close the resource

context: an Output context
Returns: 0 or -1 in case of error

Function type xmlOutputMatchCallback

int	xmlOutputMatchCallback		(char const * filename)

Callback used in the I/O Output API to detect if the current handler can provide output functionality for this resource.

filename: the filename or URI
Returns: 1 if yes and 0 if another Output module should be used

Function type xmlOutputOpenCallback

void *	xmlOutputOpenCallback		(char const * filename)

Callback used in the I/O Output API to open the resource

filename: the filename or URI
Returns: an Output context or NULL in case or error

Function type xmlOutputWriteCallback

int	xmlOutputWriteCallback		(void * context, 
					 const char * buffer, 
					 int len)

Callback used in the I/O Output API to write to the resource

context: an Output context
buffer: the buffer of data to write
len: the length of the buffer in bytes
Returns: the number of bytes written or -1 in case of error

xmlAllocOutputBuffer ()

xmlOutputBufferPtr	xmlAllocOutputBuffer	(xmlCharEncodingHandlerPtr encoder)

Create a buffered parser output

encoder: the encoding converter or NULL
Returns: the new parser output or NULL

xmlAllocParserInputBuffer ()

xmlParserInputBufferPtr	xmlAllocParserInputBuffer	(xmlCharEncoding enc)

Create a buffered parser input for progressive parsing

enc: the charset encoding if known
Returns: the new parser input or NULL

xmlCheckFilename ()

int	xmlCheckFilename		(const char * path)

function checks to see if @path is a valid source (file, socket...) for XML. if stat is not available on the target machine,

path: the path to check
Returns: 1. if stat fails, returns 0 (if calling stat on the filename fails, it can't be right). if stat succeeds and the file is a directory, returns 2. otherwise returns 1.

xmlCheckHTTPInput ()

xmlParserInputPtr	xmlCheckHTTPInput	(xmlParserCtxtPtr ctxt, 
						 xmlParserInputPtr ret)

Check an input in case it was created from an HTTP stream, in that case it will handle encoding and update of the base URL in case of redirection. It also checks for HTTP errors in which case the input is cleanly freed up and an appropriate error is raised in context

ctxt: an XML parser context
ret: an XML parser input
Returns: the input or NULL in case of HTTP error.

xmlCleanupInputCallbacks ()

void	xmlCleanupInputCallbacks	(void)

clears the entire input callback table. this includes the compiled-in I/O.

xmlCleanupOutputCallbacks ()

void	xmlCleanupOutputCallbacks	(void)

clears the entire output callback table. this includes the compiled-in I/O callbacks.

xmlFileClose ()

int	xmlFileClose			(void * context)

Close an I/O channel

context: the I/O context
Returns: 0 or -1 in case of error

xmlFileMatch ()

int	xmlFileMatch			(const char * filename)

input from FILE *

filename: the URI for matching
Returns: 1 if matches, 0 otherwise

xmlFileOpen ()

void *	xmlFileOpen			(const char * filename)

Wrapper around xmlFileOpen_real that try it with an unescaped version of @filename, if this fails fallback to @filename

filename: the URI for matching
Returns: a handler or NULL in case or failure

xmlFileRead ()

int	xmlFileRead			(void * context, 
					 char * buffer, 
					 int len)

Read @len bytes to @buffer from the I/O channel.

context: the I/O context
buffer: where to drop data
len: number of bytes to write
Returns: the number of bytes written or < 0 in case of failure

xmlFreeParserInputBuffer ()

void	xmlFreeParserInputBuffer	(xmlParserInputBufferPtr in)

Free up the memory used by a buffered parser input

in: a buffered parser input

xmlIOFTPClose ()

int	xmlIOFTPClose			(void * context)

Close an FTP I/O channel

context: the I/O context
Returns: 0

xmlIOFTPMatch ()

int	xmlIOFTPMatch			(const char * filename)

check if the URI matches an FTP one

filename: the URI for matching
Returns: 1 if matches, 0 otherwise

xmlIOFTPOpen ()

void *	xmlIOFTPOpen			(const char * filename)

open an FTP I/O channel

filename: the URI for matching
Returns: an I/O context or NULL in case of error

xmlIOFTPRead ()

int	xmlIOFTPRead			(void * context, 
					 char * buffer, 
					 int len)

Read @len bytes to @buffer from the I/O channel.

context: the I/O context
buffer: where to drop data
len: number of bytes to write
Returns: the number of bytes written

xmlIOHTTPClose ()

int	xmlIOHTTPClose			(void * context)

Close an HTTP I/O channel

context: the I/O context
Returns: 0

xmlIOHTTPMatch ()

int	xmlIOHTTPMatch			(const char * filename)

check if the URI matches an HTTP one

filename: the URI for matching
Returns: 1 if matches, 0 otherwise

xmlIOHTTPOpen ()

void *	xmlIOHTTPOpen			(const char * filename)

open an HTTP I/O channel

filename: the URI for matching
Returns: an I/O context or NULL in case of error

xmlIOHTTPOpenW ()

void *	xmlIOHTTPOpenW			(const char * post_uri, 
					 int compression)

Open a temporary buffer to collect the document for a subsequent HTTP POST request. Non-static as is called from the output buffer creation routine.

post_uri: The destination URI for the document
compression: The compression desired for the document.
Returns: an I/O context or NULL in case of error.

xmlIOHTTPRead ()

int	xmlIOHTTPRead			(void * context, 
					 char * buffer, 
					 int len)

Read @len bytes to @buffer from the I/O channel.

context: the I/O context
buffer: where to drop data
len: number of bytes to write
Returns: the number of bytes written

xmlNoNetExternalEntityLoader ()

xmlParserInputPtr	xmlNoNetExternalEntityLoader	(const char * URL, 
							 const char * ID, 
							 xmlParserCtxtPtr ctxt)

A specific entity loader disabling network accesses, though still allowing local catalog accesses for resolution.

URL: the URL for the entity to load
ID: the System ID for the entity to load
ctxt: the context in which the entity is called or NULL
Returns: a new allocated xmlParserInputPtr, or NULL.

xmlNormalizeWindowsPath ()

xmlChar *	xmlNormalizeWindowsPath	(const xmlChar * path)

This function is obsolete. Please see xmlURIFromPath in uri.c for a better solution.

path: the input file path
Returns: a canonicalized version of the path

xmlOutputBufferClose ()

int	xmlOutputBufferClose		(xmlOutputBufferPtr out)

flushes and close the output I/O channel and free up all the associated resources

out: a buffered output
Returns: the number of byte written or -1 in case of error.

xmlOutputBufferCreateBuffer ()

xmlOutputBufferPtr	xmlOutputBufferCreateBuffer	(xmlBufferPtr buffer, 
							 xmlCharEncodingHandlerPtr encoder)

Create a buffered output for the progressive saving to a xmlBuffer

buffer: a xmlBufferPtr
encoder: the encoding converter or NULL
Returns: the new parser output or NULL

xmlOutputBufferCreateFd ()

xmlOutputBufferPtr	xmlOutputBufferCreateFd	(int fd, 
						 xmlCharEncodingHandlerPtr encoder)

Create a buffered output for the progressive saving to a file descriptor

fd: a file descriptor number
encoder: the encoding converter or NULL
Returns: the new parser output or NULL

xmlOutputBufferCreateFile ()

xmlOutputBufferPtr	xmlOutputBufferCreateFile	(FILE * file, 
							 xmlCharEncodingHandlerPtr encoder)

Create a buffered output for the progressive saving to a FILE * buffered C I/O

file: a FILE*
encoder: the encoding converter or NULL
Returns: the new parser output or NULL

xmlOutputBufferCreateFilename ()

xmlOutputBufferPtr	xmlOutputBufferCreateFilename	(const char * URI, 
							 xmlCharEncodingHandlerPtr encoder, 
							 int compression)

Create a buffered output for the progressive saving of a file If filename is "-' then we use stdout as the output. Automatic support for ZLIB/Compress compressed document is provided by default if found at compile-time. TODO: currently if compression is set, the library only support writing to a local file.

URI: a C string containing the URI or filename
encoder: the encoding converter or NULL
compression: the compression ration (0 none, 9 max).
Returns: the new output or NULL

xmlOutputBufferCreateIO ()

xmlOutputBufferPtr	xmlOutputBufferCreateIO	(xmlOutputWriteCallback iowrite, 
						 xmlOutputCloseCallback ioclose, 
						 void * ioctx, 
						 xmlCharEncodingHandlerPtr encoder)

Create a buffered output for the progressive saving to an I/O handler

iowrite: an I/O write function
ioclose: an I/O close function
ioctx: an I/O handler
encoder: the charset encoding if known
Returns: the new parser output or NULL

xmlOutputBufferFlush ()

int	xmlOutputBufferFlush		(xmlOutputBufferPtr out)

flushes the output I/O channel

out: a buffered output
Returns: the number of byte written or -1 in case of error.

xmlOutputBufferGetContent ()

const xmlChar *	xmlOutputBufferGetContent	(xmlOutputBufferPtr out)

Gives a pointer to the data currently held in the output buffer

out: an xmlOutputBufferPtr
Returns: a pointer to the data or NULL in case of error

xmlOutputBufferGetSize ()

size_t	xmlOutputBufferGetSize		(xmlOutputBufferPtr out)

Gives the length of the data currently held in the output buffer

out: an xmlOutputBufferPtr
Returns: 0 in case or error or no data is held, the size otherwise

xmlOutputBufferWrite ()

int	xmlOutputBufferWrite		(xmlOutputBufferPtr out, 
					 int len, 
					 const char * buf)

Write the content of the array in the output I/O buffer This routine handle the I18N transcoding from internal UTF-8 The buffer is lossless, i.e. will store in case of partial or delayed writes.

out: a buffered parser output
len: the size in bytes of the array.
buf: an char array
Returns: the number of chars immediately written, or -1 in case of error.

xmlOutputBufferWriteEscape ()

int	xmlOutputBufferWriteEscape	(xmlOutputBufferPtr out, 
					 const xmlChar * str, 
					 xmlCharEncodingOutputFunc escaping)

Write the content of the string in the output I/O buffer This routine escapes the characters and then handle the I18N transcoding from internal UTF-8 The buffer is lossless, i.e. will store in case of partial or delayed writes.

out: a buffered parser output
str: a zero terminated UTF-8 string
escaping: an optional escaping function (or NULL)
Returns: the number of chars immediately written, or -1 in case of error.

xmlOutputBufferWriteString ()

int	xmlOutputBufferWriteString	(xmlOutputBufferPtr out, 
					 const char * str)

Write the content of the string in the output I/O buffer This routine handle the I18N transcoding from internal UTF-8 The buffer is lossless, i.e. will store in case of partial or delayed writes.

out: a buffered parser output
str: a zero terminated C string
Returns: the number of chars immediately written, or -1 in case of error.

xmlParserGetDirectory ()

char *	xmlParserGetDirectory		(const char * filename)

lookup the directory for that file

filename: the path to a file
Returns: a new allocated string containing the directory, or NULL.

xmlParserInputBufferCreateFd ()

xmlParserInputBufferPtr	xmlParserInputBufferCreateFd	(int fd, 
							 xmlCharEncoding enc)

Create a buffered parser input for the progressive parsing for the input from a file descriptor

fd: a file descriptor number
enc: the charset encoding if known
Returns: the new parser input or NULL

xmlParserInputBufferCreateFile ()

xmlParserInputBufferPtr	xmlParserInputBufferCreateFile	(FILE * file, 
							 xmlCharEncoding enc)

Create a buffered parser input for the progressive parsing of a FILE * buffered C I/O

file: a FILE*
enc: the charset encoding if known
Returns: the new parser input or NULL

xmlParserInputBufferCreateFilename ()

xmlParserInputBufferPtr	xmlParserInputBufferCreateFilename	(const char * URI, 
							 xmlCharEncoding enc)

Create a buffered parser input for the progressive parsing of a file If filename is "-' then we use stdin as the input. Automatic support for ZLIB/Compress compressed document is provided by default if found at compile-time. Do an encoding check if enc == XML_CHAR_ENCODING_NONE

URI: a C string containing the URI or filename
enc: the charset encoding if known
Returns: the new parser input or NULL

xmlParserInputBufferCreateIO ()

xmlParserInputBufferPtr	xmlParserInputBufferCreateIO	(xmlInputReadCallback ioread, 
							 xmlInputCloseCallback ioclose, 
							 void * ioctx, 
							 xmlCharEncoding enc)

Create a buffered parser input for the progressive parsing for the input from an I/O handler

ioread: an I/O read function
ioclose: an I/O close function
ioctx: an I/O handler
enc: the charset encoding if known
Returns: the new parser input or NULL

xmlParserInputBufferCreateMem ()

xmlParserInputBufferPtr	xmlParserInputBufferCreateMem	(const char * mem, 
							 int size, 
							 xmlCharEncoding enc)

Create a buffered parser input for the progressive parsing for the input from a memory area.

mem: the memory input
size: the length of the memory block
enc: the charset encoding if known
Returns: the new parser input or NULL

xmlParserInputBufferCreateStatic ()

xmlParserInputBufferPtr	xmlParserInputBufferCreateStatic	(const char * mem, 
							 int size, 
							 xmlCharEncoding enc)

DEPRECATED: Use xmlParserInputBufferCreateMem.

mem: the memory input
size: the length of the memory block
enc: the charset encoding if known
Returns: the new parser input or NULL

xmlParserInputBufferGrow ()

int	xmlParserInputBufferGrow	(xmlParserInputBufferPtr in, 
					 int len)

Grow up the content of the input buffer, the old data are preserved This routine handle the I18N transcoding to internal UTF-8 This routine is used when operating the parser in normal (pull) mode TODO: one should be able to remove one extra copy by copying directly onto in->buffer or in->raw

in: a buffered parser input
len: indicative value of the amount of chars to read
Returns: the number of chars read and stored in the buffer, or -1 in case of error.

xmlParserInputBufferPush ()

int	xmlParserInputBufferPush	(xmlParserInputBufferPtr in, 
					 int len, 
					 const char * buf)

Push the content of the arry in the input buffer This routine handle the I18N transcoding to internal UTF-8 This is used when operating the parser in progressive (push) mode.

in: a buffered parser input
len: the size in bytes of the array.
buf: an char array
Returns: the number of chars read and stored in the buffer, or -1 in case of error.

xmlParserInputBufferRead ()

int	xmlParserInputBufferRead	(xmlParserInputBufferPtr in, 
					 int len)

Refresh the content of the input buffer, the old data are considered consumed This routine handle the I18N transcoding to internal UTF-8

in: a buffered parser input
len: indicative value of the amount of chars to read
Returns: the number of chars read and stored in the buffer, or -1 in case of error.

xmlPopInputCallbacks ()

int	xmlPopInputCallbacks		(void)

Clear the top input callback from the input stack. this includes the compiled-in I/O.

Returns: the number of input callback registered or -1 in case of error.

xmlPopOutputCallbacks ()

int	xmlPopOutputCallbacks		(void)

Remove the top output callbacks from the output stack. This includes the compiled-in I/O.

Returns: the number of output callback registered or -1 in case of error.

xmlRegisterDefaultInputCallbacks ()

void	xmlRegisterDefaultInputCallbacks	(void)

Registers the default compiled-in I/O handlers.

xmlRegisterDefaultOutputCallbacks ()

void	xmlRegisterDefaultOutputCallbacks	(void)

Registers the default compiled-in I/O handlers.

xmlRegisterHTTPPostCallbacks ()

void	xmlRegisterHTTPPostCallbacks	(void)

By default, libxml submits HTTP output requests using the "PUT" method. Calling this method changes the HTTP output method to use the "POST" method instead.

xmlRegisterInputCallbacks ()

int	xmlRegisterInputCallbacks	(xmlInputMatchCallback matchFunc, 
					 xmlInputOpenCallback openFunc, 
					 xmlInputReadCallback readFunc, 
					 xmlInputCloseCallback closeFunc)

Register a new set of I/O callback for handling parser input.

matchFunc: the xmlInputMatchCallback
openFunc: the xmlInputOpenCallback
readFunc: the xmlInputReadCallback
closeFunc: the xmlInputCloseCallback
Returns: the registered handler number or -1 in case of error

xmlRegisterOutputCallbacks ()

int	xmlRegisterOutputCallbacks	(xmlOutputMatchCallback matchFunc, 
					 xmlOutputOpenCallback openFunc, 
					 xmlOutputWriteCallback writeFunc, 
					 xmlOutputCloseCallback closeFunc)

Register a new set of I/O callback for handling output.

matchFunc: the xmlOutputMatchCallback
openFunc: the xmlOutputOpenCallback
writeFunc: the xmlOutputWriteCallback
closeFunc: the xmlOutputCloseCallback
Returns: the registered handler number or -1 in case of error