API
z_common.h
Go to the documentation of this file.
1 /**
2  * \file z_common.h
3  * \author Eric Dand
4  * \version 1.0
5  * \date 28 November 2014
6  * \copyright Apache Software License Version 2.0
7  *
8  * \brief Defines a few things that all of the serial API has in common.
9  *
10  * This file should not be included directly: only include either za_serial.h
11  * or zb_serial.h, which will in turn include this file. The purpose of this
12  * file is to avoid code duplication and to enable a user to include both
13  * halves of the API in one source file without too many include guards and
14  * other preprocessor mess.
15  */
16 #if !defined(Z_COMMON_H)
17 #define Z_COMMON_H
18 
19 /** Allows for programmatic access to the library's version number. */
20 #define VERSION 1.0
21 
22 /** \typedef z_port
23  *
24  * A type to represent a port connected to one or more Zaber devices.
25  * Essentially a wrapper, this type is a `HANDLE` on Windows, and a file
26  * descriptor (`int`) on *NIX. za_connect() and zb_connect() will properly
27  * set and configure a `z_port`.
28  */
29 #if defined(_WIN32)
30 #include <windows.h>
31 typedef HANDLE z_port;
32 #elif defined(__unix__) || defined(__APPLE__)
33 typedef int z_port;
34 #endif /* if defined(_WIN32) and other OS checks */
35 
36 /** Defines how long, in milliseconds, za_receive() and zb_receive() should
37  * wait for input before returning without a full message.
38  *
39  * This number acts as an upper bound on how long the receive functions will
40  * take: they will return immediately once a full message is received.
41  *
42  * A note about the read timeout on *NIX operating systems: because of the way
43  * the POSIX "termios" functions work, this value will be rounded down to the
44  * nearest tenth of a second (eg. 200ms = 246ms = 0.2s). A value between 0 and
45  * 100 will be rounded up to 100 instead of down to 0 to give slightly more
46  * consistent behaviour between Windows and *NIX systems.
47  *
48  * Change this value with caution. It is set to two seconds by default,
49  * but a shorter time may be desired if many operations in your program
50  * depend on reading until a timeout. See zb_set_timeout() for more
51  * info on how this value affects the behaviour of zb_serial.h.
52  */
53 #define READ_TIMEOUT 2000
54 
55 /** \enum z_returns Defines a set of return values in case things go wrong.
56  *
57  * All errors are negative values in order to not be confused with the
58  * 0-or-greater regular return values. This was done so that a user can check
59  * whether a return value is < 0 to check for all error codes simultaneously.
60  *
61  * Remember to check your return values! It's good for you.
62  */
63 enum z_returns {
64  /** Everything is OK! */
65  Z_SUCCESS = 0,
66  /** Something went wrong in system code */
68  /** Tried to write to a buffer that wasn't long enough */
70  /** Was passed NULL when not expecting it */
72  /** Tried to set an unsupported baudrate */
74  /** Tried to decode a partial reply,
75  * or a string that wasn't a reply at all */
77 };
78 
79 #endif /* if !defined(Z_COMMON_H) */
80 
#define HANDLE
Definition: platform.h:8
z_returns
Definition: z_common.h:63
@ Z_ERROR_COULD_NOT_DECODE
Definition: z_common.h:76
@ Z_ERROR_SYSTEM_ERROR
Definition: z_common.h:67
@ Z_ERROR_NULL_PARAMETER
Definition: z_common.h:71
@ Z_SUCCESS
Definition: z_common.h:65
@ Z_ERROR_INVALID_BAUDRATE
Definition: z_common.h:73
@ Z_ERROR_BUFFER_TOO_SMALL
Definition: z_common.h:69