home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / include / xp_file.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  17.3 KB  |  519 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19.  
  20. #ifndef _XP_File_
  21. #define _XP_File_
  22.  
  23. #define XP_FILE_NATIVE_PATH char *
  24. #define XP_FILE_URL_PATH char*
  25. /*-----------------------------------------------------------------------------
  26.     XP_File.h
  27.     Cross-Platform File API
  28.     
  29.     XP_File INTERFACE IS A COMMONLY MISUNDERSTOOD API.PLEASE READ THESE
  30.     DOCS BEFORE USING THE API. The API is not self-documenting in any way,
  31.     and broken in many.
  32.     
  33.     XP_File mimics the stdio file interface (fopen, fread & friends...). 
  34.     The main difference is that to specify a file location, XP_File 
  35.     uses a name in combination with an enum XP_FileType instead of full path.
  36.     
  37.         For example :
  38.                 stdio:        fopen(filename, permissions)
  39.         maps to xp_file:    XP_FileOpen (name, XP_FileType type, XP_FilePerm permissions);
  40.     
  41.     Meaning of the name argument depends on the XP_FileType it is used with.
  42.     
  43.         For example:
  44.         A)        XP_FileOpen(name, xpURL)
  45.                 name is the URL path to the file (/Drive/file.html)
  46.         B)        XP_FileOpen(name, xpCache)
  47.                 name is the partial path from cache directory (expands to cache-directory/name)
  48.         C)        XP_FileOpen(name, xpTemporary)
  49.                 name is the partial path from temporary directory (expands to cache-directory/name)
  50.  
  51.     Corollary: YOU CANNOT MIX AND MATCH NAMES AND TYPES
  52.         For example:
  53.                 newTempFile = XP_TempName(name, xpTemporary);
  54.                 file =  XP_FileOpen(newTempFile, xpURL, "r+w");    // BAD!, you've just mixed xpURL and xpTemporary
  55.         This is a very common error. It might work on some platforms, but it'll break others.
  56.     
  57.     FILE NAME MADNESS
  58.     
  59.     There are 3 basic ways to specify a file in the XP_File interface:
  60.  
  61.     TheXP_FileSpec
  62.     
  63.     char* - XP_FileType pair:     used in most XP_File calls. the meaning of the name 
  64.                                 depends on the enum. Common ones are:
  65.                                 XP_FileType        /         name means:
  66.                                 
  67.                                 xpTemporary                partial path relative to temporary directory
  68.                                 xpURL                    full path in the standard URL format (file://)
  69.                                 xpGlobalHistory            name is ignored. 
  70.  
  71.     XP_FILE_NATIVE_PATH
  72.  
  73.     char *                        used in platform-specific code, platform-specific full path
  74.                                 Windows:    "C:\Windows\regedit.exe"
  75.                                 X:            "/h/users/atotic/home.html"
  76.                                 Mac:        "Macintosh HD:System Folder:System"
  77.     
  78.     XP_FILE_URL_PATH                    used in cross-platform code, when you need to manipulate the full path.
  79.                                 It is a full path in the standard URL format: (file://<path>, but just the <path> part)
  80.     
  81.     XP_FILE_NATIVE_PATH and XP_FILE_URL_PATH are often confused
  82.     
  83.     To convert between these types:
  84.  
  85.     Conversion:        TheXP_FileSpec    -> XP_FILE_NATIVE_PATH        
  86.     Call:            WH_FileName(name, type)
  87.     Example:        WH_FileName("myName", xpTemporary)    -> "/u/tmp/myName" on Unix
  88.                                                         -> "C:\tmp\myName" on Windows
  89.                                                         -> "Mac HD:Temporary folder:myName" on Mac
  90.     
  91.     Conversion:        XP_FILE_NATIVE_PATH -> XP_FILE_URL_PATH
  92.     Call:            XP_PlatformFileToURL(name)
  93.     Example:        Windows:    XP_PlatformFileToURL("C:\tmp\myName")    -> "C|/tmp/myName"
  94.                     Unix:         XP_PlatformFileToURL(/u/tmp/myName")    -> "/u/tmp/myName"
  95.                     Mac:    XP_PlatformFileToURL("Mac HD:Temporary folder:myName")    -> "Mac%20HD/Temporary%20folder/myName"
  96.     
  97.     You cannot convert anything into arbitrary TheXP_FileSpec, but you can use the XP_FILE_URL_PATH 
  98.     in combination with xpURL enum.
  99.     Example:        XP_FileOpen("C|/tmp/myName", xpURL) works
  100.     
  101.     COMMONLY USED CALLS NOT IN STDIO:
  102.  
  103.     WH_FileName(name, XP_FileType) - maps TheXP_FileSpec pair to XP_FILE_NATIVE_PATH.
  104.     Use it when you need access to full paths in platform-specific code. For example:
  105.         For example:
  106.             cacheName = XP_FileName("", xpCacheFAT);
  107.             fopen(cacheName);
  108.  
  109.     
  110.     EXTENSIONS TO STDIO API:
  111.     
  112.     - XP_FileRename also moves files accross file systems (copy + delete)
  113.  
  114.     
  115.     MISC API NOTES:
  116.     
  117.     The names of most of the calls are derived by prepending stdio call name
  118.     with XP_File. (open -> XP_FileOpen, opendir -> XP_FileOpenDir). But warren
  119.     was fixing up some bugs near the end of 3.0, and in his infinite wisdom renamed
  120.     a few of them to WH_ instead of XP_. So, XP_FileName became WH_FileName. WH_ stands
  121.     for Warren Harris. Whatever...
  122.     
  123.     Calls are not documented well. Most of the docs are in this header file. You 
  124.     can usually get a hint about what the call should do by looking up the man
  125.     pages of the equivalent stdio call.
  126.  
  127.     OLD DOCS (May mislead you, read at your peril!):
  128.     Macintosh file system is not organized in the same hierarchy as UNIX and PC
  129.     ':' is a separator character instead of '/', '~', '/../' constructs do not
  130.     work.  Basically, you cannot easily open a file using a pathname.
  131.     Because different types of files need to be stored in different 
  132.     directories, the XP_FileOpen API takes a file type and file name as an
  133.     argument.  Semantics of how file is opened vary with type.
  134.     
  135.     "Personal" files are stored in the user's "home" directory (~ on unix,
  136.         launch point or system folder on Mac, dunno about Windows). File names
  137.         may be ignored since there's no reason for multiple personal files.
  138.     "Temporary" files are stored in /tmp or the equivalent
  139.     "URL" is the only type that allows access to anywhere on the disk
  140.  
  141.     File Type           File name                 Semantics
  142.     xpURL               url part after file:///   Platform specific
  143.                         without #aklsdf
  144.     xpGlobalHistory     -                         Opens personal global history
  145.     xpKeyChain          -                         Opens personal key chain
  146.     xpUserPrefs         -                         Opens personal prefs file
  147.     xpJSMailFilters        -                          Opens personal js mail filters
  148.     xpJSHTMLFilters    -              Opens personal js HTML filters
  149.     xpCache             name without path         Opens a cache file
  150.     xpExtCache          Fully qualified path      Opens an external cache file
  151.     xpTemporary         local filename            Opens a temporary file
  152.     xpNewsrc            -                         Opens a .newsrc file
  153.     xpSignature            -                          Opens a .signature file
  154.     xpCertDB        -              Opens cert DB
  155.     xpCertDBNameIDX    -              Opens cert name index
  156.     xpKeyDB            -              Opens key DB
  157.     xpSignedAppletDB    -          Signed applets DB filename
  158.     xpJSCookieFilters   -         Opens personal js cookie filters
  159.  
  160. -----------------------------------------------------------------------------*/
  161.  
  162. #ifdef XP_UNIX
  163. # include <dirent.h>
  164. # include <sys/stat.h>
  165. #endif /* XP_UNIX */
  166.  
  167. #ifdef XP_MAC
  168. # ifndef _UNIX
  169. #  include <unix.h>
  170. # endif
  171. # include <Types.h>
  172. # include <Files.h>
  173. #endif /* XP_MAC */
  174.  
  175. #ifdef XP_WIN
  176. # include "winfile.h"
  177. #endif /* XP_WIN */
  178.  
  179. #ifdef XP_OS2
  180. # include "dirent.h"
  181. # include "sys/stat.h"
  182. #endif /* XP_OS2 */
  183.  
  184. /*-----------------------------------------------------------------------------
  185.     Types - NOT prototypes
  186.     Protoypes go further down.
  187. -----------------------------------------------------------------------------*/
  188.  
  189. typedef enum XP_FileType {
  190.     xpAddrBookNew,
  191.     xpAddrBook,
  192.     xpUserPrefs, 
  193.     xpKeyChain, 
  194.     xpGlobalHistory, 
  195.     xpGlobalHistoryList,
  196.     xpHotlist,
  197.     xpTemporary, 
  198.     xpURL,
  199.     xpCache,
  200.     xpSARCache,                /* larubbio location independent cache */
  201.     xpMimeTypes,
  202.     xpCacheFAT,
  203.     xpSARCacheIndex,            /* larubbio location independent cache */
  204.     xpNewsRC,
  205.     xpSNewsRC,
  206.     xpTemporaryNewsRC,
  207.     xpNewsgroups,
  208.     xpSNewsgroups,
  209.     xpNewsHostDatabase,
  210.     xpHTTPCookie,
  211.     xpProxyConfig,
  212.     xpSocksConfig,
  213.     xpSignature,
  214.     xpNewsrcFileMap,
  215.     xpFileToPost,
  216.     xpMailFolder,
  217.     xpMailFolderSummary,
  218.     xpJSMailFilters,
  219.     xpJSHTMLFilters,
  220.     xpMailSort,                    /* File that specifies which mail folders
  221.                                    to file which messages. */
  222.     xpNewsSort,
  223.     xpMailFilterLog,            /* log files for mail/news filters */
  224.     xpNewsFilterLog,            
  225.     xpMailPopState,
  226.     xpMailSubdirectory,
  227.     xpBookmarks,
  228.     xpCertDB,
  229.     xpCertDBNameIDX,
  230.     xpKeyDB,
  231.     xpSecModuleDB,
  232.     xpExtCache,
  233.     xpExtCacheIndex,                /* index of external indexes */
  234.     xpRegistry,
  235.  
  236.     xpXoverCache,                /* Cache of XOVER files.  This
  237.                                    filename always takes the form
  238.                                    "hostname/groupname" (except for calls
  239.                                    to XP_MakeDirectory, where it is just
  240.                                    "hostname").*/
  241.     xpEditColorScheme,            /* ifdef EDITOR   Families of "good" color combinations */
  242.     xpJPEGFile,                 /* used for pictures in LDAP directory */
  243.     xpVCardFile,                /* used for versit vCards */
  244.     xpLDIFFile,                    /* used for LDIF (LDAP Interchange format files */
  245.     xpImapRootDirectory,
  246.     xpImapServerDirectory,
  247.     xpHTMLAddressBook,            /* old (HTML) address book */
  248.     xpSignedAppletDB,            /* filename of signed applets DB */
  249.     xpCryptoPolicy,             /* Export Policy control file */
  250.     xpFolderCache,               /* for caching mail/news folder info */
  251.     xpPKCS12File,        /* used for PKCS 12 certificate transport */
  252.     xpJSCookieFilters,            /* Opens personal js cookie filters */
  253.     xpLIClientDB,
  254.     xpLIPrefs
  255. } XP_FileType;
  256.  
  257.  
  258. #define XP_FILE_READ             "r"
  259. #define XP_FILE_READ_BIN         "rb"
  260. #define XP_FILE_WRITE            "w"
  261. #define XP_FILE_WRITE_BIN        "wb"
  262. #define XP_FILE_APPEND           "a"
  263. #define XP_FILE_APPEND_BIN       "ab"
  264. #define XP_FILE_UPDATE           "r+"
  265. #define XP_FILE_TRUNCATE         "w+"
  266. #ifdef SUNOS4
  267. /* XXX SunOS4 hack -- make this universal by using r+b and w+b */
  268. #define XP_FILE_UPDATE_BIN       "r+"
  269. #define XP_FILE_TRUNCATE_BIN     "w+"
  270. #else
  271. #define XP_FILE_UPDATE_BIN       "rb+"
  272. #define XP_FILE_TRUNCATE_BIN     "wb+"
  273. #endif
  274.  
  275. #ifdef __BORLANDC__
  276.     #define _stat stat
  277. #endif
  278. #ifdef XP_MAC
  279. #define XP_STAT_READONLY( statinfo ) (0)
  280. #else
  281. #define XP_STAT_READONLY( statinfo ) ((statinfo.st_mode & S_IWRITE) == 0)
  282. #endif
  283.  
  284.  
  285. typedef FILE          * XP_File;
  286. typedef char          * XP_FilePerm;
  287.  
  288. #ifdef XP_WIN
  289.  typedef struct _stat   XP_StatStruct;
  290. #endif
  291.  
  292. #if defined(XP_OS2)
  293.  typedef struct stat    XP_StatStruct;
  294. #endif
  295.  
  296. #ifdef XP_UNIX
  297.  typedef struct stat    XP_StatStruct;
  298. #endif
  299.  
  300. #if defined (XP_MAC)
  301.  typedef struct stat    XP_StatStruct;
  302. #endif
  303.  
  304. #if defined(XP_UNIX) || defined(XP_WIN) || defined(XP_OS2)
  305.  typedef DIR          * XP_Dir;
  306.  typedef struct dirent  XP_DirEntryStruct;
  307. #endif
  308.  
  309. #ifdef XP_MAC
  310.     /* Mac has non-stdio definitions of XP_Dir and XP_DirEntryStruct */
  311.  
  312. typedef struct macdstat {
  313.     char d_name[300];
  314. } XP_DirEntryStruct;
  315.  
  316. typedef struct dirstruct {
  317.     XP_DirEntryStruct dirent;
  318.     FSSpec dirSpecs;
  319.     short index;    /* Index for looping in XP_OpenDir */
  320.     XP_FileType type;
  321. }    *XP_Dir;
  322.  
  323. #endif /* XP_MAC */
  324.  
  325.  
  326. /*-----------------------------------------------------------------------------
  327.     Prototypes
  328. -----------------------------------------------------------------------------*/
  329.  
  330. XP_BEGIN_PROTOS
  331.  
  332. /*
  333.  * Given TheXP_FileSpec returns XP_FILE_NATIVE_PATH.
  334.  * See docs on top for more info
  335.  */
  336. PUBLIC XP_FILE_NATIVE_PATH WH_FileName (const char *name, XP_FileType type);
  337.  
  338. /* 
  339.  * Given XP_FILE_URL_PATH, returns XP_FILE_NATIVE_PATH
  340.  * See docs on top for more info
  341.  */
  342. PUBLIC XP_FILE_NATIVE_PATH WH_FilePlatformName(const char * name);
  343.  
  344. /* 
  345.  * Given XP_FILE_NATIVE_PATH, returns XP_FILE_URL_PATH
  346.  * See docs on top for more info
  347.  */
  348. PUBLIC XP_FILE_URL_PATH XP_PlatformFileToURL (const XP_FILE_NATIVE_PATH platformName);
  349.  
  350. /* takes a portion of a local path and returns an allocated portion
  351.  * of an XP path. This function was initially created to translate 
  352.  * imap server folder names to xp names.
  353.  */
  354. PUBLIC char *XP_PlatformPartialPathToXPPartialPath (const char *platformPath);
  355.  
  356. /* Returns a pathname of a file suitable for use as temporary storage
  357.  * Warning: you can only use the returned pathname in other XP_File calls
  358.  * with the same enum.
  359.  */
  360. extern char * WH_TempName(XP_FileType type, const char * prefix);
  361.  
  362. /* Returns the path to the temp directory. */
  363. extern char* XP_TempDirName(void);
  364.  
  365. /* Various other wrappers for stdio.h
  366.  */
  367. extern XP_File XP_FileOpen (const char* name, XP_FileType type,
  368.                             const XP_FilePerm permissions);
  369.  
  370. extern int XP_Stat(const char * name, XP_StatStruct * outStat,
  371.                    XP_FileType type);
  372.  
  373. extern XP_Dir XP_OpenDir(const char * name, XP_FileType type);
  374.  
  375. extern void XP_CloseDir(XP_Dir dir);
  376.  
  377. extern XP_DirEntryStruct *XP_ReadDir(XP_Dir dir);
  378.  
  379. extern int XP_FileRename(const char * from, XP_FileType fromtype,
  380.                          const char * to,   XP_FileType totype);
  381.  
  382. extern int XP_FileRemove(const char * name, XP_FileType type);
  383.  
  384. extern int XP_MakeDirectory(const char* name, XP_FileType type);
  385.  
  386. /* XP_MakeDirectoryR recursively creates all the directories needed */
  387. extern int XP_MakeDirectoryR(const char* name, XP_FileType type);
  388.  
  389. extern int XP_RemoveDirectory(const char *name, XP_FileType type);
  390.  
  391. extern int XP_RemoveDirectoryRecursive(const char *name, XP_FileType type);
  392.  
  393. /* Truncate a file to be a given length.  It is important (especially on the
  394.    Mac) to make sure not to ever call this if you have the file opened. */
  395. extern int XP_FileTruncate(const char* name, XP_FileType type, int32 length);
  396.  
  397. extern int XP_FileWrite (const void* source, int32 count, XP_File file);
  398.  
  399. extern char * XP_FileReadLine(char * dest, int32 bufferSize, XP_File file);
  400.  
  401. extern long XP_FileTell( XP_File file );
  402.  
  403. extern int XP_FileFlush(  XP_File file );
  404.  
  405. extern int XP_FileClose(XP_File file);
  406.  
  407. /* Defines */
  408.  
  409. #define XP_Fileno fileno
  410. #define XP_FileSeek(file,offset,whence) fseek ((file), (offset), (whence))
  411. #define XP_FileRead(dest,count,file) fread ((dest), 1, (count), (file))
  412. #define XP_FileTell(file) ftell(file)
  413. #define XP_FileFlush(file) fflush(file)
  414. /* varargs make it impossible to do any other way */
  415. #define XP_FilePrintf fprintf
  416.  
  417. /* XP_GetNewsRCFiles returns a null terminated array of pointers to malloc'd
  418.  * filename's.  Each filename represents a different newsrc file.
  419.  *
  420.  * return only the filename since the path is not needed or wanted.
  421.  *
  422.  * Netlib is expecting a string of the form:
  423.  *  [s]newsrc-host.name.domain[:port]
  424.  *
  425.  * examples:
  426.  *    newsrc-news.mcom.com
  427.  *    snewsrc-flop.mcom.com
  428.  *    newsrc-news.mcom.com:118
  429.  *    snewsrc-flop.mcom.com:1191
  430.  *
  431.  * the port number is optional and should only be
  432.  * there when different from the default.
  433.  * the "s" in front of newsrc signifies that
  434.  * security is to be used.
  435.  *
  436.  * return NULL on critical error or no files
  437.  */
  438. extern char ** XP_GetNewsRCFiles(void);
  439.  
  440.  
  441. /* #ifdef EDITOR */
  442. /* If pszLocalName is not NULL, we return the full pathname
  443.  *   in local platform syntax. Caller must free this string.
  444.  * Returns TRUE if file already exists
  445.  * Windows version implemented in winfe\fegui.cpp
  446.  */
  447. extern Bool XP_ConvertUrlToLocalFile(const char * szURL, char **pszLocalName);
  448.  
  449. /* Construct a temporary filename in same directory as supplied "file:///" type URL
  450.  * Used as write destination for saving edited document
  451.  * User must free string.
  452.  * Windows version implemented in winfe\fegui.cpp
  453.  */ 
  454. extern char * XP_BackupFileName( const char * szURL );
  455.  
  456. extern XP_Bool XP_FileIsFullPath(const char * name);
  457.  
  458. extern XP_Bool XP_FileNameContainsBadChars(const char *name);
  459.  
  460. #ifdef XP_MAC
  461.  
  462. /* XP_FileNumberOfFilesInDirectory returns the number of files in the specified
  463.  * directory
  464.  */
  465. extern int XP_FileNumberOfFilesInDirectory(const char * dir_name, XP_FileType type);
  466.  
  467. #endif /* XP_MAC */
  468.  
  469. XP_END_PROTOS
  470.  
  471.  
  472.  
  473. #if defined(XP_UNIX) || defined(XP_WIN) || defined(XP_OS2)
  474.  
  475. /* Unix and Windows preferences communicate with the netlib through these
  476.    global variables.  Netlib does "something sensible" if they are NULL.
  477.  */
  478. extern char *FE_SARCacheDir;
  479. extern char *FE_UserNewsHost;
  480. extern char *FE_UserNewsRC;
  481. extern char *FE_TempDir;
  482. extern char *FE_CacheDir;
  483. extern char *FE_DownloadDir;
  484. extern char *FE_GlobalHist;
  485.  
  486. #endif /* XP_UNIX || XP_WIN */
  487.  
  488.  
  489. /* Each of the three patforms seem to have subtly different opinions
  490.    about which functions should be aliases for their stdio counterparts,
  491.    and which should be real functions.
  492.  
  493.    Note that on the platform in question, these #defines will override
  494.    the prototypes above.
  495.  */
  496.  
  497. #if defined(XP_UNIX) || defined(XP_WIN) || defined(XP_OS2)
  498. # define XP_FileReadLine(destBuffer, bufferSize, file) \
  499.     fgets(destBuffer, bufferSize, file)
  500. #endif /* XP_UNIX || XP_WIN */
  501.  
  502. #if defined(XP_UNIX) || defined(XP_OS2)
  503. # define XP_ReadDir(DirPtr) readdir((DirPtr))
  504. # define XP_CloseDir(DirPtr) closedir((DirPtr))
  505. #endif /* XP_UNIX */
  506.  
  507. #if defined(XP_MAC) || defined(XP_WIN) || defined(XP_OS2)
  508.  /* #### Note! This defn is dangerous because `count' is evaluated twice! */
  509. # define XP_FileWrite(source, count, file)    \
  510.     fwrite((void*)(source), 1, \
  511.            (size_t) ((count) == -1 ? strlen((char*)source) : (count)), \
  512.            (file))
  513.  
  514. # define XP_FileClose(file) fclose ((file))
  515.  
  516. #endif /* XP_MAC || XP_WIN */
  517.  
  518. #endif /* _XP_File_ */
  519.