compile insert rti_FTPClient_Equates
/*
   ** Copyright (C) 1992-2023 Revelation Software Inc. All Rights Reserved **
   
   Author   : Captain C
   Date     : November 2023
   Purpose  : Constants for use with the RTI_FTPCLIENT stored procedure which
            : is a wrapper around the WinInet FTP functions.
   
   Comments
   ========
   
   The following core connection methods are provided:
   
      CONNECT
      DISCONNECT
      
   The following methods work with the CONNECT and DISCONNECT methods 
   (i.e. CONNECT must be called to use these, and DISCONNECT must be
   called when FTP processing is completed).
   
      Directory methods
      =================
      DIRLIST
      GETCURRENTDIR
      MAKEDIR
      REMOVEDIR
      SETCURRENTDIR
      
      File methods
      ============
      DELETEFILE
      GETFILESIZE
      READFILE
      RENAMEFILE
      WRITEFILE
      WRITEFILEDATA
      
   In addition to these there are several "convenience" methods that use
   the CONNECT and DISCONNECT methods internally, thereby removing the 
   need to call them yourself:
   
      GETFILE        == (CONNECT/READFILE/DISCONNECT)
      GETFILEDATA    == (CONNECT/READFILEDATA/DISCONNECT)
      SENDFILE       == (CONNECT/WRITEFILE/DISCONNECT)
      SENDFILEDATA   == (CONNECT/WRITEFILEDATA/DISCONNECT)
   
   Amended  Date        Reason
   =======  ====        ====== 
*/
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
#ifndef _RTI_FTPCLIENT_EQUATES_
#define _RTI_FTPCLIENT_EQUATES_
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////

   declare function rti_FTPClient
   $insert msWin_FileAttribute_Equates
   
///////////////////////////////////////////////////////////////////////////////
//
// CONNECT method
//
// Connects to an FTP server and returns a handle for use with subsequent 
// operations.
//
// The handles returned from this method should be released via the DISCONNECT
// method.
//
//    hClient = rti_FTPClient( "CONNECT", serverURL, userName, password, 
//                             connectFlags )
//
// ----------------------------------------------------------------------------
// [i] serverURL     : standard ftp:// URL (poss. including port)         [req]
// [i] userName      : Username used to authenticate to the server
// [i] password      : Password used to authenticate to the server
// [i] connectFlags  : Bitmask of flags to use for the connection (see the 
//                     "dwFlags" parmater in the InternetConnect() docs)
// ----------------------------------------------------------------------------
// [r] Returns a "handle" (actually a pair of HINTERNET handles) if successful
//     
//       <1> hInternet
//       <2> hConnection
//
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
// 
// DELETEFILE method
//
// Removes a file from the FTP Server
//
//    bSuccess = rti_FTPClient( "DELETEFILE", hClient, fileName )
//
// ----------------------------------------------------------------------------
// [i] hClient  : Connection handles returned from a CONNECT method       [req]
// [i] fileName : Name of the file to be deleted                          [req]
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file was deleted, or FALSE$ otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// DIRLIST method
//
// Returns a list of files and/or directories from the FTP Server.
//
//    fileList = rti_FTPClient( "DIRLIST", hClient, dirName, fileSpec, |
//                              typeSpec, findFlags, bRecurse, bSort )
//
// ----------------------------------------------------------------------------
// [i] hClient   : Connection handles returned from the CONNECT method    [req]
// [i] dirName   : Directory to list - defaults to the current directory
// [i] fileSpec  : File specifier - name of the file to list (inc. wild cards), 
//               : or null for all files
// [i] typeSpec  : "1" for directories only 
//               : "2" for files only 
//               : "0" or null for files and directories
// [i] findFlags : Bitmask of flags to use in the search (see "dwFlags" in the
//               : FtpFindFirstFile() docs)
// [i] bRecurse  : TRUE$ to recurse into sub-directories.
// [i] bSort     : TRUE$ to sort the results (AL).
// ---------------------------------------------------------------------------- 
// [r] Returns an @fm-delimited of matching files. Each item in the list has
//     the following format:
//
//       <0,1> Fully qualified file name
//       <0,2> File Attributes (See MSWIN_FILEATTRIBUTE_EQUATES)
//       <0,3> File Size (bytes)
//       <0,4> Directory Flag (TRUE$ if the item is a directory)
//       <0,5> Date & Time created (DT format)
//       <0,6> Date & Time last accessed (DT format)
//       <0,7> Date & Time last modified (DT format)
//
// ----------------------------------------------------------------------------
// [e] Errors are returned via set_Status()
// ----------------------------------------------------------------------------

   // typeSpec
   equ RTI_FC_TYPESPEC_DIR_ONLY$      to 1
   equ RTI_FC_TYPESPEC_FILES_ONLY$    to 2
   
   // Return file list format
   equ RTI_FC_DIRLIST_POS_FILENAME$    to 1
   equ RTI_FC_DIRLIST_POS_FILEATTR$    to 2
   equ RTI_FC_DIRLIST_POS_FILESIZE$    to 3
   equ RTI_FC_DIRLIST_POS_DIRFLAG$     to 4
   equ RTI_FC_DIRLIST_POS_CREATETIME$  to 5
   equ RTI_FC_DIRLIST_POS_ACCESSTIME$  to 6
   equ RTI_FC_DIRLIST_POS_WRITETIME$   to 7

   
///////////////////////////////////////////////////////////////////////////////
// 
// DISCONNECT method
//
// This method releases the connection handles opened via the CONNECT method.
//
//    bSuccess = rti_FTPClient( "DISCONNECT", hClient )
//
// ----------------------------------------------------------------------------
// [i] hClient : Connection handles returned from a CONNECT method        [req]
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the handles are released sucessfully, or FALSE$ 
//     otherwise
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
// 
// GETCURRENTDIR method
//
// Returns the current directory for the connected FTP Server.
//
//    currentDir = rti_FTPClient( "GETCURRENTDIR", hClient )
//
// ----------------------------------------------------------------------------
// [i] hClient : Connection handles returned from a CONNECT method.       [req]
// ----------------------------------------------------------------------------
// [r] Returns the current directory, or null if there is an error
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// GETFILE method
//
// Retrieves a file from the FTP server and saves it to the local machine.
//
// This method is a simple wrapper to encapsulate calls to CONNECT, READFILE,
// and DISCONNECT.
//
//    bSuccess = rti_FTPClient( "GETFILE", serverURL, userName, password, |
//                              remoteFile, localFile, connectFlags,      |
//                              getFileFlags )
//
// ----------------------------------------------------------------------------
// [i] serverURL     : standard ftp:// URL (poss. including port)         [req]
// [i] userName      : Username used to authenticate to the server
// [i] password      : Password used to authenticate to the server
// [i] remoteFile    : Name and path of the remote file to get            [req]
// [i] localFile     : Name and path to save the file as                  [req]
// [i] connectFlags  : Bitmask of flags to use for the connection (see the 
//                   : "dwFlags" parmater in the InternetConnect() docs)
// [i] getFileFlags  : Bitmask of flags to use for the transfer (see the 
//                   : "dwFlags" parameter in the FtpGetFile() docs)
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file is transferred successfully, or FALSE$ 
//     otherwise
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
//
// GETFILEDATA method
//
// Returns the contents of a remote file.
//
// This method is a simple wrapper to encapulate calls to CONNECT, READDATA,
// and DISCONNECT to emulate the old FTPGETFILE SSP.
//
//    fileData = rti_FTPClient( "GETFILEDATA", serverURL, userName, password,|
//                              fileName, connectFlags, openFileFlags,       |
//                              bufferSize )
//
// ----------------------------------------------------------------------------
// [i] serverURL     : standard ftp:// URL (poss. including port)         [req]
// [i] userName      : Username used to authenticate to the server
// [i] password      : Password used to authenticate to the server
// [i] fileName      : Path and file name to get                          [req]
// [i] connectFlags  : Bitmask of flags to use for the connection (see the 
//                   : "dwFlags" parmater in the InternetConnect() docs)
// [i] openFileFlags : Bitmask of flags to use for the transfer (see the 
//                   : "dwFlags" parameter in the FtpOpenFile() docs)
// [i] bufferSize    : Size in bytes of the read buffer - defaults to 64K
// ----------------------------------------------------------------------------
// [r] Returns the file contents
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------

   equ RTI_FC_DFLT_READ_BUFFER_SIZE$          to 0xFFFF ; // 64K
   

///////////////////////////////////////////////////////////////////////////////
// 
// GETFILESIZE method
//
// Returns the size in bytes of the specified file
//
//    fileSize = rti_FTPClient( "GETFILESIZE", hClient, fileName )
//
// ----------------------------------------------------------------------------
// [i] hClient  : Connection handles returned from a CONNECT method       [req]
// [i] fileName : Name of the file to be queried                          [req]
// ----------------------------------------------------------------------------
// [r] Returns the size of the file in byyes if successful, or "-1" if not
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 

   equ RTI_FC_FILESIZE_UNKNOWN$      to -1
   

///////////////////////////////////////////////////////////////////////////////
// 
// MAKEDIR method
//
// Creates a new directory on the FTP Server
//
//    bSuccess = rti_FTPClient( "MAKEDIR", hClient, dirName )
//
// The directory name can be either a fully qualified path or a name relative 
// to the current directory.
//
// ----------------------------------------------------------------------------
// [i] hClient : Connection handles returned from a CONNECT method        [req]
// [i] dirName : Directory to create                                      [req]
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the directory is created, or FALSE$ otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// READFILE method
//
// Retrieves a file from the FTP server and saves it to the local machine.
//
//    bSuccess = rti_FTPClient( "READFILE", hClient, remoteFile, localFile, |
//                              getFileFlags )
//
// ----------------------------------------------------------------------------
// [i] hClient      : Connection handles returned from a CONNECT method   [req]
// [i] remoteFile   : Name and path of the remote file to get             [req]
// [i] localFile    : Name and path to save the file as                   [req]
// [i] getFileFlags : Bitmask of flags to use for the transfer (see the 
//                  : "dwFlags" parameter in the FtpGetFile() docs)
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file is transferred successfully, or FALSE$ 
//     otherwise
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
// 
// READFILEDATA method
//
// Retrieves a chunk of file contents from the connected FTP Server.  This
// method is designed to be used in a loop until all of the contents are 
// returned.
//
//    fileContents = ""
//
//    fileName      = "/tmp/test.jpg"
//    openFileFlags = bitOr( FTP_TRANSFER_TYPE_BINARY$, INTERNET_FLAG_RELOAD$ ) 
//    bufferSize    = 1024
//    hFile         = 0
//    bFinished     = FALSE$
//      
//    loop
//       fileChunk = rti_FTPClient( "READFILEDATA", hClient, fileName,          |
//                                  openFileFlags, bufferSize, hFile, bFinished )
//       if get_Status() then
//          // Handle error - bFinished will be set to TRUE$
//       end else
//          fileContents := fileData
//       end
//    until bFinished
//       // Report progess etc...
//    repeat
//
// ----------------------------------------------------------------------------
// [i]   hClient       : Connection handles returned from a CONNECT method       [req]
// [i]   fileName      : Path and file name to get                               [req]
// [i]   openFileFlags : Bitmask of flags to use for the transfer (see the 
//                     : "dwFlags" parameter in the FtpOpenFile() docs).  
//                     : Defaults to FTP_TRANSFER_TYPE_BINARY$
// [i]   bufferSize    : Size in bytes of the read buffer - defaults to 64K
// [i,o] hFile         : Internal file transfer handle - must be initialized     [req]
//                     : to 0.  This handle is closed automatically when all
//                     : of the file contents have been read, or an error is
//                     : encountered.
// [i,o] bFinished     : Returns TRUE$ when all the contents of the file have    [req]
//                     : been returned or an error is encountered.
// ----------------------------------------------------------------------------
// [r] Returns the bytes read from the file
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
// 
// REMOVEDIR method
//
// Removes a directory from the FTP Server
//
//    bSuccess = rti_FTPClient( "REMOVEDIR", hClient, dirName )
//
// The directory name can be either a fully qualified path or a name relative 
// to the current directory.
//
// ----------------------------------------------------------------------------
// [i] hClient : Connection handles returned from a CONNECT method        [req]
// [i] dirName : Directory to remove                                      [req]
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the directory is removed, or FALSE$ otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// RENAMEFILE method
//
// Renames a file stored on the FTP server.
//
//    bSuccess = rti_FTPClient( "RENAMEFILE", hClient, fileName, newFileName )
//
// ----------------------------------------------------------------------------
// [i] hClient     : Connection handles returned from a CONNECT method    [req]
// [i] fileName    : Name of the file to be renamed                       [req]
// [i] newfileName : New name for the file                                [req]
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file was renamed, or FALSE$ otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// SENDFILE method
//
// Sends a file to the FTP server
//
// This method is a simple wrapper to encapsulate calls to CONNECT, WRITEFILE,
// and DISCONNECT.
//
//    bSuccess = rti_FTPClient( "SENDFILE", serverURL, userName, password, |
//                              sourceFile, targetFile, connectFlags,      |
//                              putFileFlags )
//
// ----------------------------------------------------------------------------
// [i] serverURL     : standard ftp:// URL (poss. including port)         [req]
// [i] userName      : Username used to authenticate to the server
// [i] password      : Password used to authenticate to the server
// [i] sourceFile    : Name and path of the local file to send            [req]
// [i] targetFile    : Name and path to write the file to on the server   [req]
// [i] connectFlags  : Bitmask of flags to use for the connection (see the 
//                   : "dwFlags" parmater in the InternetConnect() docs)
// [i] putFileFlags  : Bitmask of flags to use for the transfer (see the 
//                   : "dwFlags" parameter in the FtpPutFile() docs)
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file is transferred successfully, or FALSE$ 
//     otherwise
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
//
// SENDFILEDATA method
//
// Sends the contents of the fileData parameter to the FTP server using the 
// specified path and directory.
//
// This method is a simple wrapper to encapulate calls to CONNECT, WRITEDATA,
// and DISCONNECT to emulate the old FTPSEND SSP.
//
//    bSuccess = rti_FTPClient( "SENDFILEDATA", serverURL, userName, password,|
//                              dirName, fileName, fileData, connectFlags,    |
//                              openFileFlags )
//
// ----------------------------------------------------------------------------
// [i] serverURL     : standard ftp:// URL (poss. including port)         [req]
// [i] userName      : Username used to authenticate to the server
// [i] password      : Password used to authenticate to the server
// [i] dirName       : Directory on the FTP server to write to 
// [i] fileName      : Filename to write to                               [req]
// [i] fileData      : Data to write to the file 
// [i] connectFlags  : Bitmask of flags to use for the connection (see the 
//                   : "dwFlags" parmater in the InternetConnect() docs)
// [i] openFileFlags : Bitmask of flags to use for the transfer (see the 
//                   : "dwFlags" parameter in the FtpOpenFile() docs)
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file is transferred successfully, or FALSE$ 
//     otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------


///////////////////////////////////////////////////////////////////////////////
// 
// SETCURRENTDIR method
//
// Sets the current directory for the connected FTP Server
//
//    bSuccess = rti_FTPClient( "SETCURRENTDIR", hClient, dirName )   
//
// ----------------------------------------------------------------------------
// [i] hClient : Connection handles returned from a CONNECT method        [req]
// [i] dirName : Directory to set                                         [req]
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the directory is set, or FALSE$ otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// WRITEFILE method
//
// Transfers a file to the connected FTP Server
//
//    bSuccess = rti_FTPClient( "WRITEFILE", hClient, sourceFile, targetFile, |
//                              putFileFlags )
//
// ----------------------------------------------------------------------------
// [i] hClient       : Connection handles returned from a CONNECT method  [req]
// [i] sourceFile    : Name and path of the local file to send            [req]
// [i] targetFile    : Name and path to write the file to on the server   [req]
// [i] putFileFlags  : Bitmask of flags to use for the transfer (see the 
//                   : "dwFlags" parmater in the FtpPutFile() docs)
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file is transferred successfully
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ---------------------------------------------------------------------------- 


///////////////////////////////////////////////////////////////////////////////
// 
// WRITEFILEDATA method
//
// Transfers a chunk of file contents to the connected FTP Server.  This
// method is designed to be used in a loop until all of the contents are 
// sent.
//
//    fileName      = "/tmp/test.jpg"
//    openFileFlags = FTP_TRANSFER_TYPE_BINARY$ ; // This is the default
//    hFile         = 0
//    bFinished     = FALSE$
//      
//    loop
//       // Grab a chunk of data, e.g. from an OSBRead into the fileData
//       // variable.  If this is the last chunk then set bFinished to 
//       // TRUE$
//
//       ...
//       
//       // Then send it to the server 
//       if rti_FTPClient( "WRITEFILEDATA", hClient, fileName,         |
//                         openFileFlags, fileData, hFile, bFinished ) else
//
//          // Handle error - bFinished will be set to TRUE$ and hFile
//          // released
//          call get_Status( errText ) then
//       end
//
//    until bFinished
//       // Report progess etc...
//    repeat
//
// ----------------------------------------------------------------------------
// [i]   hClient       : Connection handles returned from a CONNECT method       [req]
// [i]   fileName      : Path and file name to write to on the server            [req]
// [i]   openFileFlags : Bitmask of flags to use for the transfer (see the 
//                     : "dwFlags" parameter in the FtpOpenFile() docs).  
//                     : Defaults to FTP_TRANSFER_TYPE_BINARY$
// [i]   fileData      : Data to transfer. If null then the method assumes that
//                     : the transfer operation has finished.
// [i,o] hFile         : Internal file transfer handle - must be initialized     [req]
//                     : to 0.  This handle is closed automatically when the
//                     : bFinished parameter is set to TRUE$, or an error is
//                     : encountered.
// [i,o] bFinished     : Must be set to TRUE$ when the last file chunk is sent.  [req]
//                     : Will also be set to TRUE$ by the system if an error is 
//                     : encountered.
// ----------------------------------------------------------------------------
// [r] Returns TRUE$ if the file chunk was transferred successfully, or FALSE$
//     otherwise.
// ----------------------------------------------------------------------------
// [e] Errors are returned via Set_Status
// ----------------------------------------------------------------------------

   
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
#endif
///////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////
