..
 #############################################################
 # This file was automatically generated on 2015-05-08.      #
 #                                                           #
 # If you have a bugfix for this file and want to commit it, #
 # please fix the bug in the generator. You can find a link  #
 # to the generators git repository on tinkerforge.com       #
 #############################################################


:breadcrumbs: <a href="../../index.html">Home</a> / <a href="../../index.html#software-javascript">Software</a> / JavaScript - RED Brick

.. |device_identifier_constant| replace:: There is also a :ref:`constant <red_brick_javascript_constants>` for the device identifier of this Brick.

.. _red_brick_javascript:

JavaScript - RED Brick
======================

This is the description of the :ref:`JavaScript API bindings <api_bindings_javascript>` for the :ref:`RED Brick <red_brick>`. General information and technical
specifications for the RED Brick are summarized in its :ref:`hardware description
<red_brick_description>`.

An :ref:`installation guide <api_bindings_javascript_install>` for the JavaScript API
bindings is part of their general description.

.. _red_brick_javascript_examples:


Examples
--------

The example code below is `Public Domain (CC0 1.0)
<http://creativecommons.org/publicdomain/zero/1.0/>`__.

.. _red_brick_javascript_api:

API
---

Generally, every method of the JavaScript bindings can take two optional
parameters, ``returnCallback`` and ``errorCallback``. These are two user
defined callback functions. The ``returnCallback`` is called with the return
values as parameters, if the method returns something. The ``errorCallback``
is called with an error code in case of an error. The error code can be one
of the following values:

* IPConnection.ERROR_ALREADY_CONNECTED = 11
* IPConnection.ERROR_NOT_CONNECTED = 12
* IPConnection.ERROR_CONNECT_FAILED = 13
* IPConnection.ERROR_INVALID_FUNCTION_ID = 21
* IPConnection.ERROR_TIMEOUT = 31
* IPConnection.ERROR_INVALID_PARAMETER = 41
* IPConnection.ERROR_FUNCTION_NOT_SUPPORTED = 42
* IPConnection.ERROR_UNKNOWN_ERROR = 43

The namespace for the JavaScript bindings is ``Tinkerforge.*``.


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. :javascript:func:`allocateString() <BrickRED.allocateString>`
and :javascript:func:`getNextDirectoryEntry() <BrickRED.getNextDirectoryEntry>`) increase the reference count of the returned
object. If the object is no longer needed then :javascript:func:`releaseObject() <BrickRED.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 :javascript:func:`releaseObject() <BrickRED.releaseObject>` must not be called for
such an object in response to a callback.

There are functions (e.g. :javascript:func:`getFileInfo() <BrickRED.getFileInfo>`) that only return valid objects
under certain conditions. This conditions are documented for the specific
functions. For invalid objects :javascript:func:`releaseObject() <BrickRED.releaseObject>` must not be called.

There are also function (e.g. :javascript:func:`setProgramStdioRedirection() <BrickRED.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 :ref:`TCP/IP protocol <llproto_tcpip>`
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
^^^^^^^^^^^^^^^^^^

.. javascript:function:: BrickRED.createSession(lifetime, [returnCallback], [errorCallback])

 :param lifetime: int

 :return errorCode: int
 :return sessionId: int

 
.. javascript:function:: BrickRED.expireSession(sessionId, [returnCallback], [errorCallback])

 :param sessionId: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.expireSessionUnchecked(sessionId, [returnCallback], [errorCallback])

 :param sessionId: int

 :noreturn: undefined

 
.. javascript:function:: BrickRED.keepSessionAlive(sessionId, lifetime, [returnCallback], [errorCallback])

 :param sessionId: int
 :param lifetime: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.releaseObject(objectId, sessionId, [returnCallback], [errorCallback])

 :param objectId: int
 :param sessionId: int

 :return errorCode: int

 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.
 
.. javascript:function:: BrickRED.releaseObjectUnchecked(objectId, sessionId, [returnCallback], [errorCallback])

 :param objectId: int
 :param sessionId: int

 :noreturn: undefined

 
.. javascript:function:: BrickRED.allocateString(lengthToReserve, buffer, sessionId, [returnCallback], [errorCallback])

 :param lengthToReserve: int
 :param buffer: string
 :param sessionId: int

 :return errorCode: int
 :return stringId: int

 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.
 
.. javascript:function:: BrickRED.truncateString(stringId, length, [returnCallback], [errorCallback])

 :param stringId: int
 :param length: int

 :return errorCode: int

 Truncates a string object to ``length`` bytes and returns the resulting
 error code.
 
.. javascript:function:: BrickRED.getStringLength(stringId, [returnCallback], [errorCallback])

 :param stringId: int

 :return errorCode: int
 :return length: int

 Returns the length of a string object in bytes and the resulting error code.
 
.. javascript:function:: BrickRED.setStringChunk(stringId, offset, buffer, [returnCallback], [errorCallback])

 :param stringId: int
 :param offset: int
 :param buffer: string

 :return errorCode: int

 Sets a chunk of up to 58 bytes in a string object beginning at ``offset``.
 
 Returns the resulting error code.
 
.. javascript:function:: BrickRED.getStringChunk(stringId, offset, [returnCallback], [errorCallback])

 :param stringId: int
 :param offset: int

 :return errorCode: int
 :return buffer: string

 Returns a chunk up to 63 bytes from a string object beginning at ``offset`` and
 returns the resulting error code.
 
.. javascript:function:: BrickRED.allocateList(lengthToReserve, sessionId, [returnCallback], [errorCallback])

 :param lengthToReserve: int
 :param sessionId: int

 :return errorCode: int
 :return listId: int

 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.
 
.. javascript:function:: BrickRED.getListLength(listId, [returnCallback], [errorCallback])

 :param listId: int

 :return errorCode: int
 :return length: int

 Returns the length of a list object in items and the resulting error code.
 
.. javascript:function:: BrickRED.getListItem(listId, index, sessionId, [returnCallback], [errorCallback])

 :param listId: int
 :param index: int
 :param sessionId: int

 :return errorCode: int
 :return itemObjectId: int
 :return type: int

 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
 
.. javascript:function:: BrickRED.appendToList(listId, itemObjectId, [returnCallback], [errorCallback])

 :param listId: int
 :param itemObjectId: int

 :return errorCode: int

 Appends an object to a list object and increases the reference count of the
 appended object by one.
 
 Returns the resulting error code.
 
.. javascript:function:: BrickRED.removeFromList(listId, index, [returnCallback], [errorCallback])

 :param listId: int
 :param index: int

 :return errorCode: int

 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.
 
.. javascript:function:: BrickRED.openFile(nameStringId, flags, permissions, uid, gid, sessionId, [returnCallback], [errorCallback])

 :param nameStringId: int
 :param flags: int
 :param permissions: int
 :param uid: int
 :param gid: int
 :param sessionId: int

 :return errorCode: int
 :return fileId: int

 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
 
.. javascript:function:: BrickRED.createPipe(flags, length, sessionId, [returnCallback], [errorCallback])

 :param flags: int
 :param length: int
 :param sessionId: int

 :return errorCode: int
 :return fileId: int

 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
 
.. javascript:function:: BrickRED.getFileInfo(fileId, sessionId, [returnCallback], [errorCallback])

 :param fileId: int
 :param sessionId: int

 :return errorCode: int
 :return type: int
 :return nameStringId: int
 :return flags: int
 :return permissions: int
 :return uid: int
 :return gid: int
 :return length: int
 :return accessTimestamp: int
 :return modificationTimestamp: int
 :return statusChangeTimestamp: int

 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 :javascript:func:`openFile() <BrickRED.openFile>`.
 
 The returned flags were used to open or create the file object, as passed to
 :javascript:func:`openFile() <BrickRED.openFile>` or :javascript:func:`createPipe() <BrickRED.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
 
.. javascript:function:: BrickRED.readFile(fileId, lengthToRead, [returnCallback], [errorCallback])

 :param fileId: int
 :param lengthToRead: int

 :return errorCode: int
 :return buffer: [int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int]
 :return lengthRead: int

 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 :javascript:func:`openFile() <BrickRED.openFile>` without the *NonBlocking*
 flag or by :javascript:func:`createPipe() <BrickRED.createPipe>` without the *NonBlockingRead* flag then the
 error code *NotSupported* is returned.
 
.. javascript:function:: BrickRED.readFileAsync(fileId, lengthToRead, [returnCallback], [errorCallback])

 :param fileId: int
 :param lengthToRead: int

 :noreturn: undefined

 Reads up to 2\ :sup:`63`\  - 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 :javascript:attr:`CALLBACK_ASYNC_FILE_READ <BrickRED.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 :javascript:func:`openFile() <BrickRED.openFile>` without the *NonBlocking*
 flag or by :javascript:func:`createPipe() <BrickRED.createPipe>` without the *NonBlockingRead* flag then the error
 code *NotSupported* is reported via the :javascript:attr:`CALLBACK_ASYNC_FILE_READ <BrickRED.CALLBACK_ASYNC_FILE_READ>` callback.
 
.. javascript:function:: BrickRED.abortAsyncFileRead(fileId, [returnCallback], [errorCallback])

 :param fileId: int

 :return errorCode: int

 Aborts a :javascript:func:`readFileAsync() <BrickRED.readFileAsync>` operation in progress.
 
 Returns the resulting error code.
 
 On success the :javascript:attr:`CALLBACK_ASYNC_FILE_READ <BrickRED.CALLBACK_ASYNC_FILE_READ>` callback will report *OperationAborted*.
 
.. javascript:function:: BrickRED.writeFile(fileId, buffer, lengthToWrite, [returnCallback], [errorCallback])

 :param fileId: int
 :param buffer: [int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int]
 :param lengthToWrite: int

 :return errorCode: int
 :return lengthWritten: int

 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 :javascript:func:`openFile() <BrickRED.openFile>` without the *NonBlocking*
 flag or by :javascript:func:`createPipe() <BrickRED.createPipe>` without the *NonBlockingWrite* flag then the
 error code *NotSupported* is returned.
 
.. javascript:function:: BrickRED.writeFileUnchecked(fileId, buffer, lengthToWrite, [returnCallback], [errorCallback])

 :param fileId: int
 :param buffer: [int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int]
 :param lengthToWrite: int

 :noreturn: undefined

 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 :javascript:func:`openFile() <BrickRED.openFile>` without the *NonBlocking*
 flag or by :javascript:func:`createPipe() <BrickRED.createPipe>` without the *NonBlockingWrite* flag then the
 write operation will fail silently.
 
.. javascript:function:: BrickRED.writeFileAsync(fileId, buffer, lengthToWrite, [returnCallback], [errorCallback])

 :param fileId: int
 :param buffer: [int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int]
 :param lengthToWrite: int

 :noreturn: undefined

 Writes up to 61 bytes to a file object.
 
 Reports the actual number of bytes written and the resulting error code via the
 :javascript:attr:`CALLBACK_ASYNC_FILE_WRITE <BrickRED.CALLBACK_ASYNC_FILE_WRITE>` callback.
 
 If the file object was created by :javascript:func:`openFile() <BrickRED.openFile>` without the *NonBlocking*
 flag or by :javascript:func:`createPipe() <BrickRED.createPipe>` without the *NonBlockingWrite* flag then the
 error code *NotSupported* is reported via the :javascript:attr:`CALLBACK_ASYNC_FILE_WRITE <BrickRED.CALLBACK_ASYNC_FILE_WRITE>` callback.
 
.. javascript:function:: BrickRED.setFilePosition(fileId, offset, origin, [returnCallback], [errorCallback])

 :param fileId: int
 :param offset: int
 :param origin: int

 :return errorCode: int
 :return position: int

 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 :javascript:func:`createPipe() <BrickRED.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
 
.. javascript:function:: BrickRED.getFilePosition(fileId, [returnCallback], [errorCallback])

 :param fileId: int

 :return errorCode: int
 :return position: int

 Returns the current seek position of a file object in bytes and returns the
 resulting error code.
 
 If the file object was created by :javascript:func:`createPipe() <BrickRED.createPipe>` then it has no seek
 position and the error code *InvalidSeek* is returned.
 
.. javascript:function:: BrickRED.setFileEvents(fileId, events, [returnCallback], [errorCallback])

 :param fileId: int
 :param events: int

 :return errorCode: int

 
 The following constants are available for this function:
 
 * BrickRED.FILE_EVENT_READABLE = 1
 * BrickRED.FILE_EVENT_WRITABLE = 2
 
.. javascript:function:: BrickRED.getFileEvents(fileId, [returnCallback], [errorCallback])

 :param fileId: int

 :return errorCode: int
 :return events: int

 
 The following constants are available for this function:
 
 * BrickRED.FILE_EVENT_READABLE = 1
 * BrickRED.FILE_EVENT_WRITABLE = 2
 
.. javascript:function:: BrickRED.openDirectory(nameStringId, sessionId, [returnCallback], [errorCallback])

 :param nameStringId: int
 :param sessionId: int

 :return errorCode: int
 :return directoryId: int

 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.
 
.. javascript:function:: BrickRED.getDirectoryName(directoryId, sessionId, [returnCallback], [errorCallback])

 :param directoryId: int
 :param sessionId: int

 :return errorCode: int
 :return nameStringId: int

 Returns the name of a directory object, as passed to :javascript:func:`openDirectory() <BrickRED.openDirectory>`, and
 the resulting error code.
 
.. javascript:function:: BrickRED.getNextDirectoryEntry(directoryId, sessionId, [returnCallback], [errorCallback])

 :param directoryId: int
 :param sessionId: int

 :return errorCode: int
 :return nameStringId: int
 :return type: int

 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 :javascript:func:`rewindDirectory() <BrickRED.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
 
.. javascript:function:: BrickRED.rewindDirectory(directoryId, [returnCallback], [errorCallback])

 :param directoryId: int

 :return errorCode: int

 Rewinds a directory object and returns the resulting error code.
 
.. javascript:function:: BrickRED.createDirectory(nameStringId, flags, permissions, uid, gid, [returnCallback], [errorCallback])

 :param nameStringId: int
 :param flags: int
 :param permissions: int
 :param uid: int
 :param gid: int

 :return errorCode: int

 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
 
.. javascript:function:: BrickRED.getProcesses(sessionId, [returnCallback], [errorCallback])

 :param sessionId: int

 :return errorCode: int
 :return processesListId: int

 
.. javascript:function:: BrickRED.spawnProcess(executableStringId, argumentsListId, environmentListId, workingDirectoryStringId, uid, gid, stdinFileId, stdoutFileId, stderrFileId, sessionId, [returnCallback], [errorCallback])

 :param executableStringId: int
 :param argumentsListId: int
 :param environmentListId: int
 :param workingDirectoryStringId: int
 :param uid: int
 :param gid: int
 :param stdinFileId: int
 :param stdoutFileId: int
 :param stderrFileId: int
 :param sessionId: int

 :return errorCode: int
 :return processId: int

 
.. javascript:function:: BrickRED.killProcess(processId, signal, [returnCallback], [errorCallback])

 :param processId: int
 :param signal: int

 :return errorCode: int

 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
 
.. javascript:function:: BrickRED.getProcessCommand(processId, sessionId, [returnCallback], [errorCallback])

 :param processId: int
 :param sessionId: int

 :return errorCode: int
 :return executableStringId: int
 :return argumentsListId: int
 :return environmentListId: int
 :return workingDirectoryStringId: int

 Returns the executable, arguments, environment and working directory used to
 spawn a process object, as passed to :javascript:func:`spawnProcess() <BrickRED.spawnProcess>`, and the resulting
 error code.
 
.. javascript:function:: BrickRED.getProcessIdentity(processId, [returnCallback], [errorCallback])

 :param processId: int

 :return errorCode: int
 :return pid: int
 :return uid: int
 :return gid: int

 Returns the process ID and the user and group ID used to spawn a process object,
 as passed to :javascript:func:`spawnProcess() <BrickRED.spawnProcess>`, and the resulting error code.
 
 The process ID is only valid if the state is *Running* or *Stopped*, see
 :javascript:func:`getProcessState() <BrickRED.getProcessState>`.
 
.. javascript:function:: BrickRED.getProcessStdio(processId, sessionId, [returnCallback], [errorCallback])

 :param processId: int
 :param sessionId: int

 :return errorCode: int
 :return stdinFileId: int
 :return stdoutFileId: int
 :return stderrFileId: int

 Returns the stdin, stdout and stderr files used to spawn a process object, as
 passed to :javascript:func:`spawnProcess() <BrickRED.spawnProcess>`, and the resulting error code.
 
.. javascript:function:: BrickRED.getProcessState(processId, [returnCallback], [errorCallback])

 :param processId: int

 :return errorCode: int
 :return state: int
 :return timestamp: int
 :return exitCode: int

 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
 
.. javascript:function:: BrickRED.getPrograms(sessionId, [returnCallback], [errorCallback])

 :param sessionId: int

 :return errorCode: int
 :return programsListId: int

 
.. javascript:function:: BrickRED.defineProgram(identifierStringId, sessionId, [returnCallback], [errorCallback])

 :param identifierStringId: int
 :param sessionId: int

 :return errorCode: int
 :return programId: int

 
.. javascript:function:: BrickRED.purgeProgram(programId, cookie, [returnCallback], [errorCallback])

 :param programId: int
 :param cookie: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.getProgramIdentifier(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return identifierStringId: int

 
.. javascript:function:: BrickRED.getProgramRootDirectory(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return rootDirectoryStringId: int

 FIXME: root directory is absolute: <home>/programs/<identifier>
 
.. javascript:function:: BrickRED.setProgramCommand(programId, executableStringId, argumentsListId, environmentListId, workingDirectoryStringId, [returnCallback], [errorCallback])

 :param programId: int
 :param executableStringId: int
 :param argumentsListId: int
 :param environmentListId: int
 :param workingDirectoryStringId: int

 :return errorCode: int

 FIXME: working directory is relative to <home>/programs/<identifier>/bin
 
.. javascript:function:: BrickRED.getProgramCommand(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return executableStringId: int
 :return argumentsListId: int
 :return environmentListId: int
 :return workingDirectoryStringId: int

 FIXME: working directory is relative to <home>/programs/<identifier>/bin
 
.. javascript:function:: BrickRED.setProgramStdioRedirection(programId, stdinRedirection, stdinFileNameStringId, stdoutRedirection, stdoutFileNameStringId, stderrRedirection, stderrFileNameStringId, [returnCallback], [errorCallback])

 :param programId: int
 :param stdinRedirection: int
 :param stdinFileNameStringId: int
 :param stdoutRedirection: int
 :param stdoutFileNameStringId: int
 :param stderrRedirection: int
 :param stderrFileNameStringId: int

 :return errorCode: int

 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
 
.. javascript:function:: BrickRED.getProgramStdioRedirection(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return stdinRedirection: int
 :return stdinFileNameStringId: int
 :return stdoutRedirection: int
 :return stdoutFileNameStringId: int
 :return stderrRedirection: int
 :return stderrFileNameStringId: int

 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
 
.. javascript:function:: BrickRED.setProgramSchedule(programId, startMode, continueAfterError, startInterval, startFieldsStringId, [returnCallback], [errorCallback])

 :param programId: int
 :param startMode: int
 :param continueAfterError: boolean
 :param startInterval: int
 :param startFieldsStringId: int

 :return errorCode: int

 
 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
 
.. javascript:function:: BrickRED.getProgramSchedule(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return startMode: int
 :return continueAfterError: boolean
 :return startInterval: int
 :return startFieldsStringId: int

 
 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
 
.. javascript:function:: BrickRED.getProgramSchedulerState(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return state: int
 :return timestamp: int
 :return messageStringId: int

 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
 
.. javascript:function:: BrickRED.continueProgramSchedule(programId, [returnCallback], [errorCallback])

 :param programId: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.startProgram(programId, [returnCallback], [errorCallback])

 :param programId: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.getLastSpawnedProgramProcess(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return processId: int
 :return timestamp: int

 
.. javascript:function:: BrickRED.getCustomProgramOptionNames(programId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param sessionId: int

 :return errorCode: int
 :return namesListId: int

 
.. javascript:function:: BrickRED.setCustomProgramOptionValue(programId, nameStringId, valueStringId, [returnCallback], [errorCallback])

 :param programId: int
 :param nameStringId: int
 :param valueStringId: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.getCustomProgramOptionValue(programId, nameStringId, sessionId, [returnCallback], [errorCallback])

 :param programId: int
 :param nameStringId: int
 :param sessionId: int

 :return errorCode: int
 :return valueStringId: int

 
.. javascript:function:: BrickRED.removeCustomProgramOption(programId, nameStringId, [returnCallback], [errorCallback])

 :param programId: int
 :param nameStringId: int

 :return errorCode: int

 
.. javascript:function:: BrickRED.getAPIVersion()

 :rtype: [int, int, int]

 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.
 
.. javascript:function:: BrickRED.getResponseExpected(functionId, [errorCallback])

 :param functionId: int
 :rtype: 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
 :javascript:func:`setResponseExpected() <BrickRED.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 :javascript:func:`setResponseExpected() <BrickRED.setResponseExpected>`
 for the list of function ID constants available for this function.
 
.. javascript:function:: BrickRED.setResponseExpected(functionId, responseExpected, [errorCallback])

 :param functionId: int
 :param responseExpected: 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
 
.. javascript:function:: BrickRED.setResponseExpectedAll(responseExpected)

 :param responseExpected: boolean

 Changes the response expected flag for all setter and callback configuration
 functions of this device at once.
 
.. javascript:function:: BrickRED.getIdentity([returnCallback], [errorCallback])


 :return uid: string
 :return connectedUid: string
 :return position: char
 :return hardwareVersion: [int, int, int]
 :return firmwareVersion: [int, int, int]
 :return deviceIdentifier: int

 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 :ref:`here <device_identifier>`.
 |device_identifier_constant|
 


Callback Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


.. javascript:function:: BrickRED.on(id, callback)

 :param id: int
 :param callback: function

 Registers a callback with ID *id* to the function *callback*. The available
 IDs with corresponding function signatures are listed
 :ref:`below <red_brick_javascript_callbacks>`.




.. _red_brick_javascript_callbacks:

Callbacks
^^^^^^^^^

Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the :javascript:func:`on() <BrickRED.on>` function of
the device object. The first parameter is the callback ID and the second
parameter the callback function:

.. code-block:: javascript

    red.on(BrickRED.CALLBACK_EXAMPLE,
        function (param) {
            console.log(param);
        }
    );

The available constants with inherent number and 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.

.. javascript:attribute:: BrickRED.CALLBACK_ASYNC_FILE_READ

 :param fileId: int
 :param errorCode: int
 :param buffer: [int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int, int]
 :param lengthRead: int


 This callback reports the result of a call to the :javascript:func:`readFileAsync() <BrickRED.readFileAsync>`
 function.
 
.. javascript:attribute:: BrickRED.CALLBACK_ASYNC_FILE_WRITE

 :param fileId: int
 :param errorCode: int
 :param lengthWritten: int


 This callback reports the result of a call to the :javascript:func:`writeFileAsync() <BrickRED.writeFileAsync>`
 function.
 
.. javascript:attribute:: BrickRED.CALLBACK_FILE_EVENTS_OCCURRED

 :param fileId: int
 :param events: int


 
 The following constants are available for this function:
 
 * BrickRED.FILE_EVENT_READABLE = 1
 * BrickRED.FILE_EVENT_WRITABLE = 2
 
.. javascript:attribute:: BrickRED.CALLBACK_PROCESS_STATE_CHANGED

 :param processId: int
 :param state: int
 :param timestamp: int
 :param exitCode: int


 
 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
 
.. javascript:attribute:: BrickRED.CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED

 :param programId: int


 
.. javascript:attribute:: BrickRED.CALLBACK_PROGRAM_PROCESS_SPAWNED

 :param programId: int


 


.. _red_brick_javascript_constants:

Constants
^^^^^^^^^

.. javascript:attribute:: BrickRED.DEVICE_IDENTIFIER

 This constant is used to identify a RED Brick.

 The :javascript:func:`getIdentity() <BrickRED.getIdentity>` function and the
 :javascript:attr:`CALLBACK_ENUMERATE <IPConnection.CALLBACK_ENUMERATE>`
 callback of the IP Connection have a ``device_identifier`` parameter to specify
 the Brick's or Bricklet's type.

