The public system.hostagent.file namespace is available in Gateway, Vision, and Designer scopes. Every operation is still subject to host connection, mapping scope, and access mode.
Examples below use placeholders only:
host_id = "<host-identifier>"
approved_file = "<approved-directory>/example.dat"
system.hostagent.file.readFile()
Purpose
Read an authorized file.
Parameters
-
hostUuid: Identifier of the trusted host. -
filePath: File path covered by an active mapping. -
useCompression: Optional boolean; defaults to enabled.
Returns
The file content as a byte array.
Example
content = system.hostagent.file.readFile(host_id, approved_file)
system.hostagent.file.listFiles()
Purpose
List immediate regular files in an authorized directory. The result is nonrecursive, sorted, and excludes symbolic links.
Parameters
-
hostUuid: Identifier of the trusted host. -
path: Directory path covered by an active mapping.
Returns
A sorted collection of absolute file paths.
Example
files = system.hostagent.file.listFiles(host_id, "<approved-directory>")
system.hostagent.file.writeFile()
Purpose
Replace the content of an existing authorized file.
Parameters
-
hostUuid: Identifier of the trusted host. -
filePath: Destination covered by an active read-write mapping. -
content: Binary content to write. -
useCompression: Optional boolean; defaults to enabled.
Returns
Example
system.hostagent.file.writeFile(host_id, approved_file, bytearray([1, 2, 3]))
system.hostagent.file.createFile()
Purpose
Create a file at an authorized destination. The operation does not replace an existing destination.
Parameters
-
hostUuid: Identifier of the trusted host. -
filePath: New path covered by an active read-write mapping. -
content: Initial binary content. -
useCompression: Optional boolean; defaults to enabled.
Returns
Example
system.hostagent.file.createFile(
host_id,
"<approved-directory>/new-file.dat",
bytearray([1, 2, 3])
)
system.hostagent.file.moveFile()
Purpose
Move an authorized file. Both source and destination are checked independently, and the destination is not replaced if it already exists.
Parameters
-
hostUuid: Identifier of the trusted host. -
sourcePath: Authorized source path. -
destinationPath: Authorized destination path.
Returns
Example
system.hostagent.file.moveFile(
host_id,
"<approved-directory>/incoming.dat",
"<approved-directory>/processed.dat"
)
system.hostagent.file.deleteFile()
Purpose
Permanently delete an authorized file.
Parameters
-
hostUuid: Identifier of the trusted host. -
filePath: Path covered by an active read-write mapping.
Returns
Example
system.hostagent.file.deleteFile(
host_id,
"<approved-directory>/obsolete.dat"
)
Deletion has no module-provided undo or recycle-bin behavior.