Add jaylink_device_get_usb_bus_ports()
[libjaylink.git] / libjaylink / core.c
blob509b89defa63a5113589791f4470d3f84af25d3e
1 /*
2 * This file is part of the libjaylink project.
4 * Copyright (C) 2014-2016 Marc Schink <jaylink-dev@marcschink.de>
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
20 #ifdef HAVE_CONFIG_H
21 #include "config.h"
22 #endif
24 #include <stdlib.h>
25 #include <stdbool.h>
26 #ifdef _WIN32
27 #include <winsock2.h>
28 #endif
29 #ifdef HAVE_LIBUSB
30 #include <libusb.h>
31 #endif
33 #include "libjaylink.h"
34 #include "libjaylink-internal.h"
36 /**
37 * @mainpage
39 * @section sec_intro Introduction
41 * This document describes the API of libjaylink.
43 * libjaylink is a shared library written in C to access SEGGER J-Link and
44 * compatible devices.
46 * @section sec_error Error handling
48 * The libjaylink functions which can fail use the return value to indicate an
49 * error. The functions typically return an error code of #jaylink_error.
50 * For each function, all possible error codes and their detailed descriptions
51 * are documented. As the possible error codes returned by a function may
52 * change it is recommended to also always cover unexpected values when
53 * checking for error codes to be compatible with later versions of libjaylink.
55 * There are a few exceptions where a function directly returns the result
56 * instead of an error code because it is more convenient from an API
57 * perspective and because there is only a single reason for failure which is
58 * clearly distinguishable from the result.
60 * @section sec_license Copyright and license
62 * libjaylink is licensed under the terms of the GNU General Public
63 * License (GPL), version 2 or later.
65 * @section sec_website Website
67 * <a href="http://git.zapb.de/libjaylink.git">git.zapb.de/libjaylink.git</a>
70 /**
71 * @file
73 * Core library functions.
76 /**
77 * Initialize libjaylink.
79 * This function must be called before any other libjaylink function is called.
81 * @param[out] ctx Newly allocated libjaylink context on success, and undefined
82 * on failure.
84 * @retval JAYLINK_OK Success.
85 * @retval JAYLINK_ERR_ARG Invalid arguments.
86 * @retval JAYLINK_ERR_MALLOC Memory allocation error.
87 * @retval JAYLINK_ERR Other error conditions.
89 * @since 0.1.0
91 JAYLINK_API int jaylink_init(struct jaylink_context **ctx)
93 int ret;
94 struct jaylink_context *context;
95 #ifdef _WIN32
96 WSADATA wsa_data;
97 #endif
99 if (!ctx)
100 return JAYLINK_ERR_ARG;
102 context = malloc(sizeof(struct jaylink_context));
104 if (!context)
105 return JAYLINK_ERR_MALLOC;
107 #ifdef HAVE_LIBUSB
108 if (libusb_init(&context->usb_ctx) != LIBUSB_SUCCESS) {
109 free(context);
110 return JAYLINK_ERR;
112 #endif
114 #ifdef _WIN32
115 ret = WSAStartup(MAKEWORD(2, 2), &wsa_data);
117 if (ret != 0) {
118 #ifdef HAVE_LIBUSB
119 libusb_exit(context->usb_ctx);
120 #endif
121 free(context);
122 return JAYLINK_ERR;
125 if (LOBYTE(wsa_data.wVersion) != 2 || HIBYTE(wsa_data.wVersion) != 2) {
126 #ifdef HAVE_LIBUSB
127 libusb_exit(context->usb_ctx);
128 #endif
129 free(context);
130 return JAYLINK_ERR;
132 #endif
134 context->devs = NULL;
135 context->discovered_devs = NULL;
137 /* Show error and warning messages by default. */
138 context->log_level = JAYLINK_LOG_LEVEL_WARNING;
140 context->log_callback = &log_vprintf;
141 context->log_callback_data = NULL;
143 ret = jaylink_log_set_domain(context, JAYLINK_LOG_DOMAIN_DEFAULT);
145 if (ret != JAYLINK_OK) {
146 #ifdef HAVE_LIBUSB
147 libusb_exit(context->usb_ctx);
148 #endif
149 #ifdef _WIN32
150 WSACleanup();
151 #endif
152 free(context);
153 return ret;
156 *ctx = context;
158 return JAYLINK_OK;
162 * Shutdown libjaylink.
164 * @param[in,out] ctx libjaylink context.
166 * @retval JAYLINK_OK Success.
167 * @retval JAYLINK_ERR_ARG Invalid arguments.
169 * @since 0.1.0
171 JAYLINK_API int jaylink_exit(struct jaylink_context *ctx)
173 struct list *item;
175 if (!ctx)
176 return JAYLINK_ERR_ARG;
178 item = ctx->discovered_devs;
180 while (item) {
181 jaylink_unref_device((struct jaylink_device *)item->data);
182 item = item->next;
185 list_free(ctx->discovered_devs);
186 list_free(ctx->devs);
188 #ifdef HAVE_LIBUSB
189 libusb_exit(ctx->usb_ctx);
190 #endif
191 #ifdef _WIN32
192 WSACleanup();
193 #endif
194 free(ctx);
196 return JAYLINK_OK;
200 * Check for a capability of libjaylink.
202 * @param[in] cap Capability to check for.
204 * @retval true Capability is supported.
205 * @retval false Capability is not supported or invalid argument.
207 * @since 0.1.0
209 JAYLINK_API bool jaylink_library_has_cap(enum jaylink_capability cap)
211 switch (cap) {
212 #ifdef HAVE_LIBUSB
213 case JAYLINK_CAP_HIF_USB:
214 return true;
215 #endif
216 default:
217 return false;