Visual Basic .NET - RED Brick – Tinkerforge

- Getting Started
  - Primer
  - Tutorials
  - FAQ
- Hardware
  - Bricks
  - Bricklets
  - Master Extensions
  - Power Supplies
  - Accessories
  - Timeline
- Software
  - Brick Daemon (brickd)
  - Brick Viewer (brickv)
  - API Bindings
    - C/C++
    - C/C++ (iOS)
    - C#
    - C# (Windows Phone)
    - Delphi/Lazarus
    - Java
    - Java (Android)
    - JavaScript
    - LabVIEW
    - Mathematica
    - MATLAB/Octave
    - Perl
    - PHP
    - Python
    - Ruby
    - Shell
    - Visual Basic .NET
      - Requirements
      - Installation
      - Testing an Example
      - API Reference and Examples
        - IP Connection
        - Bricks
          - DC Brick
          - IMU Brick
          - Master Brick
          - RED Brick
            - Examples
            - API
              - Advanced Functions
              - Callbacks
              - Constants
          - Servo Brick
          - Stepper Brick
        - Bricklets
  - Firmwares and Plugins
  - Device Identifier
  - Source Code and Bug Tracking
  - Programming Interface
- Starter Kits
  - Weather Station
  - Hardware Hacking
  - Server Room Monitoring
  - Blinkenlights
  - Internet of Things
  - Camera Slider
- Embedded Boards
  - Raspberry Pi
- Specifications
  - Technical Data
  - TCP/IP Protocol
  - Modbus Protocol
  - Wireshark Dissector

# Visual Basic .NET - RED Brick

This is the description of the Visual Basic .NET API bindings for the RED Brick. General information and technical specifications for the RED Brick are summarized in its hardware description.

An installation guide for the Visual Basic .NET API bindings is part of their general description.

## Examples

The example code below is Public Domain (CC0 1.0).

## API

Since Visual Basic .NET does not support multiple return values directly, we use the `ByRef` keyword to return multiple values from a function.

All functions and procedures listed below are thread-safe.

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. `AllocateString()` and `GetNextDirectoryEntry()`) increase the reference count of the returned object. If the object is no longer needed then `ReleaseObject()` 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 `ReleaseObject()` must not be called for such an object in response to a callback.

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

There are also function (e.g. `SetProgramStdioRedirection()`) 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

Sub `BrickRED.``CreateSession`(ByVal lifetime As Long, ByRef errorCode As Byte, ByRef sessionId As Integer)

Function `BrickRED.``ExpireSession`(ByVal sessionId As Integer) As Byte

Sub `BrickRED.``ExpireSessionUnchecked`(ByVal sessionId As Integer)

Function `BrickRED.``KeepSessionAlive`(ByVal sessionId As Integer, ByVal lifetime As Long) As Byte

Function `BrickRED.``ReleaseObject`(ByVal objectId As Integer, ByVal sessionId As Integer) As Byte

  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.

Sub `BrickRED.``ReleaseObjectUnchecked`(ByVal objectId As Integer, ByVal sessionId As Integer)

Sub `BrickRED.``AllocateString`(ByVal lengthToReserve As Long, ByVal buffer As String, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef stringId As Integer)

  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.

Function `BrickRED.``TruncateString`(ByVal stringId As Integer, ByVal length As Long) As Byte

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

Sub `BrickRED.``GetStringLength`(ByVal stringId As Integer, ByRef errorCode As Byte, ByRef length As Long)

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

Function `BrickRED.``SetStringChunk`(ByVal stringId As Integer, ByVal offset As Long, ByVal buffer As String) As Byte

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

  Returns the resulting error code.

Sub `BrickRED.``GetStringChunk`(ByVal stringId As Integer, ByVal offset As Long, ByRef errorCode As Byte, ByRef buffer As String)

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

Sub `BrickRED.``AllocateList`(ByVal lengthToReserve As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef listId As Integer)

  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.

Sub `BrickRED.``GetListLength`(ByVal listId As Integer, ByRef errorCode As Byte, ByRef length As Integer)

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

Sub `BrickRED.``GetListItem`(ByVal listId As Integer, ByVal index As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef itemObjectId As Integer, ByRef type As Byte)

  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 constants are available for this function:

  - BrickRED.OBJECT_TYPE_STRING = 0
  - BrickRED.OBJECT_TYPE_LIST = 1
  - BrickRED.OBJECT_TYPE_FILE = 2
  - BrickRED.OBJECT_TYPE_DIRECTORY = 3
  - BrickRED.OBJECT_TYPE_PROCESS = 4
  - BrickRED.OBJECT_TYPE_PROGRAM = 5

Function `BrickRED.``AppendToList`(ByVal listId As Integer, ByVal itemObjectId As Integer) As Byte

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

  Returns the resulting error code.

Function `BrickRED.``RemoveFromList`(ByVal listId As Integer, ByVal index As Integer) As Byte

  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.

Sub `BrickRED.``OpenFile`(ByVal nameStringId As Integer, ByVal flags As Long, ByVal permissions As Integer, ByVal uid As Long, ByVal gid As Long, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef fileId As Integer)

  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 constants are available for this function:

  - BrickRED.FILE_FLAG_READ_ONLY = 1
  - BrickRED.FILE_FLAG_WRITE_ONLY = 2
  - BrickRED.FILE_FLAG_READ_WRITE = 4
  - BrickRED.FILE_FLAG_APPEND = 8
  - BrickRED.FILE_FLAG_CREATE = 16
  - BrickRED.FILE_FLAG_EXCLUSIVE = 32
  - BrickRED.FILE_FLAG_NON_BLOCKING = 64
  - BrickRED.FILE_FLAG_TRUNCATE = 128
  - BrickRED.FILE_FLAG_TEMPORARY = 256
  - BrickRED.FILE_FLAG_REPLACE = 512
  - BrickRED.FILE_PERMISSION_USER_ALL = 448
  - BrickRED.FILE_PERMISSION_USER_READ = 256
  - BrickRED.FILE_PERMISSION_USER_WRITE = 128
  - BrickRED.FILE_PERMISSION_USER_EXECUTE = 64
  - BrickRED.FILE_PERMISSION_GROUP_ALL = 56
  - BrickRED.FILE_PERMISSION_GROUP_READ = 32
  - BrickRED.FILE_PERMISSION_GROUP_WRITE = 16
  - BrickRED.FILE_PERMISSION_GROUP_EXECUTE = 8
  - BrickRED.FILE_PERMISSION_OTHERS_ALL = 7
  - BrickRED.FILE_PERMISSION_OTHERS_READ = 4
  - BrickRED.FILE_PERMISSION_OTHERS_WRITE = 2
  - BrickRED.FILE_PERMISSION_OTHERS_EXECUTE = 1

Sub `BrickRED.``CreatePipe`(ByVal flags As Long, ByVal length As Long, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef fileId As Integer)

  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 constants are available for this function:

  - BrickRED.PIPE_FLAG_NON_BLOCKING_READ = 1
  - BrickRED.PIPE_FLAG_NON_BLOCKING_WRITE = 2

Sub `BrickRED.``GetFileInfo`(ByVal fileId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef type As Byte, ByRef nameStringId As Integer, ByRef flags As Long, ByRef permissions As Integer, ByRef uid As Long, ByRef gid As Long, ByRef length As Long, ByRef accessTimestamp As Long, ByRef modificationTimestamp As Long, ByRef statusChangeTimestamp As Long)

  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 `OpenFile()`.

  The returned flags were used to open or create the file object, as passed to `OpenFile()` or `CreatePipe()`. 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 constants are available for this function:

  - BrickRED.FILE_TYPE_UNKNOWN = 0
  - BrickRED.FILE_TYPE_REGULAR = 1
  - BrickRED.FILE_TYPE_DIRECTORY = 2
  - BrickRED.FILE_TYPE_CHARACTER = 3
  - BrickRED.FILE_TYPE_BLOCK = 4
  - BrickRED.FILE_TYPE_FIFO = 5
  - BrickRED.FILE_TYPE_SYMLINK = 6
  - BrickRED.FILE_TYPE_SOCKET = 7
  - BrickRED.FILE_TYPE_PIPE = 8
  - BrickRED.FILE_PERMISSION_USER_ALL = 448
  - BrickRED.FILE_PERMISSION_USER_READ = 256
  - BrickRED.FILE_PERMISSION_USER_WRITE = 128
  - BrickRED.FILE_PERMISSION_USER_EXECUTE = 64
  - BrickRED.FILE_PERMISSION_GROUP_ALL = 56
  - BrickRED.FILE_PERMISSION_GROUP_READ = 32
  - BrickRED.FILE_PERMISSION_GROUP_WRITE = 16
  - BrickRED.FILE_PERMISSION_GROUP_EXECUTE = 8
  - BrickRED.FILE_PERMISSION_OTHERS_ALL = 7
  - BrickRED.FILE_PERMISSION_OTHERS_READ = 4
  - BrickRED.FILE_PERMISSION_OTHERS_WRITE = 2
  - BrickRED.FILE_PERMISSION_OTHERS_EXECUTE = 1

Sub `BrickRED.``ReadFile`(ByVal fileId As Integer, ByVal lengthToRead As Byte, ByRef errorCode As Byte, ByRef buffer() As Byte, ByRef lengthRead As Byte)

  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 `OpenFile()` without the NonBlocking flag or by `CreatePipe()` without the NonBlockingRead flag then the error code NotSupported is returned.

Sub `BrickRED.``ReadFileAsync`(ByVal fileId As Integer, ByVal lengthToRead As Long)

  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 `AsyncFileRead` 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 `OpenFile()` without the NonBlocking flag or by `CreatePipe()` without the NonBlockingRead flag then the error code NotSupported is reported via the `AsyncFileRead` callback.

Function `BrickRED.``AbortAsyncFileRead`(ByVal fileId As Integer) As Byte

  Aborts a `ReadFileAsync()` operation in progress.

  Returns the resulting error code.

  On success the `AsyncFileRead` callback will report OperationAborted.

Sub `BrickRED.``WriteFile`(ByVal fileId As Integer, ByVal buffer() As Byte, ByVal lengthToWrite As Byte, ByRef errorCode As Byte, ByRef lengthWritten As Byte)

  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 `OpenFile()` without the NonBlocking flag or by `CreatePipe()` without the NonBlockingWrite flag then the error code NotSupported is returned.

Sub `BrickRED.``WriteFileUnchecked`(ByVal fileId As Integer, ByVal buffer() As Byte, ByVal lengthToWrite As Byte)

  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 `OpenFile()` without the NonBlocking flag or by `CreatePipe()` without the NonBlockingWrite flag then the write operation will fail silently.

Sub `BrickRED.``WriteFileAsync`(ByVal fileId As Integer, ByVal buffer() As Byte, ByVal lengthToWrite As Byte)

  Writes up to 61 bytes to a file object.

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

  If the file object was created by `OpenFile()` without the NonBlocking flag or by `CreatePipe()` without the NonBlockingWrite flag then the error code NotSupported is reported via the `AsyncFileWrite` callback.

Sub `BrickRED.``SetFilePosition`(ByVal fileId As Integer, ByVal offset As Long, ByVal origin As Byte, ByRef errorCode As Byte, ByRef position As Long)

  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 `CreatePipe()` then it has no seek position and the error code InvalidSeek is returned.

  The following constants are available for this function:

  - BrickRED.FILE_ORIGIN_BEGINNING = 0
  - BrickRED.FILE_ORIGIN_CURRENT = 1
  - BrickRED.FILE_ORIGIN_END = 2

Sub `BrickRED.``GetFilePosition`(ByVal fileId As Integer, ByRef errorCode As Byte, ByRef position As Long)

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

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

Function `BrickRED.``SetFileEvents`(ByVal fileId As Integer, ByVal events As Integer) As Byte

  The following constants are available for this function:

  - BrickRED.FILE_EVENT_READABLE = 1
  - BrickRED.FILE_EVENT_WRITABLE = 2

Sub `BrickRED.``GetFileEvents`(ByVal fileId As Integer, ByRef errorCode As Byte, ByRef events As Integer)

  The following constants are available for this function:

  - BrickRED.FILE_EVENT_READABLE = 1
  - BrickRED.FILE_EVENT_WRITABLE = 2

Sub `BrickRED.``OpenDirectory`(ByVal nameStringId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef directoryId As Integer)

  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.

Sub `BrickRED.``GetDirectoryName`(ByVal directoryId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef nameStringId As Integer)

  Returns the name of a directory object, as passed to `OpenDirectory()`, and the resulting error code.

Sub `BrickRED.``GetNextDirectoryEntry`(ByVal directoryId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef nameStringId As Integer, ByRef type As Byte)

  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 `RewindDirectory()`.

  Possible directory entry types are:

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

  The following constants are available for this function:

  - BrickRED.DIRECTORY_ENTRY_TYPE_UNKNOWN = 0
  - BrickRED.DIRECTORY_ENTRY_TYPE_REGULAR = 1
  - BrickRED.DIRECTORY_ENTRY_TYPE_DIRECTORY = 2
  - BrickRED.DIRECTORY_ENTRY_TYPE_CHARACTER = 3
  - BrickRED.DIRECTORY_ENTRY_TYPE_BLOCK = 4
  - BrickRED.DIRECTORY_ENTRY_TYPE_FIFO = 5
  - BrickRED.DIRECTORY_ENTRY_TYPE_SYMLINK = 6
  - BrickRED.DIRECTORY_ENTRY_TYPE_SOCKET = 7

Function `BrickRED.``RewindDirectory`(ByVal directoryId As Integer) As Byte

  Rewinds a directory object and returns the resulting error code.

Function `BrickRED.``CreateDirectory`(ByVal nameStringId As Integer, ByVal flags As Long, ByVal permissions As Integer, ByVal uid As Long, ByVal gid As Long) As Byte

  FIXME: name has to be absolute

  The following constants are available for this function:

  - BrickRED.DIRECTORY_FLAG_RECURSIVE = 1
  - BrickRED.DIRECTORY_FLAG_EXCLUSIVE = 2
  - BrickRED.FILE_PERMISSION_USER_ALL = 448
  - BrickRED.FILE_PERMISSION_USER_READ = 256
  - BrickRED.FILE_PERMISSION_USER_WRITE = 128
  - BrickRED.FILE_PERMISSION_USER_EXECUTE = 64
  - BrickRED.FILE_PERMISSION_GROUP_ALL = 56
  - BrickRED.FILE_PERMISSION_GROUP_READ = 32
  - BrickRED.FILE_PERMISSION_GROUP_WRITE = 16
  - BrickRED.FILE_PERMISSION_GROUP_EXECUTE = 8
  - BrickRED.FILE_PERMISSION_OTHERS_ALL = 7
  - BrickRED.FILE_PERMISSION_OTHERS_READ = 4
  - BrickRED.FILE_PERMISSION_OTHERS_WRITE = 2
  - BrickRED.FILE_PERMISSION_OTHERS_EXECUTE = 1

Sub `BrickRED.``GetProcesses`(ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef processesListId As Integer)

Sub `BrickRED.``SpawnProcess`(ByVal executableStringId As Integer, ByVal argumentsListId As Integer, ByVal environmentListId As Integer, ByVal workingDirectoryStringId As Integer, ByVal uid As Long, ByVal gid As Long, ByVal stdinFileId As Integer, ByVal stdoutFileId As Integer, ByVal stderrFileId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef processId As Integer)

Function `BrickRED.``KillProcess`(ByVal processId As Integer, ByVal signal As Byte) As Byte

  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 constants are available for this function:

  - BrickRED.PROCESS_SIGNAL_INTERRUPT = 2
  - BrickRED.PROCESS_SIGNAL_QUIT = 3
  - BrickRED.PROCESS_SIGNAL_ABORT = 6
  - BrickRED.PROCESS_SIGNAL_KILL = 9
  - BrickRED.PROCESS_SIGNAL_USER1 = 10
  - BrickRED.PROCESS_SIGNAL_USER2 = 12
  - BrickRED.PROCESS_SIGNAL_TERMINATE = 15
  - BrickRED.PROCESS_SIGNAL_CONTINUE = 18
  - BrickRED.PROCESS_SIGNAL_STOP = 19

Sub `BrickRED.``GetProcessCommand`(ByVal processId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef executableStringId As Integer, ByRef argumentsListId As Integer, ByRef environmentListId As Integer, ByRef workingDirectoryStringId As Integer)

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

Sub `BrickRED.``GetProcessIdentity`(ByVal processId As Integer, ByRef errorCode As Byte, ByRef pid As Long, ByRef uid As Long, ByRef gid As Long)

  Returns the process ID and the user and group ID used to spawn a process object, as passed to `SpawnProcess()`, and the resulting error code.

  The process ID is only valid if the state is Running or Stopped, see `GetProcessState()`.

Sub `BrickRED.``GetProcessStdio`(ByVal processId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef stdinFileId As Integer, ByRef stdoutFileId As Integer, ByRef stderrFileId As Integer)

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

Sub `BrickRED.``GetProcessState`(ByVal processId As Integer, ByRef errorCode As Byte, ByRef state As Byte, ByRef timestamp As Long, ByRef exitCode As Byte)

  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 constants are available for this function:

  - BrickRED.PROCESS_STATE_UNKNOWN = 0
  - BrickRED.PROCESS_STATE_RUNNING = 1
  - BrickRED.PROCESS_STATE_ERROR = 2
  - BrickRED.PROCESS_STATE_EXITED = 3
  - BrickRED.PROCESS_STATE_KILLED = 4
  - BrickRED.PROCESS_STATE_STOPPED = 5

Sub `BrickRED.``GetPrograms`(ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef programsListId As Integer)

Sub `BrickRED.``DefineProgram`(ByVal identifierStringId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef programId As Integer)

Function `BrickRED.``PurgeProgram`(ByVal programId As Integer, ByVal cookie As Long) As Byte

Sub `BrickRED.``GetProgramIdentifier`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef identifierStringId As Integer)

Sub `BrickRED.``GetProgramRootDirectory`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef rootDirectoryStringId As Integer)

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

Function `BrickRED.``SetProgramCommand`(ByVal programId As Integer, ByVal executableStringId As Integer, ByVal argumentsListId As Integer, ByVal environmentListId As Integer, ByVal workingDirectoryStringId As Integer) As Byte

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

Sub `BrickRED.``GetProgramCommand`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef executableStringId As Integer, ByRef argumentsListId As Integer, ByRef environmentListId As Integer, ByRef workingDirectoryStringId As Integer)

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

Function `BrickRED.``SetProgramStdioRedirection`(ByVal programId As Integer, ByVal stdinRedirection As Byte, ByVal stdinFileNameStringId As Integer, ByVal stdoutRedirection As Byte, ByVal stdoutFileNameStringId As Integer, ByVal stderrRedirection As Byte, ByVal stderrFileNameStringId As Integer) As Byte

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

  The following constants are available for this function:

  - BrickRED.PROGRAM_STDIO_REDIRECTION_DEV_NULL = 0
  - BrickRED.PROGRAM_STDIO_REDIRECTION_PIPE = 1
  - BrickRED.PROGRAM_STDIO_REDIRECTION_FILE = 2
  - BrickRED.PROGRAM_STDIO_REDIRECTION_INDIVIDUAL_LOG = 3
  - BrickRED.PROGRAM_STDIO_REDIRECTION_CONTINUOUS_LOG = 4
  - BrickRED.PROGRAM_STDIO_REDIRECTION_STDOUT = 5

Sub `BrickRED.``GetProgramStdioRedirection`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef stdinRedirection As Byte, ByRef stdinFileNameStringId As Integer, ByRef stdoutRedirection As Byte, ByRef stdoutFileNameStringId As Integer, ByRef stderrRedirection As Byte, ByRef stderrFileNameStringId As Integer)

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

  The following constants are available for this function:

  - BrickRED.PROGRAM_STDIO_REDIRECTION_DEV_NULL = 0
  - BrickRED.PROGRAM_STDIO_REDIRECTION_PIPE = 1
  - BrickRED.PROGRAM_STDIO_REDIRECTION_FILE = 2
  - BrickRED.PROGRAM_STDIO_REDIRECTION_INDIVIDUAL_LOG = 3
  - BrickRED.PROGRAM_STDIO_REDIRECTION_CONTINUOUS_LOG = 4
  - BrickRED.PROGRAM_STDIO_REDIRECTION_STDOUT = 5

Function `BrickRED.``SetProgramSchedule`(ByVal programId As Integer, ByVal startMode As Byte, ByVal continueAfterError As Boolean, ByVal startInterval As Long, ByVal startFieldsStringId As Integer) As Byte

  The following constants are available for this function:

  - BrickRED.PROGRAM_START_MODE_NEVER = 0
  - BrickRED.PROGRAM_START_MODE_ALWAYS = 1
  - BrickRED.PROGRAM_START_MODE_INTERVAL = 2
  - BrickRED.PROGRAM_START_MODE_CRON = 3

Sub `BrickRED.``GetProgramSchedule`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef startMode As Byte, ByRef continueAfterError As Boolean, ByRef startInterval As Long, ByRef startFieldsStringId As Integer)

  The following constants are available for this function:

  - BrickRED.PROGRAM_START_MODE_NEVER = 0
  - BrickRED.PROGRAM_START_MODE_ALWAYS = 1
  - BrickRED.PROGRAM_START_MODE_INTERVAL = 2
  - BrickRED.PROGRAM_START_MODE_CRON = 3

Sub `BrickRED.``GetProgramSchedulerState`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef state As Byte, ByRef timestamp As Long, ByRef messageStringId As Integer)

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

  The following constants are available for this function:

  - BrickRED.PROGRAM_SCHEDULER_STATE_STOPPED = 0
  - BrickRED.PROGRAM_SCHEDULER_STATE_RUNNING = 1

Function `BrickRED.``ContinueProgramSchedule`(ByVal programId As Integer) As Byte

Function `BrickRED.``StartProgram`(ByVal programId As Integer) As Byte

Sub `BrickRED.``GetLastSpawnedProgramProcess`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef processId As Integer, ByRef timestamp As Long)

Sub `BrickRED.``GetCustomProgramOptionNames`(ByVal programId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef namesListId As Integer)

Function `BrickRED.``SetCustomProgramOptionValue`(ByVal programId As Integer, ByVal nameStringId As Integer, ByVal valueStringId As Integer) As Byte

Sub `BrickRED.``GetCustomProgramOptionValue`(ByVal programId As Integer, ByVal nameStringId As Integer, ByVal sessionId As Integer, ByRef errorCode As Byte, ByRef valueStringId As Integer)

Function `BrickRED.``RemoveCustomProgramOption`(ByVal programId As Integer, ByVal nameStringId As Integer) As Byte

Function `BrickRED.``GetAPIVersion`() As Byte()

  Returns the version of the API definition (major, minor, revision) implemented by this API bindings. This is neither the release version of this API bindings nor does it tell you anything about the represented Brick or Bricklet.

Function `BrickRED.``GetResponseExpected`(ByVal functionId As Byte) As Boolean

  Returns the response expected flag for the function specified by the function ID parameter. It is true if the function is expected to send a response, false otherwise.

  For getter functions this is enabled by default and cannot be disabled, because those functions will always send a response. For callback configuration functions it is enabled by default too, but can be disabled by `SetResponseExpected()`. For setter functions it is disabled by default and can be enabled.

  Enabling the response expected flag for a setter function allows to detect timeouts and other error conditions calls of this setter as well. The device will then send a response for this purpose. If this flag is disabled for a setter function then no response is send and errors are silently ignored, because they cannot be detected.

  See `SetResponseExpected()` for the list of function ID constants available for this function.

Sub `BrickRED.``SetResponseExpected`(ByVal functionId As Byte, ByVal responseExpected As Boolean)

  Changes the response expected flag of the function specified by the function ID parameter. This flag can only be changed for setter (default value: false) and callback configuration functions (default value: true). For getter functions it is always enabled and callbacks it is always disabled.

  Enabling the response expected flag for a setter function allows to detect timeouts and other error conditions calls of this setter as well. The device will then send a response for this purpose. If this flag is disabled for a setter function then no response is send and errors are silently ignored, because they cannot be detected.

  The following function ID constants are available for this function:

  - BrickRED.FUNCTION_EXPIRE_SESSION_UNCHECKED = 3
  - BrickRED.FUNCTION_RELEASE_OBJECT_UNCHECKED = 6
  - BrickRED.FUNCTION_READ_FILE_ASYNC = 21
  - BrickRED.FUNCTION_WRITE_FILE_UNCHECKED = 24
  - BrickRED.FUNCTION_WRITE_FILE_ASYNC = 25

Sub `BrickRED.``SetResponseExpectedAll`(ByVal responseExpected As Boolean)

  Changes the response expected flag for all setter and callback configuration functions of this device at once.

Sub `BrickRED.``GetIdentity`(ByRef uid As String, ByRef connectedUid As String, ByRef position As Char, ByRef hardwareVersion() As Byte, ByRef firmwareVersion() As Byte, ByRef deviceIdentifier As Integer)

  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. There is also a constant for the device identifier of this Brick.

### Callbacks

Callbacks can be registered to receive time critical or recurring data from the device. The registration is done by assigning a procedure to an callback property of the device object:

>     Sub Callback(ByVal sender As BrickRED, ByVal value As Short)
>         Console.WriteLine("Value: {0}", value)
>     End Sub

>     AddHandler red.Example, AddressOf Callback

The available callback property and their type of parameters are described below.

Note

Using callbacks for recurring events is always preferred compared to using getters. It will use less USB bandwidth and the latency will be a lot better, since there is no round trip time.

Event `BrickRED.``AsyncFileRead`(ByVal sender As BrickRED, ByVal fileId As Integer, ByVal errorCode As Byte, ByVal buffer() As Byte, ByVal lengthRead As Byte)

  This callback reports the result of a call to the `ReadFileAsync()` function.

Event `BrickRED.``AsyncFileWrite`(ByVal sender As BrickRED, ByVal fileId As Integer, ByVal errorCode As Byte, ByVal lengthWritten As Byte)

  This callback reports the result of a call to the `WriteFileAsync()` function.

Event `BrickRED.``FileEventsOccurred`(ByVal sender As BrickRED, ByVal fileId As Integer, ByVal events As Integer)

  The following constants are available for this function:

  - BrickRED.FILE_EVENT_READABLE = 1
  - BrickRED.FILE_EVENT_WRITABLE = 2

Event `BrickRED.``ProcessStateChanged`(ByVal sender As BrickRED, ByVal processId As Integer, ByVal state As Byte, ByVal timestamp As Long, ByVal exitCode As Byte)

  The following constants are available for this function:

  - BrickRED.PROCESS_STATE_UNKNOWN = 0
  - BrickRED.PROCESS_STATE_RUNNING = 1
  - BrickRED.PROCESS_STATE_ERROR = 2
  - BrickRED.PROCESS_STATE_EXITED = 3
  - BrickRED.PROCESS_STATE_KILLED = 4
  - BrickRED.PROCESS_STATE_STOPPED = 5

Event `BrickRED.``ProgramSchedulerStateChanged`(ByVal sender As BrickRED, ByVal programId As Integer)

Event `BrickRED.``ProgramProcessSpawned`(ByVal sender As BrickRED, ByVal programId As Integer)

### Constants

Const `BrickRED.``DEVICE_IDENTIFIER`

  This constant is used to identify a RED Brick.

  The `GetIdentity()` function and the `EnumerateCallback` callback of the IP Connection have a `deviceIdentifier` parameter to specify the Brick's or Bricklet's type.

The content of this page is licensed under Creative Commons Attribution 3.0 Unported License.