Add new APIs to get some USB descriptor details for USB serial ports.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index 036db4c425b77525d047163f05a80141910318c8..a4f0b0ff76d1d8786c13e010b649c404abb75170 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -229,6 +229,16 @@ enum sp_signal {
        SP_SIG_RI = 8,
 };
 
+/** Transport types. */
+enum sp_transport {
+       /** Native platform serial port. */
+       SP_TRANSPORT_NATIVE,
+       /** USB serial port adapter. */
+       SP_TRANSPORT_USB,
+       /** Bluetooh serial port adapter. */
+       SP_TRANSPORT_BLUETOOTH,
+};
+
 /**
  * @struct sp_port
  * An opaque structure representing a serial port.
@@ -374,6 +384,109 @@ enum sp_return sp_close(struct sp_port *port);
  */
 char *sp_get_port_name(const struct sp_port *port);
 
+/**
+ * Get a description for a port, to present to end user.
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return 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.2.0
+ */
+char *sp_get_port_description(struct sp_port *port);
+
+/**
+ * Get the transport type used by a port.
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return The port transport type.
+ *
+ * @since 0.2.0
+ */
+enum sp_transport sp_get_port_transport(struct sp_port *port);
+
+/**
+ * Get the USB bus number and address on bus of a USB serial adapter port.
+ *
+ * @param port Pointer to port structure.
+ * @param usb_bus Pointer to variable to store USB bus.
+ * @param usb_address Pointer to variable to store USB address
+ *
+ * @return SP_OK upon success, a negative error code otherwise.
+ *
+ * @since 0.2.0
+ */
+enum sp_return sp_get_port_usb_bus_address(const struct sp_port *port,
+                                           int *usb_bus, int *usb_address);
+
+/**
+ * Get the USB Vendor ID and Product ID of a USB serial adapter port.
+ *
+ * @param port Pointer to port structure.
+ * @param usb_vid Pointer to variable to store USB VID.
+ * @param usb_pid Pointer to variable to store USB PID
+ *
+ * @return SP_OK upon success, a negative error code otherwise.
+ *
+ * @since 0.2.0
+ */
+enum sp_return sp_get_port_usb_vid_pid(const struct sp_port *port, int *usb_vid, int *usb_pid);
+
+/**
+ * Get the USB manufacturer string of a USB serial adapter port.
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return 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.2.0
+ */
+char *sp_get_port_usb_manufacturer(const struct sp_port *port);
+
+/**
+ * Get the USB product string of a USB serial adapter port.
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return 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.2.0
+ */
+char *sp_get_port_usb_product(const struct sp_port *port);
+
+/**
+ * Get the USB serial number string of a USB serial adapter port.
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return 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.2.0
+ */
+char *sp_get_port_usb_serial(const struct sp_port *port);
+
+/**
+ * Get the bluetooth address of a bluetooth serial adapter port.
+ *
+ * @param port Pointer to port structure.
+ *
+ * @return The port bluetooth address, or NULL if an invalid port is passed.
+ * The bluetooth address string is part of the port structure and may not be used
+ * after the port structure has been freed.
+ *
+ * @since 0.2.0
+ */
+char *sp_get_port_bluetooth_address(const struct sp_port *port);
+
 /**
  * Get the operating system handle for a port.
  *