Scripting Functions
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.