Acts as a proxy for decompressing and compressing data streams between objects.
Use the CompressedStream class to compress and decompress data on the fly without the need for a temporary storage area. The default compression algorithm is DEFLATE with gzip header data. It is compatible with common command-line tools such as gzip.
To decompress data, set the Input field with a source object that supports the Read() action, such as a File. Repeatedly reading from the CompressedStream will automatically handle the decompression process. If the decompressed size of the incoming data is defined in the source header, it will be reflected in the Size field.
To compress data, set the Output field with a source object that supports the Write() action, such as a File. Repeatedly writing to the CompressedStream with raw data will automatically handle the compression process for you. Once all of the data has been written, call the Write() action with a Buffer of NULL and Length -1 to signal an end to the streaming process.
The CompressedStream class consists of the following fields:
Access | Name | Type | Comment | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Format | CF | The format of the compressed stream. The default is GZIP. | |||||||||
| |||||||||||
| Input | OBJECTPTR | An input object that will supply data for decompression. | |||||||||
To create a stream that decompresses data from a compressed source, set the Input field with a reference to an object that will provide the source data. It is most common for the source object to be a File type, however any class that supports the Read() action is permitted. The source object must be in a readable state. The Input field is mutually exclusive to the Output field. | |||||||||||
| Output | OBJECTPTR | A target object that will receive data compressed by the stream. | |||||||||
To create a stream that compresses data to a target object, set the Output field with an object reference. It is most common for the target object to be a File type, however any class that supports the Write() action is permitted. The target object must be in a writeable state. The Output field is mutually exclusive to the Input field. | |||||||||||
| Size | BIGINT | The uncompressed size of the input source, if known. | |||||||||
The Size field will reflect the uncompressed size of the input source, if this can be determined from the header. In the case of GZIP decompression, the size will not be known until the parser has consumed the header. This means that at least one call to the Read() action is required before the Size is known. If the size is unknown, a value of | |||||||||||
| TotalOutput | BIGINT | A live counter of total bytes that have been output by the stream. | |||||||||
Action identifiers.
| Name | Description |
|---|---|
| AC::Activate | |
| AC::Clear | |
| AC::Clipboard | |
| AC::CopyData | |
| AC::DataFeed | |
| AC::Deactivate | |
| AC::Disable | |
| AC::DragDrop | |
| AC::Draw | |
| AC::END | |
| AC::Enable | |
| AC::Flush | |
| AC::Focus | |
| AC::Free | |
| AC::FreeWarning | |
| AC::GetKey | |
| AC::Hide | |
| AC::Init | |
| AC::Lock | |
| AC::LostFocus | |
| AC::Move | |
| AC::MoveToBack | |
| AC::MoveToFront | |
| AC::MoveToPoint | |
| AC::NewChild | |
| AC::NewObject | |
| AC::NewOwner | |
| AC::NewPlacement | |
| AC::Next | |
| AC::Prev | |
| AC::Query | |
| AC::Read | |
| AC::Redimension | |
| AC::Redo | |
| AC::Refresh | |
| AC::Rename | |
| AC::Reset | |
| AC::Resize | |
| AC::SaveImage | |
| AC::SaveSettings | |
| AC::SaveToObject | |
| AC::Seek | |
| AC::SetField | |
| AC::SetKey | |
| AC::Show | |
| AC::Signal | |
| AC::Undo | |
| AC::Unlock | |
| AC::Write |
Compression stream formats
| Name | Description |
|---|---|
| CF::DEFLATE | The 'deflate' format |
| CF::GZIP | The 'gzip' format |
| CF::ZLIB | The 'zlib' format |
Event categories.
| Name | Description |
|---|---|
| EVG::ANDROID | Android specific events that do not already fit existing categories. |
| EVG::APP | Custom event dispatched from an application |
| EVG::AUDIO | Audio system events. |
| EVG::CLASS | Custom event dispatched from a class that doesn't fit within the rest of the event framework |
| EVG::DISPLAY | Video display events. |
| EVG::FILESYSTEM | File system events. |
| EVG::GUI | Events generated by the Graphical User Interface. |
| EVG::HARDWARE | Hardware device events that are not covered by other types. |
| EVG::IO | Input/Output events. |
| EVG::NETWORK | Network events. |
| EVG::POWER | Power Management - can also include app-specific events relating to resource management. |
| EVG::SYSTEM | System-wide events |
| EVG::USER | User activity events (such as user login). |
Flags that can be passed to FindObject()
| Name | Description |
|---|---|
| FOF::SMART_NAMES | Parse numeric object names as ID references and support use of the 'Owner' reserved keyword. |
Types for AllocateID()
| Name | Description |
|---|---|
| IDTYPE::FUNCTION | Function ID's are used to track FUNCTION types and are assigned to the function ID field. |
| IDTYPE::GLOBAL | Global ID's have no specific association with anything. |
| IDTYPE::MESSAGE | Message ID's are allocated for the purpose of sending uniquely identifiable messages between tasks. |
Flags for LoadFile()
| Name | Description |
|---|---|
| LDF::CHECK_EXISTS | Limits the routine to checking the file cache for the existence of the file. If found, the relevant cache entry is returned. The open count is not incremented by this action (it is therefore unnecessary to follow-up with a call to UnloadFile()). If no up-to-date cache entry is available, ERR::Search is returned. |
AnalysePath() values
| Name | Description |
|---|---|
| LOC::DIRECTORY | The path refers to a folder. |
| LOC::FILE | The path refers to a file. |
| LOC::VOLUME | The path refers to a volume name. |
Memory types used by AllocMemory(). The lower 16 bits are stored with allocated blocks, the upper 16 bits are function-relative only.
| Name | Description |
|---|---|
| MEM::AUDIO | The memory space is reserved by an audio device such as a sound card. |
| MEM::CALLER | This flag is usable only in routines that are supporting a class method. It forces the memory allocation to be tracked to the object that made the method call. This is particularly important in methods that return memory blocks that do not form a part of the object itself. |
| MEM::CODE | Set if the memory will contain executable program code. |
| MEM::DATA | The default type, DATA, is used to indicate a standard memory allocation from system RAM. |
| MEM::HIDDEN | Hidden blocks are not recorded and are excluded from resource tracking. |
| MEM::MANAGED | Enables custom resource management for the memory block. The start of the block will need to be reserved with a pointer to a ResourceManager structure, which is included as part of the block's declared Size. The Free() callback will be called when the block is removed. |
| MEM::NO_BLOCK | Permanently turn off all accesses to this memory block. This means that multiple threads can have full read/write access to the memory block at once regardless of other acces flags. |
| MEM::NO_BLOCKING | Permanently turn off all accesses to this memory block. This means that multiple threads can have full read/write access to the memory block at once regardless of other acces flags. |
| MEM::NO_CLEAR | Do not clear the memory on allocation (saves time). |
| MEM::NO_LOCK | For AllocMemory() only, indicates that the (private) memory block should not be locked on return. |
| MEM::NO_POOL | Gives a hint to the allocator to allocate the block outside of the memory pool. |
| MEM::READ | The memory is explicitly marked as readable. |
| MEM::READ_WRITE | Synonym for READ | WRITE |
| MEM::STRING | Identifies the memory content as a null terminated string. Useful for debugging and run-time type identification in scripts. |
| MEM::TEXTURE | The memory space is reserved by a video driver for hosting texture graphics. |
| MEM::TMP_LOCK | Enables temporary locking restrictions. Prevents processes from sleeping while holding a lock on the memory block. |
| MEM::UNTRACKED | Allocating an untracked memory block will prevent the memory block from being tracked back to the object holding the current context. |
| MEM::VIDEO | The memory space is reserved by a video device such as a graphics card for display purposes, e.g. framebuffer. |
| MEM::WRITE | The memory is explicitly marked as writeable. |
Message flags.
| Name | Description |
|---|---|
| MSF::ADD | The default behaviour - this will add the message to the end of the queue. |
| MSF::MESSAGE_ID | The Type parameter refers to a unique message ID rather than a message type for this call. |
| MSF::NO_DUPLICATE | If the Type parameter matches a message already inside the queue, the new message will not be added and the function will immediately return with ERR::Okay. |
| MSF::UPDATE | If the Type parameter matches a message already inside the queue, the data for that message will be deleted, then the new message will be added to the end of the queue. |
| MSF::WAIT | Wait before inserting the message if the queue is at maximum capacity. |
Reserved message ID's that are handled internally.
| Name | Description |
|---|---|
| MSGID::ACTION | |
| MSGID::BREAK | |
| MSGID::COMMAND | |
| MSGID::CORE_END | |
| MSGID::DEBUG | |
| MSGID::EVENT | |
| MSGID::FREE | |
| MSGID::QUIT | |
| MSGID::THREAD_ACTION | |
| MSGID::THREAD_CALLBACK | |
| MSGID::VALIDATE_PROCESS | |
| MSGID::WAIT_FOR_OBJECTS |
Flags that can be passed to NewObject(). If a flag needs to be stored with the object, it must be specified in the lower word.
| Name | Description |
|---|---|
| NF::COLLECT | Marked for garbage collection. |
| NF::FREE | Read-only indicator for when the object is being freed. |
| NF::FREE_ON_UNLOCK | Read-only indicator for when the object is marked for deletion. |
| NF::INITIALISED | Read-only indicator if the object has been initialised. |
| NF::LOCAL | Classes can allocate local objects to stop them from being associated with the client. |
| NF::MESSAGE | Action has been called against the object through the message system (managed by ProcessMessages()). |
| NF::NAME | Use the Name parameter to name the created object. This flag is not required if using UNIQUE. |
| NF::PRIVATE | |
| NF::RECLASSED | The object switched from the base-class to a sub-class during initialisation. |
| NF::SIGNALLED | The object has been signalled and is awaiting processing. |
| NF::TIMER_SUB | The object is subscribed to a timer interval. |
| NF::UNIQUE | Use to allocate an object that has a guaranteed unique name. This will prevent code from shadowing any object that exists with the same name, which can be imperative when creating shared objects. If it is discovered that an identically named object exists, NewObject() will return ERR::ObjectExists. This flag works in conjunction with the Name parameter. |
| NF::UNTRACKED | An object created with this flag will not be tracked back to the object that created it. |
Permission flags
| Name | Description |
|---|---|
| PERMIT::ALL_DELETE | Synonym for EVERYONE_DELETE |
| PERMIT::ALL_EXEC | Synonym for EVERYONE_EXEC |
| PERMIT::ALL_READ | Synonym for EVERYONE_READ |
| PERMIT::ALL_WRITE | Synonym for EVERYONE_WRITE |
| PERMIT::ARCHIVE | Marks the file for future backup. The flag should be cleared after the backup has succeeded. |
| PERMIT::DELETE | Owner can delete. If the file system does not support this, deletion is enabled via the WRITE flag. |
| PERMIT::EVERYONE_ACCESS | Synonym for EVERYONE_READ | EVERYONE_WRITE | EVERYONE_EXEC | EVERYONE_DELETE |
| PERMIT::EVERYONE_DELETE | Synonym for DELETE | GROUP_DELETE | OTHERS_DELETE |
| PERMIT::EVERYONE_EXEC | Synonym for EXEC | GROUP_EXEC | OTHERS_EXEC |
| PERMIT::EVERYONE_READ | Synonym for READ | GROUP_READ | OTHERS_READ |
| PERMIT::EVERYONE_READWRITE | Synonym for EVERYONE_READ | EVERYONE_WRITE |
| PERMIT::EVERYONE_WRITE | Synonym for WRITE | GROUP_WRITE | OTHERS_WRITE |
| PERMIT::EXEC | User/Owner can execute. |
| PERMIT::GROUP | Synonym for GROUP_READ | GROUP_WRITE | GROUP_EXEC | GROUP_DELETE |
| PERMIT::GROUPID | Allows executables to run with a set group id. |
| PERMIT::GROUP_DELETE | Group members can delete. |
| PERMIT::GROUP_EXEC | Group members can execute. |
| PERMIT::GROUP_READ | Group members can read. |
| PERMIT::GROUP_WRITE | Group members can write. |
| PERMIT::HIDDEN | Recommends that the file is hidden from view by default. |
| PERMIT::INHERIT | Inherit permissions from parent folder and logical OR them with preset permission flags. |
| PERMIT::NETWORK | File is hosted on another machine. |
| PERMIT::OFFLINE | File content for this networked file has not been cached on the local PC. |
| PERMIT::OTHERS | Synonym for OTHERS_READ | OTHERS_WRITE | OTHERS_EXEC | OTHERS_DELETE |
| PERMIT::OTHERS_DELETE | Others can delete. |
| PERMIT::OTHERS_EXEC | Others can execute. |
| PERMIT::OTHERS_READ | Others can read. |
| PERMIT::OTHERS_WRITE | Others can write. |
| PERMIT::PASSWORD | File is password protected. |
| PERMIT::READ | User/Owner has read access. This will not allow compiled code to be executed. |
| PERMIT::USER | Synonym for READ | WRITE | EXEC | DELETE |
| PERMIT::USERID | Allows executables to run with a set user id. |
| PERMIT::USER_EXEC | Synonym for EXEC |
| PERMIT::USER_READ | Synonym for READ |
| PERMIT::USER_WRITE | Synonym for WRITE |
| PERMIT::WRITE | User/Owner can write. |
Flags for ProcessMessages
| Name | Description |
|---|
Flags for the OpenDir() function.
| Name | Description |
|---|---|
| RDF::ARCHIVE | Feedback only - archive bit is set. |
| RDF::DATE | Retrieve the date stamp of each file. |
| RDF::FILE | Read all files in the folder. |
| RDF::FILES | Read all files in the folder. |
| RDF::FOLDER | Read all folders/volumes in the folder. |
| RDF::FOLDERS | Read all folders/volumes in the folder. |
| RDF::HIDDEN | Feedback only - file/folder is hidden. |
| RDF::LINK | Feedback only - file/folder is actually a link to another location. |
| RDF::PERMISSIONS | Get permission/security information. |
| RDF::QUALIFIED | Return fully qualified folder names (i.e. trailing slash or colon for each name). |
| RDF::QUALIFY | Return fully qualified folder names (i.e. trailing slash or colon for each name). |
| RDF::READ_ALL | Synonym for SIZE | DATE | PERMISSIONS | FILES | FOLDERS |
| RDF::READ_ONLY | Read-only (not permissions related and might indicate read-only media). |
| RDF::SIZE | Retrieve the byte size of each file. |
| RDF::STREAM | Path is connected via a stream, e.g. network connection. |
| RDF::TAGS | Receive additional information for each file, such as comments, author and copyright. The results are stored in the Tags field of each file. |
| RDF::TIME | Retrieve the date stamp of each file. |
| RDF::VIRTUAL | Path is to a virtual device. |
| RDF::VOLUME | Feedback only - indicates a volume. |
| Name | Description |
|---|---|
| RES::CORE_IDL | Refers to the Core module's compressed IDL string. |
| RES::CPU_SPEED | The average top-speed of all CPU cores in Mhz. |
| RES::FREE_MEMORY | The total amount of free memory. |
| RES::FREE_SWAP | The total amount of free swap memory. |
| RES::JNI_ENV | Return the current JNI environment string. |
| RES::KEY_STATE | Maintains the state of key qualifiers such as caps-lock and the shift keys. |
| RES::LOG_DEPTH | The current depth of log messages. |
| RES::LOG_LEVEL | The current level of log detail (larger numbers indicate more detail). |
| RES::MAX_PROCESSES | The maximum number of processes that can be supported at any time. |
| RES::OPEN_INFO | Pointer to the OpenInfo structure originally used to initialise the system. |
| RES::PRIVILEGED | This is set to true if the process has elevated privileges (such as superuser or administrative rights). |
| RES::PRIVILEGED_USER | If this value is set to 1, the process will operate in privileged mode (typically this enables full administrator rights). This feature will only work for Unix processes that are granted admin rights when launched. Setting the Value to 0 reverts to the user's permission settings. SetResource() will return an error code indicating the level of success. |
| RES::PROCESS_STATE | Life-cycle stage of the running process |
| RES::STATIC_BUILD | Returns true if the runtime is a statically linked build. |
| RES::THREAD_ID | Return the ID of the current thread. |
| RES::TOTAL_MEMORY | The total amount of installed memory. |
| RES::TOTAL_SHARED_MEMORY | The total amount of shared memory in use (system wide). |
| RES::TOTAL_SWAP | The total amount of available swap space. |
Flags for RegisterFD()
| Name | Description |
|---|---|
| RFD::ALWAYS_CALL | Always call this FD's handler prior to the process going to sleep. |
| RFD::EXCEPT | Activate the callback if error conditions are pending. |
| RFD::READ | Activate the callback if there is data available to read. |
| RFD::RECALL | Set if the subscriber needs to manually check for incoming/outgoing data. This is supported as a one-off check, so the flag will be disabled automatically when the subscriber is called. |
| RFD::REMOVE | Stop monitoring this file descriptor. |
| RFD::SOCKET | Identifies the file descriptor as a socket (Linux systems only). |
| RFD::WRITE | Activate the callback if there is room to write to the FD's buffer. |
Path types for SetResourcePath()
| Name | Description |
|---|---|
| RP::MODULE_PATH | An alternative path leading to the system modules (normally system:modules/). Introduced for platforms such as Android, where modules are stored in asset folders. |
| RP::ROOT_PATH | Overrides the root path, which defaults to the location at which Parasol is installed. |
| RP::SYSTEM_PATH | The path of the system: volume, which otherwise defaults to [root]:system/. |
Flags for ResolvePath()
| Name | Description |
|---|---|
| RSF::APPROXIMATE | Ignores file extensions for the purpose of file name matching. |
| RSF::CASE_SENSITIVE | For use on host systems that use case-insensitive file systems such as Windows; this option checks that the discovered file is a case-sensitive match to the Path. |
| RSF::CHECK_VIRTUAL | If the volume referenced by Path is traced to another volume that is reserved by a virtual file system driver, ERR::VirtualVolume is returned. The volume is still resolved as far as possible and the resulting path will be returned by this function. |
| RSF::NO_DEEP_SCAN | Do not perform more than one iteration when resolving the source file path. |
| RSF::NO_FILE_CHECK | Do not test for the existence of the targeted file or folder during the resolution process. |
| RSF::PATH | Use the PATH environment variable to resolve the file name in the Path parameter. |
VlogF flags
| Name | Description |
|---|---|
| VLF::API | |
| VLF::BRANCH | |
| VLF::CRITICAL | |
| VLF::DETAIL | |
| VLF::ERROR | |
| VLF::FUNCTION | |
| VLF::INFO | |
| VLF::TRACE | |
| VLF::WARNING |
Options for SetVolume()
| Name | Description |
|---|---|
| VOLUME::HIDDEN | Hides the volume so that it will not show up when reading volumes from the root path :. |
| VOLUME::PRIORITY | If the volume already exists, the path will be inserted at the beginning of the path list so that it has priority over the others. |
| VOLUME::REPLACE | If the volume already exists, all paths that are attached to it will be replaced with the new path setting. |
| VOLUME::SYSTEM | Identifies the volume as being created by the system (this flag is not for client use). |
Structure for ActionList
| Field | Type | Description |
|---|---|---|
| Hash | ULONG | Hash of the action name. |
| Size | LONG | Byte-size of the structure for this action. |
| Name | CSTRING | Name of the action. |
| Args | const struct FunctionField * | List of fields that are passed to this action. |
Structure for ListChildren() function
| Field | Type | Description |
|---|---|---|
| ObjectID | OBJECTID | Object ID |
| ClassID | CLASSID | The class ID of the referenced object. |
Used by OpenDir() only
| Field | Type | Description |
|---|---|---|
| Info | struct FileInfo * | Pointer to a FileInfo structure |
Used to describe the public fields of a class.
| Field | Type | Description |
|---|---|---|
| Arg | MAXINT | An option to complement the field type. Can be a pointer or an integer value |
| GetValue | FUNCTION * | A virtual function that will retrieve the value for this field. |
| SetValue | APTR | A virtual function that will set the value for this field. |
| WriteValue | FUNCTION * | An internal function for writing to this field. |
| Name | CSTRING | The English name for the field, e.g. Width |
| FieldID | ULONG | Provides a fast way of finding fields, e.g. FID_Width |
| Offset | UWORD | Field offset within the object |
| Index | UWORD | Field array index |
| Flags | ULONG | Special flags that describe the field |
Metadata for describing a file.
| Field | Type | Description |
|---|---|---|
| Size | LARGE | The size of the file's content. |
| TimeStamp | LARGE | 64-bit time stamp - usable only for comparison (e.g. sorting). |
| Next | struct FileInfo * | Next structure in the list, or NULL. |
| Name | STRING | The name of the file. |
| Flags | RDF | Additional flags to describe the file. |
| Permissions | PERMIT | Standard permission flags. |
| UserID | LONG | User ID (Unix systems only). |
| GroupID | LONG | Group ID (Unix systems only). |
| Created | struct DateTime | The date/time of the file's creation. |
| Modified | struct DateTime | The date/time of the last file modification. |
| Field | Type | Description |
|---|---|---|
| Start | APTR | The starting address of the memory block (does not apply to shared blocks). |
| ObjectID | OBJECTID | The object that owns the memory block. |
| Size | ULONG | The size of the memory block. |
| Flags | MEM | The type of memory. |
| MemoryID | MEMORYID | The unique ID for this block. |
| AccessCount | WORD | Total number of active locks on this block. |
Message header.
| Field | Type | Description |
|---|---|---|
| Time | LARGE | A timestamp acquired from PreciseTime() when the message was first passed to SendMessage(). |
| UID | LONG | A unique identifier automatically created by SendMessage(). |
| Type | LONG | A message type identifier as defined by the client. |
| Size | LONG | The byte-size of the message data, or zero if no data is provided. |
Required in calls to WaitForObjects().
| Field | Type | Description |
|---|---|---|
| Object | OBJECTPTR | Reference to an object to monitor. |
Returned by the GetSystemState() function.
| Field | Type | Description |
|---|---|---|
| Platform | CSTRING | String-based field indicating the user's platform. Currently returns Native, Windows, OSX or Linux. |
| ConsoleFD | HOSTHANDLE | Internal |
| Stage | LONG | The current operating stage. -1 = Initialising, 0 indicates normal operating status; 1 means that the program is shutting down; 2 indicates a program restart; 3 is for mode switches. |
Class Info | |
|---|---|
| ID | ID_COMPRESSEDSTREAM |
| Category | Data |
| Include | modules/compressedstream.h |
| Version | 1 |