/*************************************************************************** files.h - define file related functions ------------------- begin : Sat Nov 10 2001 copyright : (C) 2001 by Keith Isdale email : k_isdale@tpg.com.au ***************************************************************************/ /*************************************************************************** * * * This program is free software; you can redistribute it and/or modify * * it under the terms of the GNU General Public License as published by * * the Free Software Foundation; either version 2 of the License, or * * (at your option) any later version. * * * ***************************************************************************/ #ifndef FILES_H #define FILES_H #ifndef BUILD_DOCS #include "search.h" #include "arraylist.h" #endif #ifdef USE_KDE_DOCS /** * Provide a file support * * @short file support * * @author Keith Isdale */ #endif #ifdef HAVE_UNISTD_H #include /* need chdir function */ #endif #ifdef __cplusplus extern "C" { #endif extern FILE *terminalIO; #define XSLDBG_XML_NAMESPACE \ (const xmlChar *) "http://xsldbg.sourceforge.net/namespace" typedef struct _entityInfo entityInfo; typedef entityInfo *entityInfoPtr; struct _entityInfo { xmlChar *SystemID; xmlChar *PublicID; }; /* how many lines do we print before pausing when * performing "more" on a UTF-8 file. See function filesMoreFile */ #define FILES_NO_LINES 20 /* Define the types of file names that we are intested in when creating * search results */ #ifndef USE_KDOC typedef enum { FILES_SEARCHINPUT, FILES_SEARCHXSL, FILES_SEARCHRESULT } FilesSearchFileNameEnum; #else /* keep kdoc happy */ enum FilesSearchFileNameEnum { FILES_SEARCHINPUT, FILES_SEARCHXSL, FILES_SEACHRESULT }; #endif /*----------------------------------------------------------- General function for working with files -----------------------------------------------------------*/ #ifdef USE_GNOME_DOCS /** * filesEntityRef : * @ent : Is valid as provided by libxslt * @firstNode : Is valid * @lastNode : Is Valid * * Fixes the nodes from firstNode to lastNode so that debugging can occur */ #else #ifdef USE_KDE_DOCS /** * Fixes the nodes from firstNode to lastNode so that debugging can occur * * @param uri Is valid as provided by libxslt * @param firstNode Is valid * @param lastNode Is Valid */ #endif #endif void filesEntityRef(xmlEntityPtr ent, xmlNodePtr firstNode, xmlNodePtr lastNode); #ifdef USE_GNOME_DOCS /** * filesEntityList: * * Return the list entity names used for documents loaded * * Returns The list entity names used for documents loaded */ #else #ifdef USE_KDE_DOCS /** * Return the list entity names used for documents loaded * * @returns The list entity names used for documents loaded */ #endif #endif arrayListPtr filesEntityList(void); #ifdef USE_GNOME_DOCS /** * filesSetBaseUri: * @node : Is valid and has a doc parent * @uri : Is Valid * * Set the base uri for this node. Function is used when xml file * has external entities in its DTD * * Returns 1 if successful, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Set the base uri for this node. Function is used when xml file * has external entities in its DTD * * @param node Is valid and has a doc parent * @param uri Is Valid * * @returns 1 if successful, * 0 otherwise */ #endif #endif int filesSetBaseUri(xmlNodePtr node, const xmlChar * uri); #ifdef USE_GNOME_DOCS /** * filesGetBaseUri: * @node : Is valid and has a doc parent * * Get a copy of the base uri for this node. Function is most usefull * used when xml file has external entities in its DTD * * Returns the a copy of the base uri for this node, * NULL otherwise */ #else #ifdef USE_KDE_DOCS /** * Get a copy of the base uri for this node. Function is most usefull * used when xml file has external entities in its DTD * * @param node : Is valid and has a doc parent * * @returns The a copy of the base uri for this node, * NULL otherwise */ #endif #endif xmlChar *filesGetBaseUri(xmlNodePtr node); #ifdef USE_GNOME_DOCS /** * filesTempFileName: * @fleNumber : Number of temp file required * where @fileNumber is * 0 : file name used by cat command * 1 : file name used by profiling output * * Return the name of tempfile requirested * * This is a platform specific interface * * Returns The name of temp file to be used for temporary results if sucessful, * NULL otherwise */ #else #ifdef USE_KDE_DOCS /** * Return the name of tempfile requested. * @param fleNumber : Number of temp file required * where @p fileNumber is * 0 : file name used by cat command * 1 : file name used by profiling output * * This is a platform specific interface * * Returns The name of temp file to be used for temporary results if sucessful, * NULL otherwise */ #endif #endif const char *filesTempFileName(int fileNumber); #ifdef USE_GNOME_DOCS /** * filesLoadCatalogs: * * Load the catalogs specifed by OPTIONS_CATALOG_NAMES if * OPTIONS_CATALOGS is enabled * * Returns 1 if sucessful * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Load the catalogs specifed by OPTIONS_CATALOG_NAMES if * OPTIONS_CATALOGS is enabled * * @returns 1 if sucessful * 0 otherwise */ #endif #endif int filesLoadCatalogs(void); #ifdef USE_GNOME_DOCS /** * filesEncode: * @text: Is valid, text to translate from UTF-8, * * Return A string of converted @text * * Returns A string of converted @text, may be NULL */ #else #ifdef USE_KDE_DOCS /** * Return A string of converted @text * * @param text Is valid, text to translate from UTF-8, * * Returns A string of converted @text, may be NULL */ #endif #endif xmlChar *filesEncode(const xmlChar * text); #ifdef USE_GNOME_DOCS /** * filesDeccode: * @text: Is valid, text to translate from current encoding to UTF-8, * * Return A string of converted @text * * Returns A string of converted @text, may be NULL */ #else #ifdef USE_KDE_DOCS /** * Return A string of converted @text * * @param test Is valid, text to translate from current encoding to UTF-8, * * Returns A string of converted @text, may be NULL */ #endif #endif xmlChar *filesDecode(const xmlChar * text); #ifdef USE_GNOME_DOCS /** * filesSetEncoding: * @encoding : Is a valid encoding supported by the iconv library or NULL * * Opens encoding for all standard output to @encoding. If @encoding * is NULL then close current encoding and use UTF-8 as output encoding * * Returns 1 if successful in setting the encoding of all standard output * to @encoding * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Opens encoding for all standard output to @p encoding. If @p encoding * is NULL then close current encoding and use UTF-8 as output encoding * * @param encoding Is a valid encoding supported by the iconv library or NULL * * Returns 1 if successful in setting the encoding of all standard output * to @p encoding * 0 otherwise */ #endif #endif int filesSetEncoding(const char *encoding); #ifndef USE_KDOC /* used by filesLoadXmlFile, filesFreeXmlFile functions */ typedef enum { FILES_XMLFILE_TYPE = 100, /* pick a unique starting point */ FILES_SOURCEFILE_TYPE, FILES_TEMPORARYFILE_TYPE } FileTypeEnum; #else /* used by filesLoadXmlFile, filesFreeXmlFile functions */ enum FileTypeEnum { FILES_XMLFILE_TYPE = 100, /* pick a unique starting point */ FILES_SOURCEFILE_TYPE, FILES_TEMPORARYFILE_TYPE }; #endif #ifdef USE_GNOME_DOCS /** * openTerminal * @device: terminal to redirect i/o to , will not work under win32 * * Open communications to the terminal device @device * Returns 1 if sucessful * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Open communications to the terminal device @p device * * @param device Terminal to redirect i/o to , will not work under win32 * * @returns 1 if sucessful * 0 otherwise */ #endif #endif int openTerminal(xmlChar * device); #ifdef USE_GNOME_DOCS /** * guessStyleSheetName: * @searchInf : Is valid * * Try to find a matching stylesheet name * Sets the values in @searchinf depending on outcome of search */ #else #ifdef USE_KDE_DOCS /** * Try to find a matching stylesheet name * Sets the values in @p searchinf depending on outcome of search * * @param searchInf Is valid */ #endif #endif void guessStylesheetName(searchInfoPtr searchInf); #ifdef USE_GNOME_DOCS /** * stylePath: * * Returns the base path for the top stylesheet ie * ie URL minus the actual file name */ #else #ifdef USE_KDE_DOCS /** * Return the base path for the top stylesheet ie * ie URL minus the actual file name * * @returns The base path for the top stylesheet ie * ie URL minus the actual file name */ #endif #endif xmlChar *stylePath(void); #ifdef USE_GNOME_DOCS /** * workingPath: * * Return the working directory as set by changeDir function */ #else #ifdef USE_KDE_DOCS /** * Return the working directory as set by changeDir function * * @return the working directory as set by changeDir function */ #endif #endif xmlChar *workingPath(void); #ifdef USE_GNOME_DOCS /** * changeDir: * @path : path to adopt as new working directory * * Change working directory to path * * Returns 1 on success, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Change working directory to path * * @param path The operating system path(directory) to adopt as * new working directory * * @returns 1 on success, * 0 otherwise */ #endif #endif int changeDir(const xmlChar * path); #ifdef USE_GNOME_DOCS /** * filesLoadXmlFile: * @path : xml file to load * @fileType : A valid FileTypeEnum * * Load specified file type, freeing any memory previously used * * Returns 1 on success, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Load specified file type, freeing any memory previously used * * @returns 1 on success, * 0 otherwise * * @param path The xml file to load * @param fileType A valid FileTypeEnum */ #endif #endif int filesLoadXmlFile(const xmlChar * path, FileTypeEnum fileType); #ifdef USE_GNOME_DOCS /** * filesFreeXmlFile: * @fileType : A valid FileTypeEnum * * Free memory associated with the xml file * * Returns 1 on success, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Free memory associated with the xml file * * @returns 1 on success, * 0 otherwise * * @param fileType : A valid FileTypeEnum */ #endif #endif int filesFreeXmlFile(FileTypeEnum fileType); #ifdef USE_GNOME_DOCS /** * filesGetStylesheet: * * Return the topmost stylesheet * * Returns non-null on success, * NULL otherwise */ #else #ifdef USE_KDE_DOCS /** * Return the topmost stylesheet * * @returns Non-null on success, * NULL otherwise */ #endif #endif xsltStylesheetPtr filesGetStylesheet(void); #ifdef USE_GNOME_DOCS /** * filesGetTemporaryDoc: * * Return the current "temporary" document * * Returns the current "temporary" document */ #else #ifdef USE_KDE_DOCS /** * Return the current "temporary" document * * @returns non-null on success, * NULL otherwise */ #endif #endif xmlDocPtr filesGetTemporaryDoc(void); #ifdef USE_GNOME_DOCS /** * filesGetMainDoc: * * Returns the main docment */ #else #ifdef USE_KDE_DOCS /** * Return the main docment * * @returns the main document */ #endif #endif xmlDocPtr filesGetMainDoc(void); #ifdef USE_GNOME_DOCS /** * filesReloaded: * @reloaded : if = -1 then ignore @reloaded * otherwise change the status of files to value of @reloaded * * Returns 1 if stylesheet or its xml data file has been "flaged" as reloaded, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * @returns 1 if stylesheet or its xml data file has been "flaged" as reloaded, * 0 otherwise * * @param reloaded If = -1 then ignore @p reloaded * otherwise change the status of files to value of @p reloaded */ #endif #endif int filesReloaded(int reloaded); #ifdef USE_GNOME_DOCS /** * filesInit: * * Initialize the file module * Returns 1 on success, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Initialize the file module * * @returns 1 on success, * 0 otherwise */ #endif #endif int filesInit(void); #ifdef USE_GNOME_DOCS /** * filesFree: * * Free memory used by file related structures */ #else #ifdef USE_KDE_DOCS /** * Free memory used by file related structures */ #endif #endif void filesFree(void); #ifdef USE_GNOME_DOCS /** * filesIsSourceFile: * @fileName : Is valid * * Test if filename could be a stylesheet * * Returns true if @name has the ".xsl" extension */ #else #ifdef USE_KDE_DOCS /** * Test if filename could be a stylesheet * * @returns True if @name has the ".xsl" extension * * @param fileName Is valid */ #endif #endif int filesIsSourceFile(xmlChar * fileName); #ifdef USE_GNOME_DOCS /** * filesMoreFile: * @fileName : May be NULL * @file : May be NULL * * Do a "more" like print of file specified by @fileName OR * @file. If both are provided @file will be used. The content * of file chosen must be in UTF-8, and will be printed in * the current encoding selected.The function will pause output * after FILES_NO_LINES lines have been printed waiting for * user to enter "q" to quit or any other text to continue. * * Returns 1 if successful, * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Do a "more" like print of file specified by @fileName OR * @file. If both are provided @file will be used. The content * of file chosen must be in UTF-8, and will be printed in * the current encoding selected. The function will pause output * after FILES_NO_LINES lines have been printed waiting for * user to enter "q" to quit or any other text to continue. * * @returns 1 if successful, * 0 otherwise * * @param fileName May be NULL * @param file May be NULL * */ #endif #endif int filesMoreFile(const xmlChar * fileName, FILE * file); #ifdef USE_GNOME_DOCS /** * filesSearchResultsPath: * * Get the base path to be used for storing search results * * Returns The base path to be used for storing search results */ #else #ifdef USE_KDE_DOCS /** * Get the base path to be used for storing search results * * @returns The base path to be used for storing search results */ #endif #endif const xmlChar *filesSearchResultsPath(void); #ifdef USE_GNOME_DOCS /** * filesURItoFileName: * @uri : A valid URI that uses the "file://" prefix * * Return A copy of the conversion of @uri to a file name * that is suitable to be used with the fopen function. * May be NULL, if out of memory, @uri does not use the * "file://" prefix, or unable to convert to a valid file name * * Returns A copy of the conversion of @uri to a file name * that is suitable to be used with the fopen function. * May be NULL, if out of memory, @uri does not use the * "file://" prefix, or unable to convert to a valid file name * */ #else #ifdef USE_KDE_DOCS /** * Return A copy of the conversion of @uri to a file name * that is suitable to be used with the fopen function. * May be NULL, if out of memory, @uri does not use the * "file://" protocol, or unable to convert to a valid file name * * Returns A copy of the conversion of @uri to a file name * that is suitable to be used with the fopen function. * May be NULL, if out of memory, @uri does not use the * "file://" prefix, or unable to convert to a valid file name * * @param uri A valid URI that uses the "file://" prefix * */ #endif #endif xmlChar *filesURItoFileName(const xmlChar* uri); #ifdef USE_GNOME_DOCS /** * xsldbgUpdateFileDetails: * @node : A valid node * * Update the URL and line number that we stoped at */ #else #ifdef USE_KDE_DOCS /** * Update the URL and line number that we stoped at * * @param node A valid node */ #endif #endif void xsldbgUpdateFileDetails(xmlNodePtr node); #ifdef USE_GNOME_DOCS /** * xsldbgLineNo: * * What line number are we at * * Returns The current line number of xsldbg, may be -1 **/ #else #ifdef USE_KDE_DOCS /** * What line number are we at * * @returns The current line number of xsldbg, may be -1 **/ #endif #endif int xsldbgLineNo(void); #ifdef USE_GNOME_DOCS /** * xsldbgUrl: * * What URL did we stop at * * Returns A NEW copy of URL stopped at. Caller must free memory for URL, * may be NULL */ #else #ifdef USE_KDE_DOCS /** * What URL did we stop at * * @returns A NEW copy of URL stopped at. Caller must free memory for URL, * may be NULL */ #endif #endif xmlChar *xsldbgUrl(void); /*----------------------------------------------------------- Platform specific file functions -----------------------------------------------------------*/ #ifdef USE_GNOME_DOCS /** * filesPlatformInit: * * Intialize the platform specific files module * * This is a platform specific interface * * Returns 1 if sucessful * 0 otherwise */ #else #ifdef USE_KDE_DOCS /** * Intialize the platform specific files module * * This is a platform specific interface * * @returns 1 if sucessful * 0 otherwise */ #endif #endif int filesPlatformInit(void); #ifdef USE_GNOME_DOCS /** * filesPlatformFree: * * Free memory used by the platform specific files module * * This is a platform specific interface * */ #else #ifdef USE_KDE_DOCS /** * Free memory used by the platform specific files module * * This is a platform specific interface * */ #endif #endif void filesPlatformFree(void); #ifdef USE_GNOME_DOCS /** * filesExpandName: * @fileName : A valid fileName * * Converts a fileName to an absolute path * If operating system supports it a leading "~" in the fileName * will be converted to the user's home path. Otherwise * the same name will be returned * * Returns A copy of the converted @fileName or a copy of * the @fileName as supplied. May return NULL */ #else #ifdef USE_KDE_DOCS /** * Converts a fileName to an absolute path * If operating system supports it a leading "~" in the fileName * will be converted to the user's home path. Otherwise * the same name will be returned * * Returns A copy of the converted @p fileName or a copy of * the @p fileName as supplied. May return NULL * * @param fileName A valid fileName */ #endif #endif xmlChar *filesExpandName(const xmlChar * fileName); #ifdef USE_GNOME_DOCS /** * filesSearchFileName: * @fileType : Is valid * * Return a copy of the file name to use as an argument to searching * * Returns A copy of the file name to use as an argument to searching */ #else #ifdef USE_KDE_DOCS /** * Return a copy of the file name to use as an argument to searching * * @returns A copy of the file name to use as an argument to searching * * @param fileType Is valid * */ #endif #endif xmlChar *filesSearchFileName(FilesSearchFileNameEnum fileType); #ifdef __cplusplus } #endif #endif