git.sur5r.net Git - ngadmin/blob - lib/ngadmin.h

   1
   2 /**
   3  * User interface file.
   4  * All client applications which want to use NgAdmin must include this file.
   5  * @file ngadmin.h
   6  */
   7
   8
   9 #ifndef DEF_NGADMIN
  10 #define DEF_NGADMIN
  11
  12
  13 #include <stdbool.h>
  14 #include <arpa/inet.h>
  15 #include <netinet/ether.h>
  16
  17
  18 #ifdef BUILD_LIB
  19 #define EXPORT  __attribute__((visibility("default")))
  20 #else
  21 #define EXPORT
  22 #endif
  23
  24
  25
  26 /**
  27  * Maximum size of product string.
  28  */
  29 #define PRODUCT_SIZE    64
  30
  31 /**
  32  * Maximum size of name string.
  33  **/
  34 #define NAME_SIZE       64
  35
  36 /**
  37  *  Maximum size of firmware version string.
  38  **/
  39 #define FIRMWARE_SIZE   64
  40
  41
  42
  43 /**
  44  * Error codes.
  45  * This enum lists all the error codes the library can return to user.
  46  **/
  47 enum {
  48  ERR_OK=0,                      /**< no error */
  49  ERR_NET=-1,                    /**< network error */
  50  ERR_NOTLOG=-2,                 /**< not logged */
  51  ERR_BADPASS=-3,                /**< bad password */
  52  ERR_BADID=-4,                  /**< bad switch id */
  53  ERR_INVARG=-5,                 /**< invalid argument */
  54  ERR_TIMEOUT=-6,                /**< timeout */
  55  ERR_NOTIMPL=-7                 /**< not implemented */
  56 };
  57
  58
  59
  60 /**
  61  * Port speeds.
  62  * This enum lists all the speeds a port can have.
  63  **/
  64 enum {
  65  SPEED_DOWN=0,                  /**< link down */
  66  SPEED_10=1,                    /**< 10 Mb/s */
  67  SPEED_100=4,                   /**< 100 Mb/s */
  68  SPEED_1000=5                   /**< 1000 Mb/s */
  69 };
  70
  71
  72
  73 /**
  74  * VLAN types.
  75  * This enum lists all the VLAN types available
  76  **/
  77 enum {
  78  VLAN_DISABLED=0,               /**< VLAN disabled */
  79  VLAN_PORT_BASIC=1,             /**< port basic */
  80  VLAN_PORT_ADV=2,               /**< port advanced */
  81  VLAN_DOT_BASIC=3,              /**< 802.1q basic */
  82  VLAN_DOT_ADV=4                 /**< 802.1q advanced */
  83 };
  84
  85
  86 /**
  87  * VLAN port specification.
  88  * This enum lists all the VLAN specifications a port can have.
  89  **/
  90 enum {
  91  VLAN_UNSPEC=0xFF,              /**< unspecified */
  92  VLAN_NO=0,                     /**< not present */
  93  VLAN_UNTAGGED=1,               /**< present, untagged */
  94  VLAN_TAGGED=2                  /**< present, tagged */
  95 };
  96
  97
  98
  99 /**
 100  * Minimum VLAN id.
 101  **/
 102 #define VLAN_MIN                1
 103
 104 /**
 105  * Maximum VLAN id.
 106  **/
 107 #define VLAN_MAX                4093
 108
 109
 110
 111 /**
 112  * QoS modes.
 113  * This enum lists all the availables QoS modes.
 114  **/
 115 enum {
 116  QOS_PORT=1,                    /**< port based */
 117  QOS_DOT=2                      /**< 802.1p based */
 118 };
 119
 120
 121 /**
 122  * Port priorities.
 123  * This enum lists all the priorities a port can have.
 124  **/
 125 enum {
 126  PRIO_UNSPEC=-1,                /**< unspecified */
 127  PRIO_HIGH=1,                   /**< high */
 128  PRIO_MED=2,                    /**< medium */
 129  PRIO_NORM=3,                   /**< normal */
 130  PRIO_LOW=4                     /**< low */
 131 };
 132
 133
 134
 135
 136 /**
 137  * Bitrates.
 138  * This enum lists all the available bitrates.
 139  **/
 140 enum {
 141  BITRATE_UNSPEC=-1,     /**< unspecified */
 142  BITRATE_NOLIMIT=0,     /**< unlimited */
 143  BITRATE_512K=1,        /**< 512 Kb/s */
 144  BITRATE_1M=2,          /**< 1 Mb/s */
 145  BITRATE_2M=3,          /**< 2 Mb/s */
 146  BITRATE_4M=4,          /**< 4 Mb/s */
 147  BITRATE_8M=5,          /**< 8 Mb/s */
 148  BITRATE_16M=6,         /**< 16 Mb/s */
 149  BITRATE_32M=7,         /**< 32 Mb/s */
 150  BITRATE_64M=8,         /**< 64 Mb/s */
 151  BITRATE_128M=9,        /**< 128 Mb/s */
 152  BITRATE_256M=10,       /**< 256 Mb/s */
 153  BITRATE_512M=11        /**< 512 Mb/s */
 154 };
 155
 156
 157
 158
 159 /**
 160  * NgAdmin library main structure.
 161  * The structure content is hidden to clients to prevent them to manually
 162  * change data and mess up things.
 163  **/
 164 struct ngadmin;
 165
 166
 167
 168 /**
 169  * Network configuration.
 170  * Represents the network configuration of a switch.
 171  */
 172 struct net_conf {
 173  struct in_addr ip;             /**< IP */
 174  struct in_addr netmask;        /**< netmask */
 175  struct in_addr gw;             /**< gateway IP */
 176  bool dhcp;                     /**< DHCP enabled */
 177 };
 178
 179
 180 /**
 181  * Switch characteristics.
 182  * Represents the main characteristics of a switch.
 183  */
 184 struct swi_attr {
 185  char product[PRODUCT_SIZE];    /**< product name (eg.\ GS108EV1) */
 186  char name[NAME_SIZE];          /**< custom name */
 187  char firmware[FIRMWARE_SIZE];  /**< firmware version string */
 188  unsigned char ports;           /**< number of ports */
 189  struct ether_addr mac;         /**< MAC address */
 190  struct net_conf nc;            /**< network configuration */
 191 };
 192
 193
 194 /**
 195  * Port statistics.
 196  * Represents statistics of a particular port.
 197  */
 198 struct port_stats {
 199  unsigned long long recv;       /**< packets received */
 200  unsigned long long sent;       /**< packets sent */
 201  unsigned long long crc;        /**< CRC errors */
 202 };
 203
 204
 205 /**
 206  * IGMP snooping configuration.
 207  * Represents the IGMP snooping configuration of a switch.
 208  */
 209 struct igmp_conf {
 210  bool enable;                   /**< IGMP snooping enabled */
 211  unsigned short vlan;           /**< VLAN on which IGMP snooping is done */
 212  bool validate;                 /**< validate IGMPv3 headers */
 213  bool block;                    /**< block unknown multicast addresses */
 214 };
 215
 216
 217 /**
 218  * Cabletest result.
 219  */
 220 struct cabletest {
 221  char port;                     /**< port */
 222  int v1;                        /**< raw value 1 */
 223  int v2;                        /**< raw value 2 */
 224 };
 225
 226
 227
 228 #ifdef __cplusplus
 229 extern "C" {
 230 #endif
 231
 232
 233 /**
 234  * Initialize NgAdmin library.
 235  * This function initializes the NgAdmin library. You must call it before any
 236  * other function.
 237  * @param iface The network interface to use.
 238  * @return A pointer to a ngadmin structure, or NULL if an error occurred.
 239  */
 240 struct ngadmin* ngadmin_init (const char *iface) EXPORT;
 241
 242
 243 /**
 244  * Close NgAdmin library.
 245  * This function frees the resources used by the library. You really should
 246  * call this when you are done using the library.
 247  * @param nga A pointer to the ngadmin structure.
 248  * @return ERR_OK when everything is well or an error code otherwise.
 249  */
 250 int ngadmin_close (struct ngadmin *nga) EXPORT;
 251
 252
 253 /**
 254  * Force the use of the interface.
 255  * This function allows to solve two problems:
 256  * - When you have multiple network interfaces, sending to the broadcast may not
 257  *   send the packet on the interface you want. \n
 258  *   This function forces the packet to go on the interface you specified at
 259  *   the library initialization.
 260  * - When the switch is not in your network range, because DHCP is disabled or
 261  *   you started the DHCP server after the switch. \n
 262  *   This function allows you to ignore the routing table and consider every
 263  *   address is directly reachable on the interface. \n
 264  *   An alternative is to use ngadmin_setKeepBroadcasting.
 265  *
 266  * @warning Requires root priviledges.
 267  * @see ngadmin_setKeepBroadcasting()
 268  * @param nga A pointer to the ngadmin structure.
 269  * @return ERR_OK when everything is well or an error code otherwise.
 270  */
 271 int ngadmin_forceInterface (struct ngadmin *nga) EXPORT;
 272
 273
 274 /**
 275  * Keep broadcasting even when talking with a particular switch.
 276  * By default, once you login on a switch, NgAdmin talks with it using unicast.
 277  * This prevents the password from being sent to all your network. \n
 278  * The switch still replies using broadcast, but the password is not included
 279  * in the replies. \n
 280  * This function allows you to disable this feature and do like the official
 281  * Windows application that always use broadcast packets. \n
 282  * This also allows to configure a switch which is not on your network range
 283  * without forcing the interface. \n
 284  * When you enable this option, you must be aware that on every parameter
 285  * change you make on the switch, your password is broadcasted in cleartext
 286  * to all your network.
 287  * @see ngadmin_forceInterface()
 288  * @param nga A pointer to the ngadmin structure.
 289  * @param value Enable or disable the systematic use of broadcast packets.
 290  * @return ERR_OK when everything is well or an error code otherwise.
 291  **/
 292 int ngadmin_setKeepBroadcasting (struct ngadmin *nga, bool value) EXPORT;
 293
 294
 295 /**
 296  * Specify the password to use to login.
 297  * Sets the password to use to login on switches.
 298  * @param nga A pointer to the ngadmin structure.
 299  * @param pass The password string to use.
 300  * @return ERR_OK when everything is well or an error code otherwise.
 301  **/
 302 int ngadmin_setPassword (struct ngadmin *nga, const char *pass) EXPORT;
 303
 304
 305 /**
 306  * Set timeout for networking.
 307  * Sets the timeout when waiting for network packets.
 308  * @param nga A pointer to the ngadmin structure.
 309  * @param tv A pointer to a timeval structure.
 310  * @return ERR_OK when everything is well or an error code otherwise.
 311  **/
 312 int ngadmin_setTimeout (struct ngadmin *nga, const struct timeval *tv) EXPORT;
 313
 314
 315 /**
 316  * Scan the network for switches.
 317  * This function scans the network for Netgear switches that use NSDP.
 318  * @warning Systematically blocks for the timeout value.
 319  * @note If you are logged on a switch, calling this function will delog you.
 320  * @param nga A pointer to the ngadmin structure.
 321  * @return ERR_OK when everything is well or an error code otherwise.
 322  **/
 323 int ngadmin_scan (struct ngadmin *nga) EXPORT;
 324
 325
 326 /**
 327  * Get the list of detected switches.
 328  * This function allows you gou get the list of all last detected switchs.
 329  * @note When a scan is done, this array is no more valid.
 330  * @param nga A pointer to the ngadmin structure.
 331  * @param nb A pointer to an integer which will receive the number of switches.
 332  * @return A pointer to an array of switch characteristics.
 333  */
 334 const struct swi_attr* ngadmin_getSwitchTab (struct ngadmin *nga, int *nb) EXPORT;
 335
 336
 337 /**
 338  * Get the switch on which you are logged.
 339  * This function allows you to get the switch on which you are logged.
 340  * @param nga A pointer to the ngadmin structure.
 341  * @return A pointer the switch characteristics or NULL if you are not logged.
 342  **/
 343 const struct swi_attr* ngadmin_getCurrentSwitch (struct ngadmin *nga) EXPORT;
 344
 345
 346 /**
 347  * Login on a switch.
 348  * This function permits to login on a switch.
 349  * @note If you are already logged, this function delogs you whatever the new
 350  *       login attempt is successfull or not.
 351  * @see ngadmin_setPassword()
 352  * @param nga A pointer to the ngadmin structure.
 353  * @param id The id (position in the switch array) of the switch you want to login to.
 354  * @return ERR_OK when everything is well or an error code otherwise.
 355  **/
 356 int ngadmin_login (struct ngadmin *nga, int id) EXPORT;
 357
 358
 359 /**
 360  * Get the ports speed status.
 361  * This functions retrieves the ports speed status.
 362  * @note You must be logged on a switch.
 363  * @param nga A pointer to the ngadmin structure.
 364  * @param ports A pointer to an array of ports which will receive ports status.
 365  *         Must not be NULL. The array size must be ports_count*sizeof(unsigned char).
 366  * @return ERR_OK when everything is well or an error code otherwise.
 367  **/
 368 int ngadmin_getPortsStatus (struct ngadmin *nga, unsigned char *ports) EXPORT;
 369
 370
 371 /**
 372  * Change the name of a switch.
 373  * This changes the name of a switch.
 374  * @note You must be logged on a switch.
 375  * @param nga A pointer to the ngadmin structure.
 376  * @param name The name string to use.
 377  * @return ERR_OK when everything is well or an error code otherwise.
 378  **/
 379 int ngadmin_setName (struct ngadmin *nga, const char *name) EXPORT;
 380
 381
 382 /**
 383  * Get the ports statistics.
 384  * Retrieves the ports packet statistics.
 385  * @note You must be logged on a switch.
 386  * @param nga A pointer to the ngadmin structure.
 387  * @param ps A pointer to an array of port_stats structures. Must not be NULL.
 388  *        The array size must be ports_count*sizeof(struct port_stats).
 389  * @return ERR_OK when everything is well or an error code otherwise.
 390  **/
 391 int ngadmin_getPortsStatistics (struct ngadmin *nga, struct port_stats *ps) EXPORT;
 392
 393
 394 /**
 395  * Reset the ports statistics.
 396  * This resets the ports packet statistics.
 397  * @note You must be logged on a switch.
 398  * @param nga A pointer to the ngadmin structure.
 399  * @return ERR_OK when everything is well or an error code otherwise.
 400  **/
 401 int ngadmin_resetPortsStatistics (struct ngadmin *nga) EXPORT;
 402
 403
 404 /**
 405  * Change the password of a switch.
 406  * This changes the password of a switch. On success, automatically updates
 407  * local password so you do not have to relog.
 408  * @note You must be logged on a switch.
 409  * @param nga A pointer to the ngadmin structure.
 410  * @param pass The new password string to use.
 411  * @return ERR_OK when everything is well or an error code otherwise.
 412  **/
 413 int ngadmin_changePassword (struct ngadmin *nga, const char* pass) EXPORT;
 414
 415
 416 /**
 417  * Get the broadcast storm filtering state.
 418  * Retrieves the broadcast storm filtering state.
 419  * @note You must be logged on a switch.
 420  * @param nga A pointer to the ngadmin structure.
 421  * @param s A pointer to an integer which will receive 0 or 1.
 422  * @return ERR_OK when everything is well or an error code otherwise.
 423  **/
 424 int ngadmin_getStormFilterState (struct ngadmin *nga, int *s) EXPORT;
 425
 426
 427 /**
 428  * Set the broadcast storm filtering state.
 429  * Changes the broadcast storm filtering state.
 430  * @note You must be logged on a switch.
 431  * @param nga A pointer to the ngadmin structure.
 432  * @param s An integer with value 0 or 1.
 433  * @return ERR_OK when everything is well or an error code otherwise.
 434  **/
 435 int ngadmin_setStormFilterState (struct ngadmin *nga, int s) EXPORT;
 436
 437
 438 /**
 439  * Get the broadcast storm bitrates.
 440  * Retrieves the broadcast storm filtering bitrates.
 441  * @note You must be logged on a switch.
 442  * @param nga A pointer to the ngadmin structure.
 443  * @param ports A pointer to an array of integers. Must not be NULL.
 444  *              The array size must be ports_count*sizeof(int).
 445  * @return ERR_OK when everything is well or an error code otherwise.
 446  **/
 447 int ngadmin_getStormFilterValues (struct ngadmin *nga, int *ports) EXPORT;
 448
 449
 450 /**
 451  * Set the broadcast storm bitrates.
 452  * Changes the broadcast storm filtering values.
 453  * @note You must be logged on a switch.
 454  * @param nga A pointer to the ngadmin structure.
 455  * @param ports A pointer to an array of integers. Must not be NULL.
 456  *              The array size must be ports_count*sizeof(int).
 457  * @return ERR_OK when everything is well or an error code otherwise.
 458  **/
 459 int ngadmin_setStormFilterValues (struct ngadmin *nga, const int *ports) EXPORT;
 460
 461
 462 /**
 463  * Get the bitrates limits.
 464  * Retrieves the bitrates limits of each port.
 465  * @note You must be logged on a switch.
 466  * @param nga A pointer to the ngadmin structure.
 467  * @param ports A pointer to an array of integers. Must not be NULL.
 468  *              The array size must be ports_count*sizeof(int).
 469  * @return ERR_OK when everything is well or an error code otherwise.
 470  **/
 471 int ngadmin_getBitrateLimits (struct ngadmin *nga, int *ports) EXPORT;
 472
 473
 474 /**
 475  * Set the bitrates limits.
 476  * Changes the bitrates limits of each port.
 477  * @note You must be logged on a switch.
 478  * @param nga A pointer to the ngadmin structure.
 479  * @param ports A pointer to an array of integers. Must not be NULL.
 480  *              The array size must be ports_count*sizeof(int).
 481  * @return ERR_OK when everything is well or an error code otherwise.
 482  **/
 483 int ngadmin_setBitrateLimits (struct ngadmin *nga, const int *ports) EXPORT;
 484
 485
 486 /**
 487  * Get the QoS mode.
 488  * Retrieve the QoS mode.
 489  * @note You must be logged on a switch.
 490  * @param nga A pointer to the ngadmin structure.
 491  * @param s A pointer to an integer. Must not be NULL.
 492  * @return ERR_OK when everything is well or an error code otherwise.
 493  **/
 494 int ngadmin_getQOSMode (struct ngadmin *nga, int *s) EXPORT;
 495
 496
 497 /**
 498  * Set the QoS mode.
 499  * Changes the QoS mode.
 500  * @note You must be logged on a switch.
 501  * @param nga A pointer to the ngadmin structure.
 502  * @param s An integer with the new mode.
 503  * @return ERR_OK when everything is well or an error code otherwise.
 504  **/
 505 int ngadmin_setQOSMode (struct ngadmin *nga, int s) EXPORT;
 506
 507
 508 /**
 509  * Get the QoS values.
 510  * Retrieve the QoS priority values for all the ports.
 511  * @note You must be logged on a switch.
 512  * @note The switch QoS mode should be port based to use this function.
 513  * @param nga A pointer to the ngadmin structure.
 514  * @param ports A pointer to an array of chars. Must not be NULL.
 515                 The array size must be ports_count*sizeof(ports).
 516  * @return ERR_OK when everything is well or an error code otherwise.
 517  **/
 518 int ngadmin_getQOSValues (struct ngadmin *nga, char *ports) EXPORT;
 519
 520
 521 /**
 522  * Set the QoS values.
 523  * Changes the QoS priority values for all the ports.
 524  * @note You must be logged on a switch.
 525  * @note The switch QoS mode should be port based to use this function.
 526  * @param nga A pointer to the ngadmin structure.
 527  * @param ports A pointer to an array of chars. Must not be NULL.
 528                 The array size must be ports_count*sizeof(ports).
 529  * @return ERR_OK when everything is well or an error code otherwise.
 530  **/
 531 int ngadmin_setQOSValues (struct ngadmin *nga, const char *ports) EXPORT;
 532
 533
 534 /**
 535  * Restart the switch.
 536  * Restarts the switch.
 537  * @note You must be logged on a switch.
 538  * @note If successfull, you should wait a few seconds while the switch
 539          effectively restarts.
 540  * @param nga A pointer to the ngadmin structure.
 541  * @return ERR_OK when everything is well or an error code otherwise.
 542  **/
 543 int ngadmin_restart (struct ngadmin *nga) EXPORT;
 544
 545
 546 /**
 547  * Restore the switch default parameters.
 548  * Restores the switch default parameters and restarts it.
 549  * @note You must be logged on a switch.
 550  * @note If successfull, you will be delogged and the switch list will be
 551          cleared. You should wait a few seconds while the switch effectively restarts.
 552  * @param nga A pointer to the ngadmin structure.
 553  * @return ERR_OK when everything is well or an error code otherwise.
 554  **/
 555 int ngadmin_defaults (struct ngadmin *nga) EXPORT;
 556
 557
 558 /**
 559  * Get the port mirroring values.
 560  * Retrieves the port mirrorring values.
 561  * @note The switch QoS mode should be port based to use this function.
 562  * @param nga A pointer to the ngadmin structure.
 563  * @param ports A pointer to an array of chars. Must not be NULL. \n
 564                 The first element of the array is the output port (or 0 if port
 565                 mirroring is disabled), followed by 0 or 1 values for each port
 566                 if it is present or not. \n
 567                 The array size must be (1+ports_count)*sizeof(char).
 568  * @return ERR_OK when everything is well or an error code otherwise.
 569  **/
 570 int ngadmin_getMirror (struct ngadmin *nga, char *ports) EXPORT;
 571
 572
 573 /**
 574  * Set the port mirroring values.
 575  * Changes the port mirroring values.
 576  * @note The switch QoS mode should be port based to use this function.
 577  * @param nga A pointer to the ngadmin structure.
 578  * @param ports A pointer to an array of chars. It as the same format as in
 579                 ngadmin_getMirror. \n
 580                 If it is NULL, port mirroring is disabled.
 581  * @return ERR_OK when everything is well or an error code otherwise.
 582  **/
 583 int ngadmin_setMirror (struct ngadmin *nga, const char *ports) EXPORT;
 584
 585
 586 //
 587 int ngadmin_getIGMPConf (struct ngadmin *nga, struct igmp_conf *ic) EXPORT;
 588
 589
 590 //
 591 int ngadmin_setIGMPConf (struct ngadmin *nga, const struct igmp_conf *ic) EXPORT;
 592
 593
 594 //
 595 int ngadmin_cabletest (struct ngadmin *nga, struct cabletest *ct, int nb) EXPORT;
 596
 597
 598 //
 599 int ngadmin_setNetConf (struct ngadmin *nga, const struct net_conf *nc) EXPORT;
 600
 601
 602 //
 603 int ngadmin_getVLANType (struct ngadmin *nga, int *t) EXPORT;
 604
 605
 606 //
 607 int ngadmin_setVLANType (struct ngadmin *nga, int t) EXPORT;
 608
 609
 610 //
 611 int ngadmin_getVLANDotAllConf (struct ngadmin *nga, unsigned short *vlans, unsigned char *ports, int *nb) EXPORT;
 612
 613
 614 //
 615 int ngadmin_getVLANDotConf (struct ngadmin *nga, unsigned short vlan, unsigned char *ports) EXPORT;
 616
 617
 618 //
 619 int ngadmin_setVLANDotConf (struct ngadmin *nga, unsigned short vlan, const unsigned char *ports) EXPORT;
 620
 621
 622 //
 623 int ngadmin_VLANDestroy (struct ngadmin *nga, unsigned short vlan) EXPORT;
 624
 625
 626 //
 627 int ngadmin_getAllPVID (struct ngadmin *nga, unsigned short *ports) EXPORT;
 628
 629
 630 //
 631 int ngadmin_setPVID (struct ngadmin *nga, unsigned char port, unsigned short vlan) EXPORT;
 632
 633
 634 #ifdef __cplusplus
 635 }
 636 #endif
 637
 638
 639
 640 #endif
 641