Loading...
Searching...
No Matches
FileLocationHandler Module

# Introduction to the FileLocationHandler Module

The FileLocationHandler module provides an API for returning file data based on a URL-like location string.

To retrieve file data, call one of:

- FileLocationHandler::getTextFileFromLocation()
- FileLocationHandler::getBinaryFileFromLocation()
- FileLocationHandler::getStreamReaderFromLocation()
- FileLocationHandler::getBinaryStreamFromLocation()

To write file data, call one of:

- FileLocationHandler::writeFileToLocation()
- FileLocationHandler::getOutputStreamForLocation()

To register a location handler based on a scheme, call one of:

- FileLocationHandler::registerHandler()
- FileLocationHandler::tryRegisterHandler()

This module provides the following classes:

- AbstractFileLocationHandler: the abstract API class
- FileLocationHandler: the main API class
- FileLocationHandlerData: class handling `"data://"` locations (immedidate data in the location URL)
- FileLocationHandlerFile: class handling `"file://"` locations (the default if no scheme is present in the location string)
- FileLocationHandlerFtp: class handling `"ftp://"` and `"ftps://"` locations
- FileLocationHandlerHttp: class handling `"http://"` and `"https://"` locations
- FileLocationHandlerRest: class handling `"rest://"` and `"rests://"` locations
- FileLocationHandlerSftp: class handling `"sftp://"` locations
- OutputStreamWrapper: output stream wrapper class for handling background I/O operations

# FileLocationHandler Environment variable

The `QORE_FILE_LOCATION_HANDLERS` environment variable will be read to initialize modules that provide support for custom URL schemes; multiple modules can be separated by the OS-specific path separator (``: on Linux / UNIX, ``; on Windows).

Each module listed in this environment variable should call either FileLocationHandler::registerHandler() or FileLocationHandler::tryRegisterHandler() in its `init` code to register a handler for a new scheme.

# Release Notes

## FileLocationHandler v2.3

- implemented support for non-blocking I/O from file handlers (issue 4764)

## FileLocationHandler v2.2.1

- allow handler information to be returned (issue 4726)

## FileLocationHandler v2.2

- added support for `rest://` and `rests://` locations (issue 4669)
- added support for runtime extensibility from environment variables (issue 4667)

## FileLocationHandler v2.1

- added support for immediate `data://` locations (issue 4626)

## FileLocationHandler v2.0

- updated for read/write operations and added streaming APIs (issue 4424)

## FileLocationHandler v1.0

- initial release of the module