TCP/IP - RED Brick

This is the description of the TCP/IP protocol for the RED Brick. General information and technical specifications for the RED Brick are summarized in its hardware description.

API

A general description of the TCP/IP protocol structure can be found here.

Note

The API documentation for the RED Brick is currently incomplete.

The RED Brick API is meant to be used by the Brick Viewer to implement the offered functionality (getting status information, managing programs etc.). Normal users will not need to use this API, it may only be interesting for power users.

FIXME: explain sessions

The RED Brick API operates on reference counted objects (strings, lists, files, directories, processes and programs) that are identified by their 16bit object ID. Functions that allocate or return an object ID (e.g. allocate_string and get_next_directory_entry) increase the reference count of the returned object. If the object is no longer needed then release_object has to be called to decrease the reference count of the object again. In contrast to allocation and getter functions, the reference count for an object returned by a callback is not increased and release_object must not be called for such an object in response to a callback.

There are functions (e.g. get_file_info) that only return valid objects under certain conditions. This conditions are documented for the specific functions. For invalid objects release_object must not be called.

There are also function (e.g. set_program_stdio_redirection) that have conditionally unused object parameters. Under which conditions an object parameter is unused is documented for the specific functions. For unused object parameters 0 has to be passed as object ID.

The RED Brick API is more complex then the typical Brick API and requires more elaborate error reporting than the TCP/IP protocol can provide with its 2bit error code. Therefore, almost all functions of the RED Brick API return an 8bit error code. Possible error codes are:

  • Success = 0
  • UnknownError = 1
  • InvalidOperation = 2
  • OperationAborted = 3
  • InternalError = 4
  • UnknownSessionID = 5
  • NoFreeSessionID = 6
  • UnknownObjectID = 7
  • NoFreeObjectID = 8
  • ObjectIsLocked = 9
  • NoMoreData = 10
  • WrongListItemType = 11
  • ProgramIsPurged = 12
  • InvalidParameter = 128 (EINVAL)
  • NoFreeMemory = 129 (ENOMEM)
  • NoFreeSpace = 130 (ENOSPC)
  • AccessDenied = 131 (EACCES)
  • AlreadyExists = 132 (EEXIST)
  • DoesNotExist = 133 (ENOENT)
  • Interrupted = 134 (EINTR)
  • IsDirectory = 135 (EISDIR)
  • NotADirectory = 136 (ENOTDIR)
  • WouldBlock = 137 (EWOULDBLOCK)
  • Overflow = 138 (EOVERFLOW)
  • BadFileDescriptor = 139 (EBADF)
  • OutOfRange = 140 (ERANGE)
  • NameTooLong = 141 (ENAMETOOLONG)
  • InvalidSeek = 142 (ESPIPE)
  • NotSupported = 143 (ENOTSUP)
  • TooManyOpenFiles = 144 (EMFILE)

If a function returns an error code other than Success then its other return values (if any) are invalid and must not be used.

The error code InvalidOperation is returned if the requested operation cannot be performed because the current state of the object does not allow it. For example, trying to append an item to a full list object or trying to undefine an already undefined program.

The error code NotSupported is returned if the requested operation can never be performed. For example, trying to append a list object to itself, trying to get the name of a file object with type Pipe or trying to create a directory non-recursively with more than the last part of the directory name referring to non-existing directories.

String objects store UTF-8 encoded data.

Advanced Functions

BrickRED.create_session
Function ID:

1

Request:
  • lifetime -- uint32
Response:
  • error_code -- uint8
  • session_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.expire_session
Function ID:

2

Request:
  • session_id -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.expire_session_unchecked
Function ID:

3

Request:
  • session_id -- uint16
Response:

no response

BrickRED.keep_session_alive
Function ID:

4

Request:
  • session_id -- uint16
  • lifetime -- uint32
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.release_object
Function ID:

5

Request:
  • object_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8

Decreases the reference count of an object by one and returns the resulting error code. If the reference count reaches zero the object gets destroyed.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.release_object_unchecked
Function ID:

6

Request:
  • object_id -- uint16
  • session_id -- uint16
Response:

no response

BrickRED.allocate_string
Function ID:

7

Request:
  • length_to_reserve -- uint32
  • buffer -- char[58]
  • session_id -- uint16
Response:
  • error_code -- uint8
  • string_id -- uint16

Allocates a new string object, reserves length_to_reserve bytes memory for it and sets up to the first 60 bytes. Set length_to_reserve to the length of the string that should be stored in the string object.

Returns the object ID of the new string object and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.truncate_string
Function ID:

8

Request:
  • string_id -- uint16
  • length -- uint32
Response:
  • error_code -- uint8

Truncates a string object to length bytes and returns the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_string_length
Function ID:

9

Request:
  • string_id -- uint16
Response:
  • error_code -- uint8
  • length -- uint32

Returns the length of a string object in bytes and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.set_string_chunk
Function ID:

10

Request:
  • string_id -- uint16
  • offset -- uint32
  • buffer -- char[58]
Response:
  • error_code -- uint8

Sets a chunk of up to 58 bytes in a string object beginning at offset.

Returns the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_string_chunk
Function ID:

11

Request:
  • string_id -- uint16
  • offset -- uint32
Response:
  • error_code -- uint8
  • buffer -- char[63]

Returns a chunk up to 63 bytes from a string object beginning at offset and returns the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.allocate_list
Function ID:

12

Request:
  • length_to_reserve -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • list_id -- uint16

Allocates a new list object and reserves memory for length_to_reserve items. Set length_to_reserve to the number of items that should be stored in the list object.

Returns the object ID of the new list object and the resulting error code.

When a list object gets destroyed then the reference count of each object in the list object is decreased by one.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_list_length
Function ID:

13

Request:
  • list_id -- uint16
Response:
  • error_code -- uint8
  • length -- uint16

Returns the length of a list object in items and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_list_item
Function ID:

14

Request:
  • list_id -- uint16
  • index -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • item_object_id -- uint16
  • type -- uint8

Returns the object ID and type of the object stored at index in a list object and returns the resulting error code.

Possible object types are:

  • String = 0
  • List = 1
  • File = 2
  • Directory = 3
  • Process = 4
  • Program = 5

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: string, for type
  • 1: list, for type
  • 2: file, for type
  • 3: directory, for type
  • 4: process, for type
  • 5: program, for type
BrickRED.append_to_list
Function ID:

15

Request:
  • list_id -- uint16
  • item_object_id -- uint16
Response:
  • error_code -- uint8

Appends an object to a list object and increases the reference count of the appended object by one.

Returns the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.remove_from_list
Function ID:

16

Request:
  • list_id -- uint16
  • index -- uint16
Response:
  • error_code -- uint8

Removes the object stored at index from a list object and decreases the reference count of the removed object by one.

Returns the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.open_file
Function ID:

17

Request:
  • name_string_id -- uint16
  • flags -- uint32
  • permissions -- uint16
  • uid -- uint32
  • gid -- uint32
  • session_id -- uint16
Response:
  • error_code -- uint8
  • file_id -- uint16

Opens an existing file or creates a new file and allocates a new file object for it.

FIXME: name has to be absolute

The reference count of the name string object is increased by one. When the file object gets destroyed then the reference count of the name string object is decreased by one. Also the name string object is locked and cannot be modified while the file object holds a reference to it.

The flags parameter takes a ORed combination of the following possible file flags (in hexadecimal notation):

  • ReadOnly = 0x0001 (O_RDONLY)
  • WriteOnly = 0x0002 (O_WRONLY)
  • ReadWrite = 0x0004 (O_RDWR)
  • Append = 0x0008 (O_APPEND)
  • Create = 0x0010 (O_CREAT)
  • Exclusive = 0x0020 (O_EXCL)
  • NonBlocking = 0x0040 (O_NONBLOCK)
  • Truncate = 0x0080 (O_TRUNC)
  • Temporary = 0x0100
  • Replace = 0x0200

FIXME: explain Temporary and Replace flag

The permissions parameter takes a ORed combination of the following possible file permissions (in octal notation) that match the common UNIX permission bits:

  • UserRead = 00400
  • UserWrite = 00200
  • UserExecute = 00100
  • GroupRead = 00040
  • GroupWrite = 00020
  • GroupExecute = 00010
  • OthersRead = 00004
  • OthersWrite = 00002
  • OthersExecute = 00001

Returns the object ID of the new file object and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 1: read only, for flags
  • 2: write only, for flags
  • 4: read write, for flags
  • 8: append, for flags
  • 16: create, for flags
  • 32: exclusive, for flags
  • 64: non blocking, for flags
  • 128: truncate, for flags
  • 256: temporary, for flags
  • 512: replace, for flags
  • 448: user all, for permissions
  • 256: user read, for permissions
  • 128: user write, for permissions
  • 64: user execute, for permissions
  • 56: group all, for permissions
  • 32: group read, for permissions
  • 16: group write, for permissions
  • 8: group execute, for permissions
  • 7: others all, for permissions
  • 4: others read, for permissions
  • 2: others write, for permissions
  • 1: others execute, for permissions
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.create_pipe
Function ID:

18

Request:
  • flags -- uint32
  • length -- uint64
  • session_id -- uint16
Response:
  • error_code -- uint8
  • file_id -- uint16

Creates a new pipe and allocates a new file object for it.

The flags parameter takes a ORed combination of the following possible pipe flags (in hexadecimal notation):

  • NonBlockingRead = 0x0001
  • NonBlockingWrite = 0x0002

The length of the pipe buffer can be specified with the length parameter in bytes. If length is set to zero, then the default pipe buffer length is used.

Returns the object ID of the new file object and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 1: non blocking read, for flags
  • 2: non blocking write, for flags
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_file_info
Function ID:

19

Request:
  • file_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • type -- uint8
  • name_string_id -- uint16
  • flags -- uint32
  • permissions -- uint16
  • uid -- uint32
  • gid -- uint32
  • length -- uint64
  • access_timestamp -- uint64
  • modification_timestamp -- uint64
  • status_change_timestamp -- uint64

Returns various information about a file and the resulting error code.

Possible file types are:

  • Unknown = 0
  • Regular = 1
  • Directory = 2
  • Character = 3
  • Block = 4
  • FIFO = 5
  • Symlink = 6
  • Socket = 7
  • Pipe = 8

If the file type is Pipe then the returned name string object is invalid, because a pipe has no name. Otherwise the returned name string object was used to open or create the file object, as passed to open_file.

The returned flags were used to open or create the file object, as passed to open_file or create_pipe. See the respective function for a list of possible file and pipe flags.

FIXME: everything except flags and length is invalid if file type is Pipe

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: unknown, for type
  • 1: regular, for type
  • 2: directory, for type
  • 3: character, for type
  • 4: block, for type
  • 5: fifo, for type
  • 6: symlink, for type
  • 7: socket, for type
  • 8: pipe, for type
  • 448: user all, for permissions
  • 256: user read, for permissions
  • 128: user write, for permissions
  • 64: user execute, for permissions
  • 56: group all, for permissions
  • 32: group read, for permissions
  • 16: group write, for permissions
  • 8: group execute, for permissions
  • 7: others all, for permissions
  • 4: others read, for permissions
  • 2: others write, for permissions
  • 1: others execute, for permissions
BrickRED.read_file
Function ID:

20

Request:
  • file_id -- uint16
  • length_to_read -- uint8
Response:
  • error_code -- uint8
  • buffer -- uint8[62]
  • length_read -- uint8

Reads up to 62 bytes from a file object.

Returns the bytes read, the actual number of bytes read and the resulting error code.

If there is not data to be read, either because the file position reached end-of-file or because there is not data in the pipe, then zero bytes are returned.

If the file object was created by open_file without the NonBlocking flag or by create_pipe without the NonBlockingRead flag then the error code NotSupported is returned.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.read_file_async
Function ID:

21

Request:
  • file_id -- uint16
  • length_to_read -- uint64
Response:

no response

Reads up to 263 - 1 bytes from a file object asynchronously.

Reports the bytes read (in 60 byte chunks), the actual number of bytes read and the resulting error code via the CALLBACK_ASYNC_FILE_READ callback.

If there is not data to be read, either because the file position reached end-of-file or because there is not data in the pipe, then zero bytes are reported.

If the file object was created by open_file without the NonBlocking flag or by create_pipe without the NonBlockingRead flag then the error code NotSupported is reported via the CALLBACK_ASYNC_FILE_READ callback.

BrickRED.abort_async_file_read
Function ID:

22

Request:
  • file_id -- uint16
Response:
  • error_code -- uint8

Aborts a read_file_async operation in progress.

Returns the resulting error code.

On success the CALLBACK_ASYNC_FILE_READ callback will report OperationAborted.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.write_file
Function ID:

23

Request:
  • file_id -- uint16
  • buffer -- uint8[61]
  • length_to_write -- uint8
Response:
  • error_code -- uint8
  • length_written -- uint8

Writes up to 61 bytes to a file object.

Returns the actual number of bytes written and the resulting error code.

If the file object was created by open_file without the NonBlocking flag or by create_pipe without the NonBlockingWrite flag then the error code NotSupported is returned.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.write_file_unchecked
Function ID:

24

Request:
  • file_id -- uint16
  • buffer -- uint8[61]
  • length_to_write -- uint8
Response:

no response

Writes up to 61 bytes to a file object.

Does neither report the actual number of bytes written nor the resulting error code.

If the file object was created by open_file without the NonBlocking flag or by create_pipe without the NonBlockingWrite flag then the write operation will fail silently.

BrickRED.write_file_async
Function ID:

25

Request:
  • file_id -- uint16
  • buffer -- uint8[61]
  • length_to_write -- uint8
Response:

no response

Writes up to 61 bytes to a file object.

Reports the actual number of bytes written and the resulting error code via the CALLBACK_ASYNC_FILE_WRITE callback.

If the file object was created by open_file without the NonBlocking flag or by create_pipe without the NonBlockingWrite flag then the error code NotSupported is reported via the CALLBACK_ASYNC_FILE_WRITE callback.

BrickRED.set_file_position
Function ID:

26

Request:
  • file_id -- uint16
  • offset -- int64
  • origin -- uint8
Response:
  • error_code -- uint8
  • position -- uint64

Set the current seek position of a file object in bytes relative to origin.

Possible file origins are:

  • Beginning = 0
  • Current = 1
  • End = 2

Returns the resulting absolute seek position and error code.

If the file object was created by create_pipe then it has no seek position and the error code InvalidSeek is returned.

The following meanings are defined for the parameters of this function:

  • 0: beginning, for origin
  • 1: current, for origin
  • 2: end, for origin
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_file_position
Function ID:

27

Request:
  • file_id -- uint16
Response:
  • error_code -- uint8
  • position -- uint64

Returns the current seek position of a file object in bytes and returns the resulting error code.

If the file object was created by create_pipe then it has no seek position and the error code InvalidSeek is returned.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.set_file_events
Function ID:

28

Request:
  • file_id -- uint16
  • events -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 1: readable, for events
  • 2: writable, for events
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_file_events
Function ID:

29

Request:
  • file_id -- uint16
Response:
  • error_code -- uint8
  • events -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 1: readable, for events
  • 2: writable, for events
BrickRED.open_directory
Function ID:

33

Request:
  • name_string_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • directory_id -- uint16

Opens an existing directory and allocates a new directory object for it.

FIXME: name has to be absolute

The reference count of the name string object is increased by one. When the directory object is destroyed then the reference count of the name string object is decreased by one. Also the name string object is locked and cannot be modified while the directory object holds a reference to it.

Returns the object ID of the new directory object and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_directory_name
Function ID:

34

Request:
  • directory_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • name_string_id -- uint16

Returns the name of a directory object, as passed to open_directory, and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_next_directory_entry
Function ID:

35

Request:
  • directory_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • name_string_id -- uint16
  • type -- uint8

Returns the next entry in a directory object and the resulting error code.

If there is not next entry then error code NoMoreData is returned. To rewind a directory object call rewind_directory.

Possible directory entry types are:

  • Unknown = 0
  • Regular = 1
  • Directory = 2
  • Character = 3
  • Block = 4
  • FIFO = 5
  • Symlink = 6
  • Socket = 7

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: unknown, for type
  • 1: regular, for type
  • 2: directory, for type
  • 3: character, for type
  • 4: block, for type
  • 5: fifo, for type
  • 6: symlink, for type
  • 7: socket, for type
BrickRED.rewind_directory
Function ID:

36

Request:
  • directory_id -- uint16
Response:
  • error_code -- uint8

Rewinds a directory object and returns the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.create_directory
Function ID:

37

Request:
  • name_string_id -- uint16
  • flags -- uint32
  • permissions -- uint16
  • uid -- uint32
  • gid -- uint32
Response:
  • error_code -- uint8

FIXME: name has to be absolute

The following meanings are defined for the parameters of this function:

  • 1: recursive, for flags
  • 2: exclusive, for flags
  • 448: user all, for permissions
  • 256: user read, for permissions
  • 128: user write, for permissions
  • 64: user execute, for permissions
  • 56: group all, for permissions
  • 32: group read, for permissions
  • 16: group write, for permissions
  • 8: group execute, for permissions
  • 7: others all, for permissions
  • 4: others read, for permissions
  • 2: others write, for permissions
  • 1: others execute, for permissions
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_processes
Function ID:

38

Request:
  • session_id -- uint16
Response:
  • error_code -- uint8
  • processes_list_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.spawn_process
Function ID:

39

Request:
  • executable_string_id -- uint16
  • arguments_list_id -- uint16
  • environment_list_id -- uint16
  • working_directory_string_id -- uint16
  • uid -- uint32
  • gid -- uint32
  • stdin_file_id -- uint16
  • stdout_file_id -- uint16
  • stderr_file_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • process_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.kill_process
Function ID:

40

Request:
  • process_id -- uint16
  • signal -- uint8
Response:
  • error_code -- uint8

Sends a UNIX signal to a process object and returns the resulting error code.

Possible UNIX signals are:

  • Interrupt = 2
  • Quit = 3
  • Abort = 6
  • Kill = 9
  • User1 = 10
  • User2 = 12
  • Terminate = 15
  • Continue = 18
  • Stop = 19

The following meanings are defined for the parameters of this function:

  • 2: interrupt, for signal
  • 3: quit, for signal
  • 6: abort, for signal
  • 9: kill, for signal
  • 10: user1, for signal
  • 12: user2, for signal
  • 15: terminate, for signal
  • 18: continue, for signal
  • 19: stop, for signal
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_process_command
Function ID:

41

Request:
  • process_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • executable_string_id -- uint16
  • arguments_list_id -- uint16
  • environment_list_id -- uint16
  • working_directory_string_id -- uint16

Returns the executable, arguments, environment and working directory used to spawn a process object, as passed to spawn_process, and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_process_identity
Function ID:

42

Request:
  • process_id -- uint16
Response:
  • error_code -- uint8
  • pid -- uint32
  • uid -- uint32
  • gid -- uint32

Returns the process ID and the user and group ID used to spawn a process object, as passed to spawn_process, and the resulting error code.

The process ID is only valid if the state is Running or Stopped, see get_process_state.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_process_stdio
Function ID:

43

Request:
  • process_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • stdin_file_id -- uint16
  • stdout_file_id -- uint16
  • stderr_file_id -- uint16

Returns the stdin, stdout and stderr files used to spawn a process object, as passed to spawn_process, and the resulting error code.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_process_state
Function ID:

44

Request:
  • process_id -- uint16
Response:
  • error_code -- uint8
  • state -- uint8
  • timestamp -- uint64
  • exit_code -- uint8

Returns the current state, timestamp and exit code of a process object, and the resulting error code.

Possible process states are:

  • Unknown = 0
  • Running = 1
  • Error = 2
  • Exited = 3
  • Killed = 4
  • Stopped = 5

The timestamp represents the UNIX time since when the process is in its current state.

The exit code is only valid if the state is Error, Exited, Killed or Stopped and has different meanings depending on the state:

  • Error: error code for error occurred while spawning the process (see below)
  • Exited: exit status of the process
  • Killed: UNIX signal number used to kill the process
  • Stopped: UNIX signal number used to stop the process

Possible exit/error codes in Error state are:

  • InternalError = 125
  • CannotExecute = 126
  • DoesNotExist = 127

The CannotExecute error can be caused by the executable being opened for writing.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: unknown, for state
  • 1: running, for state
  • 2: error, for state
  • 3: exited, for state
  • 4: killed, for state
  • 5: stopped, for state
BrickRED.get_programs
Function ID:

46

Request:
  • session_id -- uint16
Response:
  • error_code -- uint8
  • programs_list_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.define_program
Function ID:

47

Request:
  • identifier_string_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • program_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.purge_program
Function ID:

48

Request:
  • program_id -- uint16
  • cookie -- uint32
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_program_identifier
Function ID:

49

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • identifier_string_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_program_root_directory
Function ID:

50

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • root_directory_string_id -- uint16

FIXME: root directory is absolute: <home>/programs/<identifier>

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.set_program_command
Function ID:

51

Request:
  • program_id -- uint16
  • executable_string_id -- uint16
  • arguments_list_id -- uint16
  • environment_list_id -- uint16
  • working_directory_string_id -- uint16
Response:
  • error_code -- uint8

FIXME: working directory is relative to <home>/programs/<identifier>/bin

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_program_command
Function ID:

52

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • executable_string_id -- uint16
  • arguments_list_id -- uint16
  • environment_list_id -- uint16
  • working_directory_string_id -- uint16

FIXME: working directory is relative to <home>/programs/<identifier>/bin

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.set_program_stdio_redirection
Function ID:

53

Request:
  • program_id -- uint16
  • stdin_redirection -- uint8
  • stdin_file_name_string_id -- uint16
  • stdout_redirection -- uint8
  • stdout_file_name_string_id -- uint16
  • stderr_redirection -- uint8
  • stderr_file_name_string_id -- uint16
Response:
  • error_code -- uint8

FIXME: stdio file names are relative to <home>/programs/<identifier>/bin

The following meanings are defined for the parameters of this function:

  • 0: dev null, for stdin_redirection, stdout_redirection and stderr_redirection
  • 1: pipe, for stdin_redirection, stdout_redirection and stderr_redirection
  • 2: file, for stdin_redirection, stdout_redirection and stderr_redirection
  • 3: individual log, for stdin_redirection, stdout_redirection and stderr_redirection
  • 4: continuous log, for stdin_redirection, stdout_redirection and stderr_redirection
  • 5: stdout, for stdin_redirection, stdout_redirection and stderr_redirection
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_program_stdio_redirection
Function ID:

54

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • stdin_redirection -- uint8
  • stdin_file_name_string_id -- uint16
  • stdout_redirection -- uint8
  • stdout_file_name_string_id -- uint16
  • stderr_redirection -- uint8
  • stderr_file_name_string_id -- uint16

FIXME: stdio file names are relative to <home>/programs/<identifier>/bin

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: dev null, for stdin_redirection, stdout_redirection and stderr_redirection
  • 1: pipe, for stdin_redirection, stdout_redirection and stderr_redirection
  • 2: file, for stdin_redirection, stdout_redirection and stderr_redirection
  • 3: individual log, for stdin_redirection, stdout_redirection and stderr_redirection
  • 4: continuous log, for stdin_redirection, stdout_redirection and stderr_redirection
  • 5: stdout, for stdin_redirection, stdout_redirection and stderr_redirection
BrickRED.set_program_schedule
Function ID:

55

Request:
  • program_id -- uint16
  • start_mode -- uint8
  • continue_after_error -- bool
  • start_interval -- uint32
  • start_fields_string_id -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: never, for start_mode
  • 1: always, for start_mode
  • 2: interval, for start_mode
  • 3: cron, for start_mode
  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_program_schedule
Function ID:

56

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • start_mode -- uint8
  • continue_after_error -- bool
  • start_interval -- uint32
  • start_fields_string_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: never, for start_mode
  • 1: always, for start_mode
  • 2: interval, for start_mode
  • 3: cron, for start_mode
BrickRED.get_program_scheduler_state
Function ID:

57

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • state -- uint8
  • timestamp -- uint64
  • message_string_id -- uint16

FIXME: message is currently valid in error-occurred state only

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
  • 0: stopped, for state
  • 1: running, for state
BrickRED.continue_program_schedule
Function ID:

58

Request:
  • program_id -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.start_program
Function ID:

59

Request:
  • program_id -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_last_spawned_program_process
Function ID:

60

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • process_id -- uint16
  • timestamp -- uint64

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_custom_program_option_names
Function ID:

61

Request:
  • program_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • names_list_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.set_custom_program_option_value
Function ID:

62

Request:
  • program_id -- uint16
  • name_string_id -- uint16
  • value_string_id -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_custom_program_option_value
Function ID:

63

Request:
  • program_id -- uint16
  • name_string_id -- uint16
  • session_id -- uint16
Response:
  • error_code -- uint8
  • value_string_id -- uint16

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.remove_custom_program_option
Function ID:

64

Request:
  • program_id -- uint16
  • name_string_id -- uint16
Response:
  • error_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.get_identity
Function ID:

255

Request:

empty payload

Response:
  • uid -- char[8]
  • connected_uid -- char[8]
  • position -- char
  • hardware_version -- uint8[3]
  • firmware_version -- uint8[3]
  • device_identifier -- uint16

Returns the UID, the UID where the Brick is connected to, the position, the hardware and firmware version as well as the device identifier.

The position can be '0'-'8' (stack position).

The device identifier numbers can be found here

Callbacks

BrickRED.CALLBACK_ASYNC_FILE_READ
Function ID:

30

Response:
  • file_id -- uint16
  • error_code -- uint8
  • buffer -- uint8[60]
  • length_read -- uint8

This callback reports the result of a call to the read_file_async function.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.CALLBACK_ASYNC_FILE_WRITE
Function ID:

31

Response:
  • file_id -- uint16
  • error_code -- uint8
  • length_written -- uint8

This callback reports the result of a call to the write_file_async function.

The following meanings are defined for the parameters of this function:

  • 0: success, for error_code
  • 1: unknown error, for error_code
  • 2: invalid operation, for error_code
  • 3: operation aborted, for error_code
  • 4: internal error, for error_code
  • 5: unknown session id, for error_code
  • 6: no free session id, for error_code
  • 7: unknown object id, for error_code
  • 8: no free object id, for error_code
  • 9: object is locked, for error_code
  • 10: no more data, for error_code
  • 11: wrong list item type, for error_code
  • 12: program is purged, for error_code
  • 128: invalid parameter, for error_code
  • 129: no free memory, for error_code
  • 130: no free space, for error_code
  • 121: access denied, for error_code
  • 132: already exists, for error_code
  • 133: does not exist, for error_code
  • 134: interrupted, for error_code
  • 135: is directory, for error_code
  • 136: not a directory, for error_code
  • 137: would block, for error_code
  • 138: overflow, for error_code
  • 139: bad file descriptor, for error_code
  • 140: out of range, for error_code
  • 141: name too long, for error_code
  • 142: invalid seek, for error_code
  • 143: not supported, for error_code
  • 144: too many open files, for error_code
BrickRED.CALLBACK_FILE_EVENTS_OCCURRED
Function ID:

32

Response:
  • file_id -- uint16
  • events -- uint16

The following meanings are defined for the parameters of this function:

  • 1: readable, for events
  • 2: writable, for events
BrickRED.CALLBACK_PROCESS_STATE_CHANGED
Function ID:

45

Response:
  • process_id -- uint16
  • state -- uint8
  • timestamp -- uint64
  • exit_code -- uint8

The following meanings are defined for the parameters of this function:

  • 0: unknown, for state
  • 1: running, for state
  • 2: error, for state
  • 3: exited, for state
  • 4: killed, for state
  • 5: stopped, for state
BrickRED.CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED
Function ID:

65

Response:
  • program_id -- uint16
BrickRED.CALLBACK_PROGRAM_PROCESS_SPAWNED
Function ID:

66

Response:
  • program_id -- uint16