aLink.h¶

group aLink

BrainStem Link Interface.

aLink.h provides the interface for creating and maintaining the link to a BrainStem module, and the BrainStem network. It includes facilities for starting and stopping links, as well as sending and receiving BrainStem protocol packets.

typedef uint32_t aLinkRef¶

Typedef aLinkRef Opaque reference to a BrainStem link.

Typedef for aLinkRef for an opaque reference to BrainStem Link.

enum linkStatus¶

Represents the current state of the BrainStem link.

Values:

enumerator STOPPED¶: Link currently stopped.

enumerator INITIALIZING¶: Starting communication with module.

enumerator RUNNING¶: Link running.

enumerator STOPPING¶: Link is in the process of stopping.

enumerator SYNCING¶: Packet framing lost re-syncing.

enumerator INVALID_LINK_STREAM¶: Link stream provided is not valid.

enumerator IO_ERROR¶: Communication error occured on link, could not resync.

enumerator RESETTING¶: Resetting the link connection

enumerator UNKNOWN_ERROR¶: Something really bad happened, but we couldn’t determin what.

aLinkRef aLink_CreateUSB(const uint32_t serialNumber)¶

Create a USB BrainStem link reference.

Creates a reference to a USB BrainStem link. The linkStream is now maintained by the BrainStem link. If the link already exists, the use count for that link will be incremented and the linkRef for that entry will be returned.

Links created with this procedure must use aLink_Destroy to properly dispose of the link reference and associated connections.

Parameters:: serialNumber – Unique identifier of the device.
Returns:: aLinkRef identifier if successful or 0 otherwise.

aLinkRef aLink_CreateTCPIP(const uint32_t address, const uint16_t port)¶

Creates a reference to a BrainStem link. The linkStream is now maintained by the BrainStem link. If the link already exists, the use count for that link will be incremented and the linkRef for that entry will be returned.

Links created with this procedure must use aLink_Destroy to properly dispose of the link reference and associated connections.

Parameters:

address – the TCPIP address
port – the TCPIP port

Returns:

aLinkRef identifier if successful or 0 otherwise.

aErr aLink_Destroy(aLinkRef *linkRef)¶

Destroy a BrainStem link reference.

Destroys a Link reference. deallocating associated resources cleanly.

Links created with aLink_Create must use aLink_Destroy to clean up resources used by the link Ref.

Parameters:: linkRef – a Pointer to a valid LinkRef. The linkRef will be set to NULL on succesful completion of the Destroy call.
Returns:: aStreamRef Return value will always be NULL. The return value has been left for backwards compatability.

aErr aLink_Reset(const aLinkRef linkRef)¶

Reset a connection to a BrainStem module.

Stop the active connection to the BrainStem if the Link contains a valid stream Reference, and clear out the communication buffers, and restart the link.

Parameters:

linkRef – A valid LinkRef.

Return values:

aErrNone – the call completed successfully, a subsequent call to aLink_GetStatus should return the current state of the link.
aErrParam – No valid LinkRef provided.

Returns:

Function returns aErr values.

linkStatus aLink_GetStatus(const aLinkRef linkRef)¶

Return the current status of the BrainStem link.

Parameters:: linkRef – A valid LinkRef.
Returns:: linkStatus See the possible linkStatus values.

aPacket *aLink_GetPacket(const aLinkRef linkRef)¶

Return the first packet in the Link incomming FIFO.

Return the first packet in the Link incomming FIFO. This call is non blocking, and will return immediately.

Parameters:: linkRef – A valid LinkRef.
Returns:: aPacket Returns a BrainStem packet on success or NULL.

aPacket *aLink_AwaitPacket(const aLinkRef linkRef, const unsigned long msTimeout)¶

Return the first packet in the Link incomming FIFO.

Return the first packet in the Link incomming FIFO. This call blocks waiting for msTimeout milliseconds.

Parameters:

linkRef – A valid LinkRef.
msTimeout – The maximum amount of time in milliseconds to wait for a packet.

Returns:

aPacket Returns a BrainStem packet on success or NULL.

aPacket *aLink_GetFirst(const aLinkRef linkRef, aPacketMatchPacketProc proc, const void *vpRef)¶

Return the first packet matched by proc in the Link incomming FIFO.

Return the first packet matched by proc in the Link incomming FIFO. This call is non blocking and returns immediatly.

Parameters:

linkRef – A valid LinkRef.
proc – The callback used for determining a matching packet.
vpRef – A resource passed to the callback proc.

Returns:

aPacket Returns the first packet that is matched by proc or NULL.

aPacket *aLink_AwaitFirst(const aLinkRef linkRef, aPacketMatchPacketProc proc, const void *vpRef, const unsigned long msTimeout)¶

Return the first packet matched by proc in the Link incomming FIFO.

Return the first packet matched by proc in the Link incomming FIFO. This call blocks for up to msTimeout milliseconds waiting for a matching packet.

Parameters:

linkRef – A valid LinkRef.
proc – The callback used for determining a matching packet.
vpRef – A resource passed to the callback proc.
msTimeout – The maximum amount of time in milliseconds to wait for a matching packet.

Returns:

aPacket Returns the first packet that is matched by proc or NULL.

size_t aLink_DrainPackets(const aLinkRef linkRef, aPacketMatchPacketProc proc, const void *vpRef)¶

Drain all matching packets from the incomming FIFO.

Drain all matching packets from the incomming FIFO. This call does not block.

Parameters:

linkRef – A valid LinkRef.
proc – The callback used for determining a matching packet.
vpRef – A resource passed to the callback proc.

Returns:

aPacket Returns the first packet that is matched by proc or NULL.

aErr aLink_PutPacket(const aLinkRef linkRef, const aPacket *packet)¶

Put a packet into the outgoingBackend link FIFO.

Parameters:

linkRef – A valid LinkRef.
packet – A BrainStem packet.

Return values:

aErrNone – Call successfully added the packet.
aErrParam – Invalid LinkRef or packet.
aErrResource – Unable to create memory for packet in FIFO.

Returns:

Function returns aErr values.