Add examples directory with two example programs.

examples/.gitignore

@@ -0,0 +1,2 @@
+list_ports
+port_info

examples/Makefile

@@ -0,0 +1,16 @@
+CC = gcc
+PKG_CONFIG = pkg-config
+CFLAGS = -g -Wall $(shell $(PKG_CONFIG) --cflags libserialport)
+LIBS = $(shell $(PKG_CONFIG) --libs libserialport)
+
+SOURCES = $(wildcard *.c)
+
+BINARIES = $(SOURCES:.c=)
+
+%: %.c
+	$(CC) $(CFLAGS) $< $(LIBS) -o $@
+
+all: $(BINARIES)
+
+clean:
+	rm $(BINARIES)

examples/README

@@ -0,0 +1,24 @@
+This directory contains example programs showing how to use libserialport.
+
+The examples currently included are:
+
+list_ports.c - displays a list of ports on the system.
+port_info.c - displays info about a particular port on the system.
+
+The programs themselves are completely OS-independent, and require only a
+C compiler and libserialport.
+
+The Makefile in this directory will attempt to build all the examples,
+using 'gcc' to compile them and 'pkg-config' to discover the include
+paths and linker settings needed to build with libserialport. It provides
+a minimal example of how to write a Makefile to build a program using
+libserialport.
+
+If you have make, gcc, pkg-config and libserialport installed correctly
+then running 'make' should build the example programs in this directory.
+If this doesn't work, you may need to modify the Makefile or set necessary
+paths in your environment to suit your system.
+
+You can also build these examples using any other compiler, IDE or build
+system. You just need the libserialport.h header available to compile them,
+and the libserialport library available to link and run them.

examples/list_ports.c

@@ -0,0 +1,50 @@
+#include <libserialport.h>
+#include <stdio.h>
+
+/* Example of how to get a list of serial ports on the system. */
+
+int main(int argc, char **argv)
+{
+	/* A pointer to a null-terminated array of pointers to
+	 * struct sp_port, which will contain the ports found.*/
+	struct sp_port **port_list;
+
+	printf("Getting port list.\n");
+
+	/* Call sp_list_ports() to get the ports. The port_list
+	 * pointer will be updated to refer to the array created. */
+	enum sp_return result = sp_list_ports(&port_list);
+
+	if (result != SP_OK)
+	{
+		printf("sp_list_ports() failed!\n");
+		return -1;
+	}
+
+	/* Iterate through the ports. When port_list[i] is NULL
+	 * this indicates the end of the list. */
+	int i;
+	for (i = 0; port_list[i] != NULL; i++)
+	{
+		struct sp_port *port = port_list[i];
+
+		/* Get the name of the port. */
+		char *port_name = sp_get_port_name(port);
+
+		printf("Found port: %s\n", port_name);
+	}
+
+	printf("Found %d ports.\n", i);
+
+	printf("Freeing port list.\n");
+
+	/* Free the array created by sp_list_ports(). */
+	sp_free_port_list(port_list);
+
+	/* Note that this will also free all the sp_port structures
+	 * it points to. If you want to keep one of them (e.g. to
+	 * use that port in the rest of your program), take a copy
+	 * of it first using sp_copy_port(). */
+
+	return 0;
+}

examples/port_info.c

@@ -0,0 +1,84 @@
+#include <libserialport.h>
+#include <stdio.h>
+
+/* Example of how to get information about a serial port. */
+
+int main(int argc, char **argv)
+{
+	/* Get the port name from the command line. */
+	if (argc != 2) {
+		printf("Usage: %s <port name>\n", argv[0]);
+		return -1;
+	}
+	char *port_name = argv[1];
+
+	/* A pointer to a struct sp_port, which will refer to
+	 * the port found. */
+	struct sp_port *port;
+
+	printf("Looking for port %s.\n", port_name);
+
+	/* Call sp_get_port_by_name() to find the port. The port
+	 * pointer will be updated to refer to the port found. */
+	enum sp_return result = sp_get_port_by_name(port_name, &port);
+
+	if (result != SP_OK)
+	{
+		printf("sp_get_port_by_name() failed!\n");
+		return -1;
+	}
+
+	/* Display some basic information about the port. */
+	printf("Port name: %s\n", sp_get_port_name(port));
+	printf("Description: %s\n", sp_get_port_description(port));
+
+	/* Identify the transport which this port is connected through,
+	 * e.g. native port, USB or Bluetooth. */
+	enum sp_transport transport = sp_get_port_transport(port);
+
+	if (transport == SP_TRANSPORT_NATIVE)
+	{
+		/* This is a "native" port, usually directly connected
+		 * to the system rather than some external interface. */
+		printf("Type: Native\n");
+	}
+	else if (transport == SP_TRANSPORT_USB)
+	{
+		/* This is a USB to serial converter of some kind. */
+		printf("Type: USB\n");
+
+		/* Display string information from the USB descriptors. */
+		printf("Manufacturer: %s\n", sp_get_port_usb_manufacturer(port));
+		printf("Product: %s\n", sp_get_port_usb_product(port));
+		printf("Serial: %s\n", sp_get_port_usb_serial(port));
+
+		/* Display USB vendor and product IDs. */
+		int usb_vid, usb_pid;
+		sp_get_port_usb_vid_pid(port, &usb_vid, &usb_pid);
+		printf("VID: %04X PID: %04X\n", usb_vid, usb_pid);
+
+		/* Display bus and address. */
+		int usb_bus, usb_address;
+		sp_get_port_usb_bus_address(port, &usb_bus, &usb_address);
+		printf("Bus: %d Address: %d\n", usb_bus, usb_address);
+	}
+	else if (transport == SP_TRANSPORT_BLUETOOTH)
+	{
+		/* This is a Bluetooth serial port. */
+		printf("Type: Bluetooth\n");
+
+		/* Display Bluetooth MAC address. */
+		printf("MAC: %s\n", sp_get_port_bluetooth_address(port));
+	}
+
+	printf("Freeing port.\n");
+
+	/* Free the port structure created by sp_get_port_by_name(). */
+	sp_free_port(port);
+
+	/* Note that this will also free the port name and other
+	 * strings retrieved from the port structure. If you want
+	 * to keep these, copy them before freeing the port. */
+
+	return 0;
+}