libserialport  unreleased development snapshot
cross-platform library for accessing serial ports
 All Data Structures Files Functions Variables Enumerations Enumerator Modules Pages
Functions
Port handling

Opening, closing and querying ports. More...

Functions

enum sp_return sp_open (struct sp_port *port, enum sp_mode flags)
 Open the specified serial port. More...
 
enum sp_return sp_close (struct sp_port *port)
 Close the specified serial port. More...
 
char * sp_get_port_name (const struct sp_port *port)
 Get the name of a port. More...
 
char * sp_get_port_description (const struct sp_port *port)
 Get a description for a port, to present to end user. More...
 
enum sp_transport sp_get_port_transport (const struct sp_port *port)
 Get the transport type used by a port. More...
 
enum sp_return sp_get_port_usb_bus_address (const struct sp_port *port, int *usb_bus, int *usb_address)
 Get the USB bus number and address on bus of a USB serial adapter port. More...
 
enum sp_return sp_get_port_usb_vid_pid (const struct sp_port *port, int *usb_vid, int *usb_pid)
 Get the USB Vendor ID and Product ID of a USB serial adapter port. More...
 
char * sp_get_port_usb_manufacturer (const struct sp_port *port)
 Get the USB manufacturer string of a USB serial adapter port. More...
 
char * sp_get_port_usb_product (const struct sp_port *port)
 Get the USB product string of a USB serial adapter port. More...
 
char * sp_get_port_usb_serial (const struct sp_port *port)
 Get the USB serial number string of a USB serial adapter port. More...
 
char * sp_get_port_bluetooth_address (const struct sp_port *port)
 Get the MAC address of a Bluetooth serial adapter port. More...
 
enum sp_return sp_get_port_handle (const struct sp_port *port, void *result_ptr)
 Get the operating system handle for a port. More...
 

Detailed Description

Opening, closing and querying ports.

Function Documentation

enum sp_return sp_close ( struct sp_port port)

Close the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
char* sp_get_port_bluetooth_address ( const struct sp_port port)

Get the MAC address of a Bluetooth serial adapter port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port MAC address, or NULL if an invalid port is passed. The MAC address string is part of the port structure and may not be used after the port structure has been freed.
Since
0.1.1
char* sp_get_port_description ( const struct sp_port port)

Get a description for a port, to present to end user.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port description, or NULL if an invalid port is passed. The description string is part of the port structure and may not be used after the port structure has been freed.
Since
0.1.1
enum sp_return sp_get_port_handle ( const struct sp_port port,
void *  result_ptr 
)

Get the operating system handle for a port.

The type of the handle depends on the operating system. On Unix based systems, the handle is a file descriptor of type "int". On Windows, the handle is of type "HANDLE". The user should allocate a variable of the appropriate type and pass a pointer to this to receive the result.

To obtain a valid handle, the port must first be opened by calling sp_open() using the same port structure.

After the port is closed or the port structure freed, the handle may no longer be valid.

Warning
This feature is provided so that programs may make use of OS-specific functionality where desired. Doing so obviously comes at a cost in portability. It also cannot be guaranteed that direct usage of the OS handle will not conflict with the library's own usage of the port. Be careful.
Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]result_ptrIf any error is returned, the variable pointed to by result_ptr will have unknown contents and should not be used. Otherwise, it will be set to point to the OS handle. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
char* sp_get_port_name ( const struct sp_port port)

Get the name of a port.

The name returned is whatever is normally used to refer to a port on the current operating system; e.g. for Windows it will usually be a "COMn" device name, and for Unix it will be a device path beginning with "/dev/".

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port name, or NULL if an invalid port is passed. The name string is part of the port structure and may not be used after the port structure has been freed.
Since
0.1.0
enum sp_transport sp_get_port_transport ( const struct sp_port port)

Get the transport type used by a port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port transport type.
Since
0.1.1
enum sp_return sp_get_port_usb_bus_address ( const struct sp_port port,
int *  usb_bus,
int *  usb_address 
)

Get the USB bus number and address on bus of a USB serial adapter port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]usb_busPointer to a variable to store the USB bus. Can be NULL (in that case it will be ignored).
[out]usb_addressPointer to a variable to store the USB address. Can be NULL (in that case it will be ignored).
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.1
char* sp_get_port_usb_manufacturer ( const struct sp_port port)

Get the USB manufacturer string of a USB serial adapter port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port manufacturer string, or NULL if an invalid port is passed. The manufacturer string is part of the port structure and may not be used after the port structure has been freed.
Since
0.1.1
char* sp_get_port_usb_product ( const struct sp_port port)

Get the USB product string of a USB serial adapter port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port product string, or NULL if an invalid port is passed. The product string is part of the port structure and may not be used after the port structure has been freed.
Since
0.1.1
char* sp_get_port_usb_serial ( const struct sp_port port)

Get the USB serial number string of a USB serial adapter port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
The port serial number, or NULL if an invalid port is passed. The serial number string is part of the port structure and may not be used after the port structure has been freed.
Since
0.1.1
enum sp_return sp_get_port_usb_vid_pid ( const struct sp_port port,
int *  usb_vid,
int *  usb_pid 
)

Get the USB Vendor ID and Product ID of a USB serial adapter port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]usb_vidPointer to a variable to store the USB VID. Can be NULL (in that case it will be ignored).
[out]usb_pidPointer to a variable to store the USB PID. Can be NULL (in that case it will be ignored).
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.1
enum sp_return sp_open ( struct sp_port port,
enum sp_mode  flags 
)

Open the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]flagsFlags to use when opening the serial port.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0