Reference of the ezV24 API. More...
#include <stdlib.h>Go to the source code of this file.
Reference of the ezV24 API.
| enum __EZV24_BAUDRATE |
Valid Baudrates.
| enum __EZV24_DATASIZE |
Valid datasizes.
| enum __EZV24_ERROR_CODES |
Error code of the library.
| enum __EZV24_OPEN_FLAGS |
Valid open flags.
| enum __EZV24_PARITY_FLAGS |
Valid parity settings.
| enum __EZV24_STATUS_FLAGS |
| int v24ClosePort | ( | v24_port_t * | port | ) |
This function closes a previously opened device. If a lock file is used, this file will be removed. As a result, the V24_* error code is returned. Possible errors are V24_E_ILLHANDLE and V24_E_KILL_LOCK. If all went fine, V24_E_OK is returned.
| port | pointer to handle of the opened port. |
V24_* error code. | int v24CountPorts | ( | unsigned long * | BitMask | ) |
Detect installed serial devices. The goal of this function is to detect which serial devices are installed. Therefore the /proc file system is used. The content of the virtual file /proc/tty/driver/serial must be present. It must hold a specially formatted line for each device (see below). A device is recognized as `installed' if this line doesn't contain the word ``unknown'' but contain the ``tx:''.
The line format of the virtual file should look like this:
0: uart:16550A port:3F8 irq:4 tx:0 rx:0 1: uart:16550A port:2F8 irq:3 tx:0 rx:0 2: uart:unknown port:3E8 irq:4
The result of the detection is stored in a unsigned long variable. For every port found, the corresponding bit is set. The above sample shows us that port0 (ttyS0) and port1 (ttyS1) are present. So the bit0 and bit1 of the variable referenced by BitMask are set.
If the function fails to detect the installed ports, a -1 is returned. If all went fine, the number of detected ports is returned.
Note: this function can be used without an opened device!
| BitMask | pointer to a unsigned long variable. |
-1. | int v24FlushRxQueue | ( | v24_port_t * | port | ) |
All remaining characters in the receive-queue are removed.
| port | pointer to handle of the opened port. |
V24_* error code. | int v24FlushTxQueue | ( | v24_port_t * | port | ) |
All remaining characters in the transmit-queue are removed.
| port | pointer to handle of the opened port. |
V24_* error code. | int v24Getc | ( | v24_port_t * | port | ) |
The function tries to read a single character from the opened device. To do this, the function v24Read is used. If we have got some data, the character is returned as integer value. The caller have to cast it to the data type he need.
In case of an error, the function returns -1. The caller has to use v24QueryErrno to get the exact error code. Contrarily to v24Read, a timeout is reported as error!
Possible error code are V24_OK, V24_E_NULL_POINTER, V24_E_ILLHANDLE, V24_E_TIMEOUT or V24_READ.
| port | pointer to handle of the opened port. |
-1. | int v24GetCTS | ( | v24_port_t * | port, | |
| int * | CurrState | |||
| ) |
Get the state of the CTS line and store it on the parameter CurrState. If CurrState is 0 the CTS signal is unset, otherwise it is set. This will only happen if the port uses hardware handshaking. This means v24OpenPort is called with V24_RTS_CTS. If no hardware handshaking is used while calling this function, it aborts and returns V24_E_ILLPARM as error.
The values returned are: V24_E_OK, V24_E_ILLHANDLE, V24_E_ILLPARM, V24_E_NOT_IMPLEMENTED.
| port | pointer to handle of the opened port. | |
| CurrState | pointer to the current state of CTS (see V24_CTS_ constants). If there is a problem getting CurrState, it will be set to V24_DSRCTS_UNKNOWN. |
V24_* error code. | int v24GetDSR | ( | v24_port_t * | port, | |
| int * | CurrState | |||
| ) |
Get the state of the DSR line and store it on the parameter CurrState. If CurrState is 0 the DSR signal is unset, otherwise it is set.
| port | pointer to handle of the opened port. | |
| CurrState | pointer to the current state of DSR (see V24_DSR_ constants). If there is a problem getting CurrState, it will be set to V24_DSRCTS_UNKNOWN. |
V24_* error code. | int v24Gets | ( | v24_port_t * | port, | |
| char * | Buffer, | |||
| size_t | BuffSize | |||
| ) |
Receive a string. Unlike v24Read, which tries to read a fixed number of character, v24Gets read characters unless BuffSize characters are fetched, or a end of line (\n) is received. At the end of the game, the number of characters read is returned. If an error occurs, a -1 is returned. The characters are stored in Buffer. The function ensures a 0 terminated string!
Possible error code are V24_OK, V24_E_NULL_POINTER, V24_E_ILLPARM, V24_E_ILLHANDLE or V24_WRITE. To get this error code, use v24QueryErrno.
A string should at least have 1 character and the terminating 0. The parameter BuffSize must therefore be greater than 1! If not, the operation results in a V24_E_ILLPARM error. To read a single character, we have v24Getc.
Implementation note: the current release of the library defines the end of a string as a hard coded constant! Search the internal headers EZV24_END_OF_STRING.
| port | pointer to handle of the opened port. | |
| Buffer | pointer to buffer. | |
| BuffSize | the maximum size of the buffer. |
-1. | int v24HaveData | ( | v24_port_t * | port | ) |
If implemented by the operating system, this function returns the number of character waiting in the receive-queue. If the function isn't available or if an error happens, a -1 is returned. Use v24QueryErrno to retrieve the error code.
Possible error code are V24_OK, V24_E_NOT_IMPLEMENTED and V24_E_ILLHANDLE.
| port | pointer to handle of the opened port. |
| v24_port_t* v24OpenPort | ( | const char * | PortName, | |
| unsigned int | OpenFlags | |||
| ) |
This function opens a serial device for reading and writing. A pointer to a special handle is returned. This handle must be passed to all further functions. If the function fails to open the port, a value of NULL is returned to indicate the error.
The portname is a string which represents the serial device. This representation is platform dependent. The following table shows the naming on several different operating systems. To avoid the usage of these names, you can use v24PortName to build the name for you.
System | port #1 | port #2 |
|---|---|---|
Linux | /dev/ttyS0 | /dev/ttyS1 |
NetBSD | /dev/tty00 | /dev/tty01 |
IRIX | /dev/ttyf1 | /dev/ttyf2 |
HP-UX | /dev/tty1p0 | /dev/tty2p0 |
Solaris/SunOS | /dev/ttya | /dev/ttyb |
Digital UNIX | /dev/tty01 | /dev/tty02 |
Cygwin | /dev/ttyS0 | /dev/ttyS1 |
Windows | com1: | com2: |
The open flags are used to specify a special behaviour of the library. The following flag can be OR'ed together.
V24_STANDARD V24_LOCK V24_NO_DELAY V24_RTS_CTS V24_XON_XOFF V24_DROP_DTR V24_NON_BLOCK V24_SYNC V24_DEBUG_ON Some more word about the lock files: the handling of the lock file (hopefully) accords to the specification from http://www.pathname.com/fhs/2.0/fhs-5.5.html.
Device lock files, such as the serial device lock files that were originally found in either /usr/spool/locks or /usr/spool/uucp, must now be stored in /var/lock. The naming convention which must be used is LCK.. followed by the base name of the device. For example, to lock /dev/ttyS0 the file LCK..ttyS0 would be created.
The format used for device lock files must be the HDB UUCP lock file format. The HDB format is to store the process identifier (PID) as a ten byte ASCII decimal number, with a trailing newline. For example, if process 1230 holds a lock file, it would contain the eleven characters: space, space, space, space, space, space, one, two, three, zero, and newline.
| PortName | the name of the device. | |
| OpenFlags | the OR'ed open flags. |
| const char* v24PortName | ( | int | PortNo, | |
| char * | PortName | |||
| ) |
Build a valid port name. This function can be used to build the platform dependent name of the serial device used by v24OpenPort. The exact format of the name is explained at v24OpenPort.
The parameter PortNo is the number of the port. The parameter PortName is a pointer to a string buffer where the built name is stored. Important: the caller must ensure that the string buffer referenced by PortName can hold V24_SZ_PORTNAME characters.
To ease the use, the function returns the pointer PortName.
Note: this function can be used without an opened device!
| PortNo | number of the port. | |
| PortName | resulting name for v24OpenPort. |
PortName. | int v24Putc | ( | v24_port_t * | port, | |
| unsigned char | TheData | |||
| ) |
This function simply sends one character. Nothing more and nothing less.
The values returned are: V24_E_OK, V24_E_ILLHANDLE.
| port | pointer to handle of the opened port. | |
| TheData | the character to be sent. |
V24_* error code. | int v24Puts | ( | v24_port_t * | port, | |
| const char * | Buffer | |||
| ) |
Send a string. This function simply sends all characters of the ASCIIZ string. A single \n is not expanded to \n\r! The function returns the number of characters sent, or a -1 if something fails. Use v24QueryErrno to retrieve the error code.
Possible error code are V24_OK, V24_E_NULL_POINTER, V24_E_ILLHANDLE or V24_WRITE.
Implementation note: the current release of the library defines the end of a string as a hard coded constant! Search the internal headers EZV24_END_OF_STRING.
| port | pointer to handle of the opened port. | |
| Buffer | a pointer to an ASCIIZ string. |
| int v24QueryErrno | ( | v24_port_t * | port | ) |
If possible, all functions return the result of the operation as return code. Some functions don't do this. Therefore, the last error code could be retrieved with this function.
For example: v24Read reports an error by returning a -1. To get the exact error code, the application can call v24QueryErrno.
| port | pointer to handle of the opened port. |
V24_* constant. | int v24QueryFileHandle | ( | v24_port_t * | port | ) |
In some cases it may be necessary to know the file handle returned by the internal open call. To retrieve the current file handle for an opened port, use this function.
| port | pointer to handle of the opened port. |
| const char* v24QueryPortName | ( | v24_port_t * | port | ) |
This function returns the platform dependent name of the currently opened device.
| port | pointer to handle of the opened port. |
| int v24Read | ( | v24_port_t * | port, | |
| unsigned char * | Buffer, | |||
| size_t | Len | |||
| ) |
v24Read is the basic function to get one or more received data bytes out of the receive queue. If the queue is empty, the behaviour of the function depends on the used open flags. Without any open flags, the function will wait for the reception of a character. The wait time is limited to the given timeout time. If this limit is exceeded, the function aborts waiting. If nothing is read, the returned value is 0, and the error code is set to V24_E_TIMEOUT. At this level it's no real error, so there is no error report for the debug output (see V24_DEBUG_ON in v24OpenPort).
If the flag V24_NON_BLOCK is used, a empty receive queue leads to an error. The fuctions doesnt wait for the reception of characters.
The parameter Buffer references a buffer that should hold the received characters. The parameter Len is the number of characters to read.
The function returns the number of character read. An error is indicated by a return value of -1. Use v24QueryErrno to get the exact error code.
Possible error code are V24_OK, V24_E_NULL_POINTER, V24_E_ILLHANDLE, V24_E_TIMEOUT or V24_READ.
Note: the caller has to ensure that Buffer can hold the Len characters.
| port | pointer to handle of the opened port. | |
| Buffer | pointer to buffer to hold the data. | |
| Len | number of characters to receive. |
-1. | int v24SetDTR | ( | v24_port_t * | port, | |
| int | NewState | |||
| ) |
Set the state of the DTR line according to the parameter NewState. If NewsState is 0 the DTR signal is unset, otherwise it is set.
| port | pointer to handle of the opened port. | |
| NewState | the new state to set DTR to. |
V24_* error code. | int v24SetParameters | ( | v24_port_t * | port, | |
| int | Baudrate, | |||
| int | Datasize, | |||
| int | Parity | |||
| ) |
After a serial device is opened, the user have to setup the communication parameter. The parameter port references the handle of the opened device. With Baudrate, the speed can be set as bitrate (bits per second). Use the __EZV24_BAUDRATE values as parameter. The size of a transmitted data byte can be passed as __EZV24_DATASIZE value to Datasize. The last parameter Parity defines the parity checking. The possible values are defined in __EZV24_PARITY_FLAGS.
The number of stop bits is set to 1. If you need 2 stop bits, you have to call v24SetStopbits.
The values returned are: V24_E_ILLHANDLE, V24_E_ILLBAUD, V24_E_ILLDATASZ, V24_E_ILLPARITY and V24_E_OK.
| port | pointer to handle of the opened port. | |
| Baudrate | a V24_* (__EZV24_BAUDRATE) constant representing the baudrate. | |
| Datasize | a V24_* (__EZV24_DATASIZE) constant representing the size of a data byte. | |
| Parity | a V24_* (__EZV24_PARITY_FLAGS) constant representing the parity check mode. |
V24_* error code. | int v24SetRTS | ( | v24_port_t * | port, | |
| int | NewState | |||
| ) |
Set the state of the RTS line according to the parameter NewState. If NewsState is 0 the RTS signal is unset, otherwise it is set. This is only allowed if the port doesn't use hardware handshaking. This means v24OpenPort isn't called with V24_RTS_CTS. If hardware handshaking is used while calling this function, it aborts and returns V24_E_ILLPARM as error.
The values returned are: V24_E_OK, V24_E_ILLHANDLE, V24_E_ILLPARM, V24_E_NOT_IMPLEMENTED.
| port | pointer to handle of the opened port. | |
| NewState | the new state to set DTR to. |
V24_* error code. | int v24SetStopbits | ( | v24_port_t * | port, | |
| int | Stops | |||
| ) |
Setup the number of stop bits. This function should be called directly after v24SetParameters. The parameter Stops have to be set to the correct number of stopbits. Valid values are 1 and 2.
The values returned are: V24_E_OK, V24_E_ILLHANDLE, V24_E_ILLPARM, V24_E_NOT_INIT.
| port | pointer to handle of the opened port. | |
| Stops | the number of stop bits. |
V24_* error code. | int v24SetTimeouts | ( | v24_port_t * | port, | |
| int | TenthOfSeconds | |||
| ) |
All read functions may use a timeout mechanism while waiting for characters. If this time limit is exceeded, the function abort reading. The timeout mechanism is only active if the open flag V24_NON_BLOCK isn't specified.
The timeout duration is specified by the parameter TenthOfSeconds. This value is given as a multiple of a tenth of a second.
The values returned are: V24_E_OK, V24_E_ILLHANDLE, V24_E_ILLTIMEOUT, V24_E_NOT_INIT.
| port | pointer to handle of the opened port. | |
| TenthOfSeconds | the timeout duration. |
V24_* error code. | int v24Write | ( | v24_port_t * | port, | |
| const unsigned char * | Buffer, | |||
| size_t | Len | |||
| ) |
Send a buffer. This function sends all Len characters of the array referenced by Buffer. The number of sent bytes is returned. If an error occurs, a -1 is returned. Use v24QueryErrno to retrieve the error code.
Possible error code are V24_OK, V24_E_NULL_POINTER, V24_E_ILLHANDLE or V24_WRITE.
| port | pointer to handle of the opened port. | |
| Buffer | pointer to buffer. | |
| Len | number of characters to send. |
-1. 1.6.1