FileAccess C Library Reference

FileAccess

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/library. 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 CkFileAccess_Create(void);

Creates an instance of the CkFileAccess object and returns a handle (i.e. a "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.

C "Properties"

void CkFileAccess_getCurrentDir(HCkFileAccess cHandle, HCkString retval);

The current working directory of the calling process.

BOOL CkFileAccess_getEndOfFile(HCkFileAccess cHandle);

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

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.

void CkFileAccess_getFileOpenErrorMsg(HCkFileAccess cHandle, HCkString retval);

The error message text associated with the FileOpenError code.

void CkFileAccess_getLastErrorHtml(HCkFileAccess cHandle, HCkString retval);

Error information in HTML format for the last method called.

void CkFileAccess_getLastErrorText(HCkFileAccess cHandle, HCkString retval);

Error information in plain-text format for the last method called.

void CkFileAccess_getLastErrorXml(HCkFileAccess cHandle, HCkString retval);

Error information in XML format for the last method called.

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

To be documented soon...

C "Methods"

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.

BOOL CkFileAccess_AppendText(HCkFileAccess cHandle, const char *text, 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.

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.

BOOL CkFileAccess_AppendUtf8BOM(HCkFileAccess cHandle);

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

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_DirAutoCreate(HCkFileAccess cHandle, const char *path);

Creates all directories necessary such that the entire dirPath exists.

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_DirCreate(HCkFileAccess cHandle, const char *path);

Creates a new directory specified by dirPath.

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_DirDelete(HCkFileAccess cHandle, const char *path);

Deletes the directory specified by dirPath.

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_DirEnsureExists(HCkFileAccess cHandle, const char *filePath);

Same as DirAutoCreate, 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.

void CkFileAccess_FileClose(HCkFileAccess cHandle);

Closes the currently open file.

BOOL CkFileAccess_FileCopy(HCkFileAccess cHandle, const char *existing, const char *newFilename, 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.

BOOL CkFileAccess_FileDelete(HCkFileAccess cHandle, const char *filename);

Deletes the file specified by filePath.

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_FileExists(HCkFileAccess cHandle, const char *filename);

Returns true if filePath exists, otherwise returns false.

BOOL CkFileAccess_FileRead(HCkFileAccess cHandle, int numBytes, 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.

BOOL CkFileAccess_FileRename(HCkFileAccess cHandle, const char *existing, const char *newFilename);

Renames a file from existingFilepath to newFilepath.

Returns TRUE for success, FALSE for failure.

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.

int CkFileAccess_FileSize(HCkFileAccess cHandle, const char *filename);

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

BOOL CkFileAccess_FileWrite(HCkFileAccess cHandle, HCkByteData data);

Writes bytes to the currently open file.

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_GetTempFilename(HCkFileAccess cHandle, const char *dirName, const char *prefix, HCkString outStr);

To be documented soon.

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.

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.

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.

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.

BOOL CkFileAccess_ReadBinaryToEncoded(HCkFileAccess cHandle, const char *filename, const char *encoding, HCkString outStr);

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.

BOOL CkFileAccess_ReadEntireFile(HCkFileAccess cHandle, const char *filename, HCkByteData outBytes);

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

BOOL CkFileAccess_ReadEntireTextFile(HCkFileAccess cHandle, const char *filename, const char *charset, HCkString outStrFileContents);

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.

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.

BOOL CkFileAccess_SaveLastError(HCkFileAccess cHandle, const char *filename);

Saves the last error information to an XML formatted file.

BOOL CkFileAccess_SetCurrentDir(HCkFileAccess cHandle, const char *path);

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

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

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

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.

BOOL CkFileAccess_WriteEntireFile(HCkFileAccess cHandle, const char *filename, HCkByteData fileData);

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

Returns TRUE for success, FALSE for failure.

BOOL CkFileAccess_WriteEntireTextFile(HCkFileAccess cHandle, const char *filename, const char *fileData, const char *charset, BOOL includePreamble);

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.

const char *CkFileAccess_currentDir(HCkFileAccess cHandle);

The current working directory of the calling process.

Returns a null on failure

const char *CkFileAccess_fileOpenErrorMsg(HCkFileAccess cHandle);

The error message text associated with the FileOpenError code.

Returns a null on failure

const char *CkFileAccess_getTempFilename(HCkFileAccess cHandle, const char *dirName, const char *prefix);

To be documented soon.

Returns a null on failure

const char *CkFileAccess_lastErrorHtml(HCkFileAccess cHandle);

Error information in HTML format for the last method called.

Returns a null on failure

const char *CkFileAccess_lastErrorText(HCkFileAccess cHandle);

Error information in plain-text format for the last method called.

Returns a null on failure

const char *CkFileAccess_lastErrorXml(HCkFileAccess cHandle);

Error information in XML format for the last method called.

Returns a null on failure

const char *CkFileAccess_readBinaryToEncoded(HCkFileAccess cHandle, const char *filename, 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 a null on failure

const char *CkFileAccess_readEntireTextFile(HCkFileAccess cHandle, const char *filename, 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 a null on failure