libjaylink/core.c

   1 /*
   2  * This file is part of the libjaylink project.
   3  *
   4  * Copyright (C) 2014-2016 Marc Schink <jaylink-dev@marcschink.de>
   5  *
   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.
  10  *
  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.
  15  *
  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/>.
  18  */
  19
  20 #ifdef HAVE_CONFIG_H
  21 #include "config.h"
  22 #endif
  23
  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
  32
  33 #include "libjaylink.h"
  34 #include "libjaylink-internal.h"
  35
  36 /**
  37  * @mainpage
  38  *
  39  * @section sec_intro Introduction
  40  *
  41  * This document describes the API of libjaylink.
  42  *
  43  * libjaylink is a shared library written in C to access SEGGER J-Link and
  44  * compatible devices.
  45  *
  46  * @section sec_error Error handling
  47  *
  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.
  54  *
  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.
  59  *
  60  * @section sec_license Copyright and license
  61  *
  62  * libjaylink is licensed under the terms of the GNU General Public
  63  * License (GPL), version 2 or later.
  64  *
  65  * @section sec_website Website
  66  *
  67  * <a href="https://gitlab.zapb.de/libjaylink/libjaylink.git">gitlab.zapb.de/libjaylink/libjaylink.git</a>
  68  */
  69
  70 /**
  71  * @file
  72  *
  73  * Core library functions.
  74  */
  75
  76 /**
  77  * Initialize libjaylink.
  78  *
  79  * This function must be called before any other libjaylink function is called.
  80  *
  81  * @param[out] ctx Newly allocated libjaylink context on success, and undefined
  82  *                 on failure.
  83  *
  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.
  88  *
  89  * @since 0.1.0
  90  */
  91 JAYLINK_API int jaylink_init(struct jaylink_context **ctx)
  92 {
  93         int ret;
  94         struct jaylink_context *context;
  95 #ifdef _WIN32
  96         WSADATA wsa_data;
  97 #endif
  98
  99         if (!ctx)
 100                 return JAYLINK_ERR_ARG;
 101
 102         context = malloc(sizeof(struct jaylink_context));
 103
 104         if (!context)
 105                 return JAYLINK_ERR_MALLOC;
 106
 107 #ifdef HAVE_LIBUSB
 108         if (libusb_init(&context->usb_ctx) != LIBUSB_SUCCESS) {
 109                 free(context);
 110                 return JAYLINK_ERR;
 111         }
 112 #endif
 113
 114 #ifdef _WIN32
 115         ret = WSAStartup(MAKEWORD(2, 2), &wsa_data);
 116
 117         if (ret != 0) {
 118 #ifdef HAVE_LIBUSB
 119                 libusb_exit(context->usb_ctx);
 120 #endif
 121                 free(context);
 122                 return JAYLINK_ERR;
 123         }
 124
 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;
 131         }
 132 #endif
 133
 134         context->devs = NULL;
 135         context->discovered_devs = NULL;
 136
 137         /* Show error and warning messages by default. */
 138         context->log_level = JAYLINK_LOG_LEVEL_WARNING;
 139
 140         context->log_callback = &log_vprintf;
 141         context->log_callback_data = NULL;
 142
 143         ret = jaylink_log_set_domain(context, JAYLINK_LOG_DOMAIN_DEFAULT);
 144
 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;
 154         }
 155
 156         *ctx = context;
 157
 158         return JAYLINK_OK;
 159 }
 160
 161 /**
 162  * Shutdown libjaylink.
 163  *
 164  * @param[in,out] ctx libjaylink context.
 165  *
 166  * @retval JAYLINK_OK Success.
 167  * @retval JAYLINK_ERR_ARG Invalid arguments.
 168  *
 169  * @since 0.1.0
 170  */
 171 JAYLINK_API int jaylink_exit(struct jaylink_context *ctx)
 172 {
 173         struct list *item;
 174
 175         if (!ctx)
 176                 return JAYLINK_ERR_ARG;
 177
 178         item = ctx->discovered_devs;
 179
 180         while (item) {
 181                 jaylink_unref_device((struct jaylink_device *)item->data);
 182                 item = item->next;
 183         }
 184
 185         list_free(ctx->discovered_devs);
 186         list_free(ctx->devs);
 187
 188 #ifdef HAVE_LIBUSB
 189         libusb_exit(ctx->usb_ctx);
 190 #endif
 191 #ifdef _WIN32
 192         WSACleanup();
 193 #endif
 194         free(ctx);
 195
 196         return JAYLINK_OK;
 197 }
 198
 199 /**
 200  * Check for a capability of libjaylink.
 201  *
 202  * @param[in] cap Capability to check for.
 203  *
 204  * @retval true Capability is supported.
 205  * @retval false Capability is not supported or invalid argument.
 206  *
 207  * @since 0.1.0
 208  */
 209 JAYLINK_API bool jaylink_library_has_cap(enum jaylink_capability cap)
 210 {
 211         switch (cap) {
 212 #ifdef HAVE_LIBUSB
 213         case JAYLINK_CAP_HIF_USB:
 214                 return true;
 215 #endif
 216         default:
 217                 return false;
 218         }
 219 }