API
z_common.h File Reference

Defines a few things that all of the serial API has in common. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define VERSION   1.0
 
#define READ_TIMEOUT   2000
 

Enumerations

enum  z_returns {
  Z_SUCCESS = 0 , Z_ERROR_SYSTEM_ERROR = -1 , Z_ERROR_BUFFER_TOO_SMALL = -2 , Z_ERROR_NULL_PARAMETER = -3 ,
  Z_ERROR_INVALID_BAUDRATE = -4 , Z_ERROR_COULD_NOT_DECODE = -5 , Z_ERROR_TIMEOUT = -10 , Z_SUCCESS = 0 ,
  Z_ERROR_SYSTEM_ERROR = -1 , Z_ERROR_BUFFER_TOO_SMALL = -2 , Z_ERROR_NULL_PARAMETER = -3 , Z_ERROR_INVALID_BAUDRATE = -4 ,
  Z_ERROR_COULD_NOT_DECODE = -5
}
 

Detailed Description

Defines a few things that all of the serial API has in common.

Author
Eric Dand
Version
1.0
Date
28 November 2014

This file should not be included directly: only include either za_serial.h or zb_serial.h, which will in turn include this file. The purpose of this file is to avoid code duplication and to enable a user to include both halves of the API in one source file without too many include guards and other preprocessor mess.

Definition in file z_common.h.

Macro Definition Documentation

◆ READ_TIMEOUT

#define READ_TIMEOUT   2000

Defines how long, in milliseconds, za_receive() and zb_receive() should wait for input before returning without a full message.

This number acts as an upper bound on how long the receive functions will take: they will return immediately once a full message is received.

A note about the read timeout on *NIX operating systems: because of the way the POSIX "termios" functions work, this value will be rounded down to the nearest tenth of a second (eg. 200ms = 246ms = 0.2s). A value between 0 and 100 will be rounded up to 100 instead of down to 0 to give slightly more consistent behaviour between Windows and *NIX systems.

Change this value with caution. It is set to two seconds by default, but a shorter time may be desired if many operations in your program depend on reading until a timeout. See zb_set_timeout() for more info on how this value affects the behaviour of zb_serial.h.

Definition at line 53 of file z_common.h.

◆ VERSION

#define VERSION   1.0

Allows for programmatic access to the library's version number.

Definition at line 20 of file z_common.h.

Enumeration Type Documentation

◆ z_returns

enum z_returns

Defines a set of return values in case things go wrong.

All errors are negative values in order to not be confused with the 0-or-greater regular return values. This was done so that a user can check whether a return value is < 0 to check for all error codes simultaneously.

Remember to check your return values! It's good for you.

Enumerator
Z_SUCCESS 

Everything is OK!

Z_ERROR_SYSTEM_ERROR 

Something went wrong in system code

Z_ERROR_BUFFER_TOO_SMALL 

Tried to write to a buffer that wasn't long enough

Z_ERROR_NULL_PARAMETER 

Was passed NULL when not expecting it

Z_ERROR_INVALID_BAUDRATE 

Tried to set an unsupported baudrate

Z_ERROR_COULD_NOT_DECODE 

Tried to decode a partial reply, or a string that wasn't a reply at all

Z_ERROR_TIMEOUT 

A imeout occurred (added by JRM for MagAO-X)

Z_SUCCESS 

Everything is OK!

Z_ERROR_SYSTEM_ERROR 

Something went wrong in system code

Z_ERROR_BUFFER_TOO_SMALL 

Tried to write to a buffer that wasn't long enough

Z_ERROR_NULL_PARAMETER 

Was passed NULL when not expecting it

Z_ERROR_INVALID_BAUDRATE 

Tried to set an unsupported baudrate

Z_ERROR_COULD_NOT_DECODE 

Tried to decode a partial reply, or a string that wasn't a reply at all

Definition at line 63 of file z_common.h.