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

Enumerating the serial ports of a system. More...

Functions

enum sp_return sp_get_port_by_name (const char *portname, struct sp_port **port_ptr)
 Obtain a pointer to a new sp_port structure representing the named port. More...
 
void sp_free_port (struct sp_port *port)
 Free a port structure obtained from sp_get_port_by_name() or sp_copy_port(). More...
 
enum sp_return sp_list_ports (struct sp_port ***list_ptr)
 List the serial ports available on the system. More...
 
enum sp_return sp_copy_port (const struct sp_port *port, struct sp_port **copy_ptr)
 Make a new copy of an sp_port structure. More...
 
void sp_free_port_list (struct sp_port **ports)
 Free a port list obtained from sp_list_ports(). More...
 

Detailed Description

Enumerating the serial ports of a system.

Function Documentation

enum sp_return sp_copy_port ( const struct sp_port port,
struct sp_port **  copy_ptr 
)

Make a new copy of an sp_port structure.

The user should allocate a variable of type "struct sp_port *" and pass a pointer to this to receive the result.

The copy should be freed after use by calling sp_free_port().

Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]copy_ptrIf any error is returned, the variable pointed to by copy_ptr will be set to NULL. Otherwise, it will be set to point to the newly allocated copy. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
void sp_free_port ( struct sp_port port)

Free a port structure obtained from sp_get_port_by_name() or sp_copy_port().

Parameters
[in]portPointer to a port structure. Must not be NULL.
Since
0.1.0
void sp_free_port_list ( struct sp_port **  ports)

Free a port list obtained from sp_list_ports().

This will also free all the sp_port structures referred to from the list; any that are to be retained must be copied first using sp_copy_port().

Parameters
[in]portsPointer to a list of port structures. Must not be NULL.
Since
0.1.0
enum sp_return sp_get_port_by_name ( const char *  portname,
struct sp_port **  port_ptr 
)

Obtain a pointer to a new sp_port structure representing the named port.

The user should allocate a variable of type "struct sp_port *" and pass a pointer to this to receive the result.

The result should be freed after use by calling sp_free_port().

Parameters
[in]portnameThe OS-specific name of a serial port. Must not be NULL.
[out]port_ptrIf any error is returned, the variable pointed to by port_ptr will be set to NULL. Otherwise, it will be set to point to the newly allocated port. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_list_ports ( struct sp_port ***  list_ptr)

List the serial ports available on the system.

The result obtained is an array of pointers to sp_port structures, terminated by a NULL. The user should allocate a variable of type "struct sp_port **" and pass a pointer to this to receive the result.

The result should be freed after use by calling sp_free_port_list(). If a port from the list is to be used after freeing the list, it must be copied first using sp_copy_port().

Parameters
[out]list_ptrIf any error is returned, the variable pointed to by list_ptr will be set to NULL. Otherwise, it will be set to point to the newly allocated array. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0