lib/libifconfig/libifconfig.h

   1 /*
   2  * Copyright (c) 2016, Marie Helene Kvello-Aune
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without modification,
   6  * are permitted provided that the following conditions are met:
   7  *
   8  * 1. Redistributions of source code must retain the above copyright notice,
   9  * thislist of conditions and the following disclaimer.
  10  *
  11  * 2. Redistributions in binary form must reproduce the above copyright notice,
  12  * this list of conditions and the following disclaimer in the documentation and/or
  13  * other materials provided with the distribution.
  14  *
  15  * 3. Neither the name of the copyright holder nor the names of its contributors
  16  * may be used to endorse or promote products derived from this software without
  17  * specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  21  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  23  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  25  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  26  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  *
  30  * $FreeBSD$
  31  */
  32
  33 #pragma once
  34
  35 typedef enum {
  36         OTHER, IOCTL, SOCKET
  37 } ifconfig_errtype;
  38
  39 /*
  40  * Opaque definition so calling application can just pass a
  41  * pointer to it for library use.
  42  */
  43 struct ifconfig_handle;
  44 typedef struct ifconfig_handle   ifconfig_handle_t;
  45
  46 struct ifconfig_capabilities {
  47         /** Current capabilities (ifconfig prints this as 'options')*/
  48         int curcap;
  49         /** Requested capabilities (ifconfig prints this as 'capabilities')*/
  50         int reqcap;
  51 };
  52
  53
  54 /** Retrieves a new state object for use in other API calls.
  55  * Example usage:
  56  *{@code
  57  * // Create state object
  58  * ifconfig_handle_t *lifh = ifconfig_open();
  59  *
  60  * // Do stuff with it
  61  *
  62  * // Dispose of the state object
  63  * ifconfig_close(lifh);
  64  * lifh = NULL;
  65  *}
  66  */
  67 ifconfig_handle_t *ifconfig_open(void);
  68
  69 /** Frees resources held in the provided state object.
  70  * @param h The state object to close.
  71  * @see #ifconfig_open(void)
  72  */
  73 void ifconfig_close(ifconfig_handle_t *h);
  74
  75 /** Identifies what kind of error occured. */
  76 ifconfig_errtype ifconfig_err_errtype(ifconfig_handle_t *h);
  77
  78 /** Retrieves the errno associated with the error, if any. */
  79 int ifconfig_err_errno(ifconfig_handle_t *h);
  80
  81 /** If error type was IOCTL, this identifies which request failed. */
  82 unsigned long ifconfig_err_ioctlreq(ifconfig_handle_t *h);
  83
  84 int ifconfig_get_description(ifconfig_handle_t *h, const char *name,
  85     char **description);
  86 int ifconfig_set_description(ifconfig_handle_t *h, const char *name,
  87     const char *newdescription);
  88 int ifconfig_unset_description(ifconfig_handle_t *h, const char *name);
  89 int ifconfig_set_name(ifconfig_handle_t *h, const char *name, const char *newname);
  90 int ifconfig_set_mtu(ifconfig_handle_t *h, const char *name, const int mtu);
  91 int ifconfig_get_mtu(ifconfig_handle_t *h, const char *name, int *mtu);
  92
  93 int ifconfig_set_metric(ifconfig_handle_t *h, const char *name, const int metric);
  94 int ifconfig_get_metric(ifconfig_handle_t *h, const char *name, int *metric);
  95
  96 int ifconfig_set_capability(ifconfig_handle_t *h, const char *name,
  97     const int capability);
  98 int ifconfig_get_capability(ifconfig_handle_t *h, const char *name,
  99     struct ifconfig_capabilities *capability);
 100
 101 /** Destroy a virtual interface
 102  * @param name Interface to destroy
 103  */
 104 int ifconfig_destroy_interface(ifconfig_handle_t *h, const char *name);
 105
 106 /** Creates a (virtual) interface
 107  * @param name Name of interface to create. Example: bridge or bridge42
 108  * @param name ifname Is set to actual name of created interface
 109  */
 110 int ifconfig_create_interface(ifconfig_handle_t *h, const char *name,
 111     char **ifname);