FileAccess C Reference Documentation

FileAccess

Current Version: 9.5.0.75

API for reading and writing files, creating and deleting directories, deleting directory trees, splitting and re-joining large files, etc. This is a freeware class. The reason for its existence is that in some programming languages, file I/O API's are limited or difficult to understand/use. This API provides an identical FILE I/O API across all programming languages supported by Chilkat.

Create/Dispose

HCkFileAccess instance = CkFileAccess_Create();
// ...
CkFileAccess_Dispose(instance);
HCkFileAccess CkFileAccess_Create(void);

Creates an instance of the HCkFileAccess object and returns a handle ("void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkFileAccess_Dispose(HCkFileAccess handle);

Objects created by calling CkFileAccess_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkFileAccess_Dispose.

Properties

CurrentDir
void CkFileAccess_getCurrentDir(HCkFileAccess cHandle, HCkString retval);
const char *CkFileAccess_currentDir(HCkFileAccess cHandle);

The current working directory of the calling process.

top
DebugLogFilePath
void CkFileAccess_getDebugLogFilePath(HCkFileAccess cHandle, HCkString retval);
void CkFileAccess_putDebugLogFilePath(HCkFileAccess cHandle, const char *newVal);
const char *CkFileAccess_debugLogFilePath(HCkFileAccess cHandle);

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

top
EndOfFile
BOOL CkFileAccess_getEndOfFile(HCkFileAccess cHandle);

Returns TRUE if the current open file is at the end-of-file.

top
FileOpenError
int CkFileAccess_getFileOpenError(HCkFileAccess cHandle);

This property is set by the following methods: FileOpen, OpenForRead, OpenForWrite, OpenForReadWrite, and OpenForAppend. It provides an error code indicating the failure reason. Possible values are:

  1. Success (No error)
  2. Access denied.
  3. File not found.
  4. General (non-specific) open error.
  5. File aleady exists.
  6. Path refers to a directory and the access requested involves writing.
  7. Too many symbolic links were encountered in resolving path.
  8. The process already has the maximum number of files open.
  9. Pathname is too long.
  10. The system limit on the total number of open files has been reached.
  11. Pathname refers to a device special file and no corresponding device exists.
  12. Insufficient kernel memory was available.
  13. Pathname was to be created but the device containing pathname has no room for the new file.
  14. A component used as a directory in pathname is not, in fact, a directory.
  15. Pathname refers to a regular file, too large to be opened (this would be a limitation of the underlying operating system, not a limitation imposed by Chilkat).
  16. Pathname refers to a file on a read-only filesystem and write access was requested.

top
FileOpenErrorMsg
void CkFileAccess_getFileOpenErrorMsg(HCkFileAccess cHandle, HCkString retval);
const char *CkFileAccess_fileOpenErrorMsg(HCkFileAccess cHandle);

The error message text associated with the FileOpenError code.

top
LastErrorHtml
void CkFileAccess_getLastErrorHtml(HCkFileAccess cHandle, HCkString retval);
const char *CkFileAccess_lastErrorHtml(HCkFileAccess cHandle);

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorText
void CkFileAccess_getLastErrorText(HCkFileAccess cHandle, HCkString retval);
const char *CkFileAccess_lastErrorText(HCkFileAccess cHandle);

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorXml
void CkFileAccess_getLastErrorXml(HCkFileAccess cHandle, HCkString retval);
const char *CkFileAccess_lastErrorXml(HCkFileAccess cHandle);

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastMethodSuccess
BOOL CkFileAccess_getLastMethodSuccess(HCkFileAccess cHandle);
void CkFileAccess_putLastMethodSuccess(HCkFileAccess cHandle, BOOL newVal);
Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of TRUE indicates success, a value of FALSE indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = TRUE and failure = FALSE.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to TRUE. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

top
Utf8
BOOL CkFileAccess_getUtf8(HCkFileAccess cHandle);
void CkFileAccess_putUtf8(HCkFileAccess cHandle, BOOL newVal);

When set to TRUE, all "const char *" arguments are interpreted as utf-8 strings. If set to FALSE (the default), then "const char *" arguments are interpreted as ANSI strings. Also, when set to TRUE, and Chilkat method returning a "const char *" is returning the utf-8 representation. If set to FALSE, all "const char *" return values are ANSI strings.

top
VerboseLogging
BOOL CkFileAccess_getVerboseLogging(HCkFileAccess cHandle);
void CkFileAccess_putVerboseLogging(HCkFileAccess cHandle, BOOL newVal);

If set to TRUE, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is FALSE. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
void CkFileAccess_getVersion(HCkFileAccess cHandle, HCkString retval);
const char *CkFileAccess_version(HCkFileAccess cHandle);

Version of the component/library, such as "9.5.0.63"

top

Methods

AppendAnsi
BOOL CkFileAccess_AppendAnsi(HCkFileAccess cHandle, const char *text);

Appends a string using the ANSI character encoding to the currently open file.

Returns TRUE for success, FALSE for failure.

top
AppendText
BOOL CkFileAccess_AppendText(HCkFileAccess cHandle, const char *str, const char *charset);

Appends a string using the character encoding specified by str to the currently open file.

Returns TRUE for success, FALSE for failure.

top
AppendUnicodeBOM
BOOL CkFileAccess_AppendUnicodeBOM(HCkFileAccess cHandle);

Appends the 2-byte Unicode BOM (little endian) to the currently open file.

Returns TRUE for success, FALSE for failure.

top
AppendUtf8BOM
BOOL CkFileAccess_AppendUtf8BOM(HCkFileAccess cHandle);

Appends the 3-byte utf-8 BOM to the currently open file.

Returns TRUE for success, FALSE for failure.

top
DirAutoCreate
BOOL CkFileAccess_DirAutoCreate(HCkFileAccess cHandle, const char *filePath);

Same as DirEnsureExists, except the argument is a file path (the last part of the path is a filename and not a directory). Creates all missing directories such that filePath may be created.

Returns TRUE for success, FALSE for failure.

top
DirCreate
BOOL CkFileAccess_DirCreate(HCkFileAccess cHandle, const char *dirPath);

Creates a new directory specified by dirPath.

Returns TRUE for success, FALSE for failure.

top
DirDelete
BOOL CkFileAccess_DirDelete(HCkFileAccess cHandle, const char *dirPath);

Deletes the directory specified by dirPath.

Returns TRUE for success, FALSE for failure.

top
DirEnsureExists
BOOL CkFileAccess_DirEnsureExists(HCkFileAccess cHandle, const char *dirPath);

Creates all directories necessary such that the entire dirPath exists.

Returns TRUE for success, FALSE for failure.

top
FileClose
void CkFileAccess_FileClose(HCkFileAccess cHandle);

Closes the currently open file.

top
FileContentsEqual
BOOL CkFileAccess_FileContentsEqual(HCkFileAccess cHandle, const char *filePath1, const char *filePath2);

Compares the contents of two files and returns TRUE if they are equal and otherwise returns FALSE. The actual contents of the files are only compared if the sizes are equal. The files are not entirely loaded into memory. Instead, they are compared chunk by chunk. This allows for any size files to be compared, regardless of the memory capacity of the computer.

top
FileCopy
BOOL CkFileAccess_FileCopy(HCkFileAccess cHandle, const char *existingFilepath, const char *newFilepath, BOOL failIfExists);

Copys existingFilepath to newFilepath. If failIfExists is TRUE and newFilepath already exists, then an error is returned.

Returns TRUE for success, FALSE for failure.

top
FileDelete
BOOL CkFileAccess_FileDelete(HCkFileAccess cHandle, const char *filePath);

Deletes the file specified by filePath.

Returns TRUE for success, FALSE for failure.

top
FileExists
BOOL CkFileAccess_FileExists(HCkFileAccess cHandle, const char *filePath);

Returns TRUE if filePath exists, otherwise returns FALSE.

top
FileExists3
int CkFileAccess_FileExists3(HCkFileAccess cHandle, const char *path);
Introduced in version 9.5.0.45

Returns 1 if the file exists, 0 if the file does not exist, and -1 if unable to check because of directory permissions or some other error that prevents the ability to obtain the information.

top
FileOpen
BOOL CkFileAccess_FileOpen(HCkFileAccess cHandle, const char *filePath, unsigned long accessMode, unsigned long shareMode, unsigned long createDisposition, unsigned long attributes);

This method should only be called on Windows operating systems. It's arguments are similar to the Windows Platform SDK function named CreateFile. For Linux, MAC OS X, and other operating system, use the OpenForRead, OpenForWrite, OpenForReadWrite, and OpenForAppend methods.

Opens a file for reading or writing. The arguments mirror the Windows CreateFile function:

Access Modes:
GENERIC_READ	(0x80000000)
GENERIC_WRITE (0x40000000)

Share Modes:
FILE_SHARE_READ(0x00000001)
FILE_SHARE_WRITE(0x00000002)

Create Dispositions
CREATE_NEW          1
CREATE_ALWAYS       2
OPEN_EXISTING       3
OPEN_ALWAYS         4
TRUNCATE_EXISTING   5

// Attributes:
FILE_ATTRIBUTE_READONLY         0x00000001
FILE_ATTRIBUTE_HIDDEN           0x00000002
FILE_ATTRIBUTE_SYSTEM           0x00000004
FILE_ATTRIBUTE_DIRECTORY        0x00000010
FILE_ATTRIBUTE_ARCHIVE          0x00000020
FILE_ATTRIBUTE_NORMAL           0x00000080
FILE_ATTRIBUTE_TEMPORARY	   0x00000100

Returns TRUE for success, FALSE for failure.

top
FileRead
BOOL CkFileAccess_FileRead(HCkFileAccess cHandle, int maxNumBytes, HCkByteData outBytes);

Reads bytes from the currently open file. maxNumBytes specifies the maximum number of bytes to read. Returns an empty byte array on error.

Returns TRUE for success, FALSE for failure.

top
FileReadBd
BOOL CkFileAccess_FileReadBd(HCkFileAccess cHandle, int maxNumBytes, HCkBinData binData);
Introduced in version 9.5.0.64

Reads bytes from the currently open file. maxNumBytes specifies the maximum number of bytes to read. Appends the bytes to the binData.

Returns TRUE for success, FALSE for failure.

top
FileRename
BOOL CkFileAccess_FileRename(HCkFileAccess cHandle, const char *existingFilepath, const char *newFilepath);

Renames a file from existingFilepath to newFilepath.

Returns TRUE for success, FALSE for failure.

top
FileSeek
BOOL CkFileAccess_FileSeek(HCkFileAccess cHandle, int offset, int origin);

Sets the file pointer for the currently open file. The offset is an offset in bytes from the origin. The origin can be one of the following:

0 = Offset is from beginning of file.
1 = Offset is from current position of file pointer.
2 = Offset is from the end-of-file (offset may be negative).

Returns TRUE for success, FALSE for failure.

top
FileSize
int CkFileAccess_FileSize(HCkFileAccess cHandle, const char *filePath);

Returns the size, in bytes, of a file. Returns -1 for failure.

Returns TRUE for success, FALSE for failure.

top
FileWrite
BOOL CkFileAccess_FileWrite(HCkFileAccess cHandle, HCkByteData data);

Writes bytes to the currently open file.

Returns TRUE for success, FALSE for failure.

top
FileWriteBd
BOOL CkFileAccess_FileWriteBd(HCkFileAccess cHandle, HCkBinData binData, int offset, int numBytes);
Introduced in version 9.5.0.64

Writes the contents of binData to the currently open file. To specify the entire contents of binData, set both offset and numBytes equal to 0. To write all remaining data starting at offset, then set numBytes equal to 0.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
GenBlockId
BOOL CkFileAccess_GenBlockId(HCkFileAccess cHandle, int index, int length, const char *encoding, HCkString outStr);
const char *CkFileAccess_genBlockId(HCkFileAccess cHandle, int index, int length, const char *encoding);
Introduced in version 9.5.0.58

This is purely a utility/convenience method -- initially created to help with block file uploads to Azure Blob storage. It generates a block ID string that is the decimal representation of the index in length chars, and then encoded according to encoding (which can be an encoding such as "base64", "hex", "ascii", etc.) For example, if index = 8, length = 12, and encoding = "base64", then the string "00000012" is returned base64 encoded.

Returns TRUE for success, FALSE for failure.

top
GetDirectoryName
BOOL CkFileAccess_GetDirectoryName(HCkFileAccess cHandle, const char *path, HCkString outStr);
const char *CkFileAccess_getDirectoryName(HCkFileAccess cHandle, const char *path);
Introduced in version 9.5.0.64

Returns the directory information for the specified path string.

GetDirectoryName('C:\MyDir\MySubDir\myfile.ext') returns 'C:\MyDir\MySubDir\'
GetDirectoryName('C:\MyDir\MySubDir') returns 'C:\MyDir\'
GetDirectoryName('C:\MyDir\') returns 'C:\MyDir\'
GetDirectoryName('C:\MyDir') returns 'C:\'
GetDirectoryName('C:\') returns 'C:\'

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
GetExtension
BOOL CkFileAccess_GetExtension(HCkFileAccess cHandle, const char *path, HCkString outStr);
const char *CkFileAccess_getExtension(HCkFileAccess cHandle, const char *path);
Introduced in version 9.5.0.64

Returns the extension of the specified path string.

GetExtension('C:\mydir.old\myfile.ext') returns '.ext'
GetExtension('C:\mydir.old\') returns ''

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
GetFileName
BOOL CkFileAccess_GetFileName(HCkFileAccess cHandle, const char *path, HCkString outStr);
const char *CkFileAccess_getFileName(HCkFileAccess cHandle, const char *path);
Introduced in version 9.5.0.64

Returns the file name and extension of the specified path string.

GetFileName('C:\mydir\myfile.ext') returns 'myfile.ext'
GetFileName('C:\mydir\') returns ''

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
GetFileNameWithoutExtension
BOOL CkFileAccess_GetFileNameWithoutExtension(HCkFileAccess cHandle, const char *path, HCkString outStr);
const char *CkFileAccess_getFileNameWithoutExtension(HCkFileAccess cHandle, const char *path);
Introduced in version 9.5.0.64

Returns the file name of the specified path string without the extension.

GetFileNameWithoutExtension('C:\mydir\myfile.ext') returns 'myfile'
GetFileNameWithoutExtension('C:\mydir\') returns ''

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
GetFileTime
HCkDateTime CkFileAccess_GetFileTime(HCkFileAccess cHandle, const char *path, int which);
Introduced in version 9.5.0.71

Gets one of the following date/times for a file:

0: Last-modified
1: Last-access
2: Creation
The "path" argument indicates which time to return. The values can be 0, 1, or 2.

Note: Linux filesystems do not keep a file's creation date/time. In such a case, this method will return the last-modified time.

Returns NULL on failure

top
GetLastModified
HCkDateTime CkFileAccess_GetLastModified(HCkFileAccess cHandle, const char *path);
Introduced in version 9.5.0.66

Gets the last-modified date/time for a file.

Returns NULL on failure

top
GetNumBlocks
int CkFileAccess_GetNumBlocks(HCkFileAccess cHandle, int blockSize);
Introduced in version 9.5.0.58

Returns the number of blocks in the currently open file. The number of bytes per block is specified by blockSize. The number of blocks is the file size divided by the blockSize, plus 1 if the file size is not evenly divisible by blockSize. For example, if the currently open file is 60500 bytes, and if the blockSize is 1000 bytes, then this method returns a count of 61 blocks.

Returns -1 if no file is open. Return 0 if the file is completely empty (0 bytes).

More Information and Examples
top
GetTempFilename
BOOL CkFileAccess_GetTempFilename(HCkFileAccess cHandle, const char *dirPath, const char *prefix, HCkString outStr);
const char *CkFileAccess_getTempFilename(HCkFileAccess cHandle, const char *dirPath, const char *prefix);

Creates a temporary filepath of the form dirPath\prefix_xxxx.TMP Where "xxxx" are random alpha-numeric chars. The returned filepath is guaranteed to not already exist.

Returns TRUE for success, FALSE for failure.

top
OpenForAppend
BOOL CkFileAccess_OpenForAppend(HCkFileAccess cHandle, const char *filePath);

Opens a file for appending. If filePath did not already exists, it is created. When an existing file is opened with this method, the contents will not be overwritten and the file pointer is positioned at the end of the file.

If the open/create failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns TRUE for success, FALSE for failure.

top
OpenForRead
BOOL CkFileAccess_OpenForRead(HCkFileAccess cHandle, const char *filePath);

Opens a file for reading. The file may contain any type of data (binary or text) and it must already exist. If the open failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns TRUE for success, FALSE for failure.

top
OpenForReadWrite
BOOL CkFileAccess_OpenForReadWrite(HCkFileAccess cHandle, const char *filePath);

Opens a file for reading/writing. If filePath did not already exists, it is created. When an existing file is opened with this method, the contents will not be overwritten, but the file pointer is positioned at the beginning of the file.

If the open/create failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns TRUE for success, FALSE for failure.

top
OpenForWrite
BOOL CkFileAccess_OpenForWrite(HCkFileAccess cHandle, const char *filePath);

Opens a file for writing. If filePath did not already exists, it is created. When an existing file is opened with this method, the contents will be overwritten. (For example, calling OpenForWrite on an existing file and then immediately closing the file will result in an empty file.) If the open/create failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns TRUE for success, FALSE for failure.

top
ReadBinaryToEncoded
BOOL CkFileAccess_ReadBinaryToEncoded(HCkFileAccess cHandle, const char *filePath, const char *encoding, HCkString outStr);
const char *CkFileAccess_readBinaryToEncoded(HCkFileAccess cHandle, const char *filePath, const char *encoding);

Reads the entire contents of a binary file and returns it as an encoded string (using an encoding such as Base64, Hex, etc.) The encoding may be one of the following strings: base64, hex, qp, or url.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ReadBlock
BOOL CkFileAccess_ReadBlock(HCkFileAccess cHandle, int blockIndex, int blockSize, HCkByteData outBytes);
Introduced in version 9.5.0.58

Reads the Nth block of a file, where the size of each block is specified by blockSize. The first block is at blockIndex 0. If the block to be read is the last in the file and there is not enough data to fill an entire block, then the partial block is returned.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ReadEntireFile
BOOL CkFileAccess_ReadEntireFile(HCkFileAccess cHandle, const char *filePath, HCkByteData outBytes);

Reads the entire contents of a binary file and returns the data.

Returns TRUE for success, FALSE for failure.

top
ReadEntireTextFile
BOOL CkFileAccess_ReadEntireTextFile(HCkFileAccess cHandle, const char *filePath, const char *charset, HCkString outStrFileContents);
const char *CkFileAccess_readEntireTextFile(HCkFileAccess cHandle, const char *filePath, const char *charset);

Reads the entire contents of a text file, interprets the bytes according to the character encoding specified by charset, and returns the text file as a string.

Returns TRUE for success, FALSE for failure.

top
ReassembleFile
BOOL CkFileAccess_ReassembleFile(HCkFileAccess cHandle, const char *partsDirPath, const char *partPrefix, const char *partExtension, const char *reassembledFilename);

Reassembles a file previously split by the SplitFile method.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
ReplaceStrings
int CkFileAccess_ReplaceStrings(HCkFileAccess cHandle, const char *filePath, const char *charset, const char *existingString, const char *replacementString);

Replaces all occurrences of existingString with replacementString in a file. The character encoding, such as utf-8, ansi, etc. is specified by charset.

top
SaveLastError
BOOL CkFileAccess_SaveLastError(HCkFileAccess cHandle, const char *path);

Saves the last-error information (the contents of LastErrorXml) to an XML formatted file.

Returns TRUE for success, FALSE for failure.

top
SetCurrentDir
BOOL CkFileAccess_SetCurrentDir(HCkFileAccess cHandle, const char *dirPath);

Sets the current working directory for the calling process to dirPath.

Returns TRUE for success, FALSE for failure.

top
SetFileTimes
BOOL CkFileAccess_SetFileTimes(HCkFileAccess cHandle, const char *filePath, HCkDateTime createTime, HCkDateTime lastAccessTime, HCkDateTime lastModTime);

Sets the create date/time, the last-access date/time, and the last-modified date/time for a file. For non-Windows filesystems where create times are not implemented, the createTime is ignored.

top
SetLastModified
BOOL CkFileAccess_SetLastModified(HCkFileAccess cHandle, const char *filePath, HCkDateTime lastModified);

Sets the last-modified date/time for a file.

top
SplitFile
BOOL CkFileAccess_SplitFile(HCkFileAccess cHandle, const char *fileToSplit, const char *partPrefix, const char *partExtension, int partSize, const char *destDir);

Splits a file into chunks. Please refer to the example below:

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
TreeDelete
BOOL CkFileAccess_TreeDelete(HCkFileAccess cHandle, const char *path);

Deletes an entire directory tree (all files and sub-directories).

Returns TRUE for success, FALSE for failure.

top
WriteEntireFile
BOOL CkFileAccess_WriteEntireFile(HCkFileAccess cHandle, const char *filePath, HCkByteData fileData);

Opens/creates filePath, writes fileData, and closes the file.

Returns TRUE for success, FALSE for failure.

top
WriteEntireTextFile
BOOL CkFileAccess_WriteEntireTextFile(HCkFileAccess cHandle, const char *filePath, const char *textData, const char *charset, BOOL includedPreamble);

Opens filePath, writes textData using the character encoding specified by charset, and closes the file. If includedPreamble is TRUE and the charset is Unicode or utf-8, then the BOM is included at the beginning of the file.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top