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.

See port_info.c for a working example of getting port information.

Function Documentation

enum sp_return sp_close ( struct sp_port * port )

Close the specified serial port.

Parameters

[in] port Pointer to a port structure. Must not be NULL.

Returns: SP_OK upon success, a negative error code otherwise.

Since: 0.1.0

Examples:: await_events.c, port_config.c, and send_receive.c.

char* sp_get_port_bluetooth_address ( const struct sp_port * port )

Get the MAC address of a Bluetooth serial adapter port.

Parameters

[in] port Pointer 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

Examples:: port_info.c.

char* sp_get_port_description ( const struct sp_port * port )

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

Parameters

[in] port Pointer 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

Examples:: port_config.c, and port_info.c.

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]	port	Pointer to a port structure. Must not be NULL.
[out]	result_ptr	If 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] port Pointer 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

Examples:: await_events.c, list_ports.c, port_config.c, port_info.c, and send_receive.c.

enum sp_transport sp_get_port_transport ( const struct sp_port * port )

Get the transport type used by a port.

Parameters

[in] port Pointer to a port structure. Must not be NULL.

Returns: The port transport type.

Since: 0.1.1

Examples:: port_info.c.

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]	port	Pointer to a port structure. Must not be NULL.
[out]	usb_bus	Pointer to a variable to store the USB bus. Can be NULL (in that case it will be ignored).
[out]	usb_address	Pointer 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

Examples:: port_info.c.

char* sp_get_port_usb_manufacturer ( const struct sp_port * port )

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

Parameters

[in] port Pointer 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

Examples:: port_info.c.

char* sp_get_port_usb_product ( const struct sp_port * port )

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

Parameters

[in] port Pointer 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

Examples:: port_info.c.

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] port Pointer 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

Examples:: port_info.c.

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]	port	Pointer to a port structure. Must not be NULL.
[out]	usb_vid	Pointer to a variable to store the USB VID. Can be NULL (in that case it will be ignored).
[out]	usb_pid	Pointer 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

Examples:: port_info.c.

enum sp_return sp_open	(	struct sp_port *	port,
		enum sp_mode	flags
	)

Open the specified serial port.

Parameters

[in]	port	Pointer to a port structure. Must not be NULL.
[in]	flags	Flags to use when opening the serial port.

Returns: SP_OK upon success, a negative error code otherwise.

Since: 0.1.0

Examples:: await_events.c, port_config.c, and send_receive.c.

Functions

Detailed Description

Function Documentation