path: root/vfs/uVFSprototypes.pas

(*
    Virtual File System support
     - prototypes functions and types
    draft version 25

    used in Seksi commander and Tux Commander

    Copyright (C) 2003 Radek Cervinka <radek.cervinka@centrum.cz>
    Copyright (C) 2005-2009 Tomas Bzatek <tbzatek@users.sourceforge.net>

    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.

    This program 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 General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*)

unit uVFSprototypes;

interface

uses glib2;

{$IFDEF FPC}
  {$PACKRECORDS C}
{$ENDIF}

const
      cVFSVersion = 5;    //  current version of the VFS API

      //  Error codes (TVFSResult)
      cVFS_OK = 0;
      cVFS_Failed = 1;   // also No such file
      cVFS_Cancelled = 2;
      cVFS_Not_Supported = 3;
      cVFS_Not_More_Files = 4;   // returned while directory listing
      cVFS_ReadErr = 5;
      cVFS_WriteErr = 6;   //  also ReadOnlyFileSystem
      cVFS_LoginFailed = 7;
      cVFS_PermissionDenied = 8;
      cVFS_NoSpaceLeft = 9;
      cVFS_mallocFailed = 10;
      cVFS_BadPassword = 11;
      cVFS_MissingVolume = 12;
      cVFS_CorruptedArchive = 13;


      //  Open modes (for VFSOpenFile function) 
      cVFS_OpenRead = 0;
      cVFS_OpenWrite = 1;
      cVFS_OpenAppend = 2;

      VFS_ASK_PASSWORD_NEED_PASSWORD = 1 shl 0;
      VFS_ASK_PASSWORD_NEED_USERNAME = 1 shl 1;
      VFS_ASK_PASSWORD_NEED_DOMAIN   = 1 shl 2;
      VFS_ASK_PASSWORD_SAVING_SUPPORTED = 1 shl 3;       //  Plugin reports if gnome-keyring is available
      VFS_ASK_PASSWORD_ANONYMOUS_SUPPORTED = 1 shl 4;
      VFS_ASK_PASSWORD_SAVE_INTERNAL = 1 shl 14;         //  Save password into internal Connection Manager
      VFS_ASK_PASSWORD_ARCHIVE_MODE = 1 shl 15;          //  Callback from archive, change the UI a little bit


type
     TVFSResult = longint;

     //  Plugin private data for each connection/instance
     TVFSGlobs = Pointer;

     //  File descriptor for Open, Read, Write, Close, Seek operations
     TVFSFileDes = Pointer;

     TVFSAskPasswordFlags = Longint;

     //  Let the plugin save password, usually to gnome-keyring
     PVFSPasswordSave = ^TVFSPasswordSave;
     TVFSPasswordSave = (VFS_PASSWORD_SAVE_NEVER,
                         VFS_PASSWORD_SAVE_FOR_SESSION,
                         VFS_PASSWORD_SAVE_PERMANENTLY);

     TVFSItemType = (vRegular=0, vChardev=1, vBlockdev=2, vDirectory=3, vFifo=4, vSock=5, vOther=6);


     PVFSItem = ^TVFSItem;
     TVFSItem = record
       FName: PChar;
       FDisplayName: PChar;     //  FDisplayName - plugins must return valid UTF-8 string
       iSize: guint64;
       iPackedSize: gint64;     //  iPackedSize - set to -1 if plugin doesn't support this feature
       m_time: guint32;
       a_time: guint32;
       c_time: guint32;
       iMode: guint32;
       IsLink: gboolean;
       sLinkTo: PChar;
       iUID: guint32;
       iGID: guint32;
       ItemType: TVFSItemType;
     end;


     //  Basic information about the plugin
     PVFSInfo = ^TVFSInfo;
     TVFSInfo = record
       ID: PChar;          //  unique identifier, not shown in GUI
       Name: PChar;        //  plugin name, GUI string (UTF-8)
       About: PChar;       //  GUI string (UTF-8)
       Copyright: PChar;   //  GUI string (UTF-8)
     end;

type
    //  Return index of the choice selected or negative number when dialog has been cancelled
    //    cancel_choice: index which represents the cancellation choice. Set to -1 (e.g.) to disable this feature
    PVFSAskQuestionCallback = ^TVFSAskQuestionCallback;
    TVFSAskQuestionCallback = procedure (const AMessage: PChar;
                                         const Choices: PPChar;
                                         choice: PInteger;
                                         cancel_choice: Integer;
                                         user_data: Pointer); cdecl;

    //  Remember to allocate passed strings separately (use strdup() when setting reply)
    //  Modules are eligible for keeping passwords during one session; calling callback again means the last password was wrong and user should enter new one
    //  Returns True (1) if succeeded or False (0) if cancelled
    PVFSAskPasswordCallback = ^TVFSAskPasswordCallback;
    TVFSAskPasswordCallback = function (const AMessage: PChar;
                                        const default_user: PChar;
                                        const default_domain: PChar;
                                        const default_password: PChar;
                                        flags: TVFSAskPasswordFlags;
                                        username: PPChar;
                                        password: PPChar;
                                        anonymous: Pgboolean;
                                        domain: PPChar;
                                        password_save: PVFSPasswordSave;
                                        user_data: Pointer): gboolean; cdecl;

    //  Return False to break the operation
    PVFSProgressCallback = ^TVFSProgressCallback;
    TVFSProgressCallback = function (position: guint64;
                                     max: guint64;
                                     user_data: Pointer): gboolean; cdecl;

type
    //  Log function for plugin debugging output - host application will print or save these messages
    //  TODO: add log_level?
    PVFSLogFunc = ^TVFSLogFunc;
    TVFSLogFunc = procedure(const S: PChar); cdecl;
    //  Set callbacks, the user_data value will be passed into them
    TVFSSetCallbacks = procedure (g: TVFSGlobs; ask_question_callback: PVFSAskQuestionCallback;
                                                ask_password_callback: PVFSAskPasswordCallback;
                                                progress_func: PVFSProgressCallback;
                                                user_data: Pointer); cdecl;

    //  Allocates memory for the globs structure and performs intialization of the plugin
    TVFSNew = function (LogFunc: PVFSLogFunc): TVFSGlobs; cdecl;
    //  Performs cleanup and destroys all objects
    TVFSFree = procedure (g: TVFSGlobs); cdecl;
    //  Returns VFS API Version; must match version hardcoded in the host program, otherwise module is not loaded
    //  Please use the cVFSVersion constant as a return value
    TVFSVersion = function: integer; cdecl;
    //  Returns module info struct, tuxcmd will take care of memory deallocation
    TVFSGetInfo = function: PVFSInfo; cdecl;
    //  Returns the list of filename extensions which the module can handle separated by ';' (without a leading dots)
    //  Returning NULL or not defining the symbol at all means plugin can't handle archives
    //  tuxcmd will take care of memory deallocation
    TVFSGetArchiveExts = function: PChar; cdecl;
    //  Returns the list of supported remote protocols separated by ';' (without the '://')
    //  Returning NULL or not defining the symbol at all means plugin can't access network services
    //  tuxcmd will take care of memory deallocation
    TVFSGetNetworkServices = function: PChar; cdecl;
    //  TODO: Sets the protocol log function (unlike module debug log func this is intended only for server messages (FTP mainly))
    TVFSSetProtocolLogFunc = procedure (g:TVFSGlobs; ProtocolLogFunc: TVFSLogFunc); cdecl;
    //  Sets block size for I/O operations (not supported by all modules)
    TVFSSetBlockSize = procedure (g:TVFSGlobs; Value: guint32); cdecl;


    //  Opens specified archive. This will also switch engine into an archiving mode
    TVFSOpenArchive = function (g:TVFSGlobs; const sName: PChar): TVFSResult; cdecl;
    //  Opens specified network location. This will also switch engine into a networking mode
    //  In case of URI, do not supply password encoded in the string; plugin will automatically spawn the TVFSAskPasswordCallback callback when needed
    TVFSOpenURI = function (g:TVFSGlobs; const sURI: PChar): TVFSResult; cdecl;
    //  Closes the file or connection to the server
    TVFSClose = function (g:TVFSGlobs): TVFSResult; cdecl;


    //  These functions serves for listing contents of a directory
    //  Before calling VFSListFirst, it is recommended to change target directory (VFSChangeDir) to check it really exists
    //  First call the VFSListFirst function and then repeat call of VFSListNext until it returns NULL.
    //  Then call VFSListClose to make cleanup
    TVFSListFirst = function (g:TVFSGlobs; const sDir: PChar; VFSItem: PVFSItem; FollowSymlinks, AddFullPath: gboolean): TVFSResult; cdecl;
    TVFSListNext = function (g:TVFSGlobs; VFSItem: PVFSItem): TVFSResult; cdecl;
    TVFSListClose = function (g:TVFSGlobs): TVFSResult; cdecl;
    //  Gets a single info item without need to list a whole directory
    TVFSFileInfo = function (g:TVFSGlobs; const AFileName: PChar; VFSItem: PVFSItem; FollowSymlinks, AddFullPath: gboolean): TVFSResult; cdecl;


    //  Try to change directory, checks real access
    TVFSChangeDir = function (g:TVFSGlobs; const NewPath: PChar): TVFSResult; cdecl;
    //  Returns current working path, tuxcmd will take care of memory deallocation
    TVFSGetPath = function (g:TVFSGlobs): PChar; cdecl;
    //  Returns the current working path in the URI form, tuxcmd will take care of memory deallocation
    TVFSGetPathURI = function (g:TVFSGlobs): PChar; cdecl;
    //  Gets filesystem info; tuxcmd will take care of memory deallocation
    TVFSGetFileSystemInfo = function (g:TVFSGlobs; const APath: PChar; FSSize, FSFree: PInt64; FSLabel: PPChar): TVFSResult; cdecl;
    TVFSIsOnSameFS = function (g:TVFSGlobs; const Path1, Path2: PChar; FollowSymlinks: gboolean): gboolean; cdecl;
    //  Checks if the two files are simmilar (used to test the case-insensitive filesystem - or hardlinks)
    TVFSTwoSameFiles = function (g:TVFSGlobs; const Path1, Path2: PChar; FollowSymlinks: gboolean): gboolean; cdecl;
    //  Calculates recursively the size of a tree specified
    TVFSGetDirSize = function (g:TVFSGlobs; const APath: PChar): guint64; cdecl;
    //  Call this function to break the calculation performed by VFSGetDirSize
    TVFSBreakGetDirSize = procedure (g:TVFSGlobs); cdecl;

    //  Operations
    TVFSMkDir = function (g:TVFSGlobs; const sDirName: PChar): TVFSResult; cdecl;
    //  Rename/Move, the two files/directories have to be on the same filesystem (do manual copy and delete otherway)
    TVFSRename = function (g:TVFSGlobs; const sSrcName, sDstName: PChar): TVFSResult; cdecl;
    //  Removes file/directory (empty only!)
    TVFSRemove = function (g:TVFSGlobs; const APath: PChar): TVFSResult; cdecl;
    TVFSMakeSymLink = function (g:TVFSGlobs; const NewFileName, PointTo: PChar): TVFSResult; cdecl;
    //  Mode is classic unix format (glibc) - a bit mask
    TVFSChmod = function (g:TVFSGlobs; const FileName: PChar; Mode: guint32): TVFSResult; cdecl;
    TVFSChown = function (g:TVFSGlobs; const FileName: PChar; UID, GID: guint32): TVFSResult; cdecl;
    //  Changes times for the file/directory - mtime and atime are __time_t parameters (glibc)
    TVFSChangeTimes = function (g:TVFSGlobs; const APath: PChar; mtime, atime: guint32): TVFSResult; cdecl;

    
    //  Performs the copy process from inside of module to local filesystem
    //  (thus sSrcName is a path from inside of module and sDstName is path in the local filesystem where the file should be copied)
    //  Note: if you need to transfer a file between two VFS modules, you need to do it manually -
    //        - either first copy to local FS or use the Open, Read, Write functions of the module (NOTE: both VFS modules have to support these functions)
    TVFSCopyToLocal = function (g:TVFSGlobs; const sSrcName, sDstName: PChar; Append: gboolean): TVFSResult; cdecl;
    //  Performs the copy process from local filesystem into the module
    TVFSCopyFromLocal = function (g:TVFSGlobs; const sSrcName, sDstName: PChar; Append: gboolean): TVFSResult; cdecl;


    //  TODO: Prototype function for packing new files into archive
    TVFSPack = function (g:TVFSGlobs; const sSrcName, sDstName: PChar; CompressionLevel: integer; const Password: PChar): TVFSResult; cdecl;


    //  TODO: not implemented at all
    //  This is the set of basic functions which can manipulate with data
    //  There is a TVFSFileDes object which identifies the processed file (filedescriptor)
    //  All these functions needs a pointer to an int variable to store the error code
    //  NOTE: not all modules could support this set of functions due to its design (unable to set a solid block size)
    TVFSOpenFile = function (g:TVFSGlobs; const APath: PChar; Mode: integer; Error: Pinteger): TVFSFileDes; cdecl;
    //  Opens a file or creates new (the values for the Mode parameter are described above) and returns the assigned filedescriptor
    TVFSReadFile = function (g:TVFSGlobs; const FileDescriptor: TVFSFileDes; Buffer: Pointer; ABlockSize: integer; Error: Pinteger): integer; cdecl;
    //  Returns number of bytes read; the buffer needs to be allocated by a blocksize (set it by VFSSetBlockSize function)
    TVFSWriteFile = function (g:TVFSGlobs; const FileDescriptor: TVFSFileDes; Buffer: Pointer; BytesCount: integer; Error: Pinteger): integer; cdecl;
    //  Returns number of bytes written
    TVFSCloseFile = function (g:TVFSGlobs; const FileDescriptor: TVFSFileDes): TVFSResult; cdecl;
    TVFSFileSeek = function (g:TVFSGlobs; const FileDescriptor: TVFSFileDes; const AbsoluteOffset: Int64; Error: Pinteger): Int64; cdecl;
    //  Sets the position in the file from the start and returns real current position


    //  Returns flag indicating whether password is required for some files in the archive
    TVFSGetPasswordRequired = function (g:TVFSGlobs): gboolean; cdecl;
    //  Reset stored password in the plugin session
    TVFSResetPassword = procedure (g: TVFSGlobs); cdecl;

//  TODO: some function to check the CRC of the archive - it should need also some progress feedback - the processed file and percentage progress

//  TODO: port error logging subsystem to glib's GError

implementation

end.