From 3d0300cc60cd7e2a6cfbf5a9eb9c6a5d2833c6cb Mon Sep 17 00:00:00 2001 From: Matteo Cypriani Date: Wed, 9 Mar 2011 17:42:58 +0100 Subject: [PATCH] [lib] Translate comments, 72 col. --- libowlps/libowlps.c | 161 +++++++++++++++++++++++++++----------------- libowlps/owlps.h | 85 ++++++++++++----------- 2 files changed, 146 insertions(+), 100 deletions(-) diff --git a/libowlps/libowlps.c b/libowlps/libowlps.c index 61e6496..7cd0aeb 100644 --- a/libowlps/libowlps.c +++ b/libowlps/libowlps.c @@ -13,14 +13,17 @@ BOOL run = TRUE ; -/* Convertit une adresse MAC en octets en une chaîne de caractères. - * ¡ Il est nécessaire de libérer manuellement le retour de cette fonction ! +/* + * Converts a MAC address from bytes to string. + * /!\ You *must* manually free the returned string /!\ */ char* mac_bytes_to_string(unsigned char *mac_binary) { char *ret = malloc(sizeof(char) * 18) ; - sprintf(ret, "%02x:%02x:%02x:%02x:%02x:%02x", mac_binary[0], mac_binary[1], mac_binary[2], mac_binary[3], mac_binary[4], mac_binary[5]) ; + sprintf(ret, "%02x:%02x:%02x:%02x:%02x:%02x", + mac_binary[0], mac_binary[1], mac_binary[2], + mac_binary[3], mac_binary[4], mac_binary[5]) ; ret[17] = '\0' ; return ret ; @@ -28,10 +31,13 @@ char* mac_bytes_to_string(unsigned char *mac_binary) -/* Convertit un identifiant de canal en son numéro (0 si la fréquence est erronée) */ +/* + * Converts a IEEE 802.11 frequency into a channel number. + * Returns 0 if the frequency does not correspond to an official channel. + */ char frequency_to_channel(unsigned short channel) { - char c = 0 ; // Résultat + char c = 0 ; // Result switch (channel) { @@ -84,7 +90,9 @@ char frequency_to_channel(unsigned short channel) -/* Convertit une date au format struct timeval en une valeur entière en millisecondes, et retourne le résultat */ +/* + * Converts a struct timeval date value into milliseconds. + */ unsigned long long timeval_to_ms(struct timeval d) { return d.tv_sec * 1000 + d.tv_usec / 1000 ; @@ -93,8 +101,8 @@ unsigned long long timeval_to_ms(struct timeval d) /* - * Convertit une date sous forme de valeur entière en millisecondes, - * en une struct timeval, et retourne cette structure. + * Converts a date value in milliseconds into a struct timeval. + * struct timeval ms_to_timeval(unsigned long long tms) { struct timeval d ; @@ -106,7 +114,9 @@ struct timeval ms_to_timeval(unsigned long long tms) -/* Retourne le temps (en millisecondes) écoulé entre deux dates */ +/* + * Returns the time (in milliseconds) between two dates. + */ unsigned long sub_date(struct timeval sup, struct timeval inf) { unsigned long sub = abs(timeval_to_ms(sup) - timeval_to_ms(inf)) ; @@ -118,7 +128,10 @@ unsigned long sub_date(struct timeval sup, struct timeval inf) -/* Compare deux adresses MAC : retourne TRUE si elles sont égales, FALSE sinon */ +/* + * Compares two MAC addresses. + * Returns TRUE if they are identical, FALSE otherwise. + */ BOOL mac_cmp(unsigned char *mac1, unsigned char *mac2) { int i ; @@ -130,81 +143,92 @@ BOOL mac_cmp(unsigned char *mac1, unsigned char *mac2) -/* Crée une socket d'envoi UDP et retourne son descripteur. - * Paramètres : - * - server_address : l'adresse IP du serveur. - * - server_port : le port d'écoute du serveur. - * - server_description (paramètre résultat) : la structure dans laquelle sera enregistrée la description du serveur. - * - client_description (paramètre résultat) : la structure dans laquelle sera enregistrée la description du client. +/* + * Creates a UDP transmission socket and returns its descriptor. + * Parameters: + * - server_address: the server IP address. + * - server_port: the listening port on the server. + * - server_description (in/out): the structure in which the server + * description will be saved. + * - client_description (in/out): the structure in which the client + * description will be saved. */ -int create_udp_sending_socket(char *server_address, int server_port, struct sockaddr_in *server_description, struct sockaddr_in * client_description) +int create_udp_sending_socket(char *server_address, int server_port, + struct sockaddr_in *server_description, + struct sockaddr_in * client_description) { - int sockfd ; // Descripteur de la socket + int sockfd ; // Socket descriptor - /* Ceation de la socket UDP */ + /* Ceate the UDP socket */ sockfd = socket(AF_INET, SOCK_DGRAM, 0) ; if (sockfd < 0) { - perror("Échec de la création de la socket ") ; + perror("UDP socket creation failed") ; return sockfd ; } - /* Remise à zéro et initialisation de la structure du client */ + /* Initialise the client structure */ bzero((char *) client_description, sizeof(*client_description)) ; - client_description->sin_family = AF_INET ; // Socket INET - client_description->sin_addr.s_addr = htonl(INADDR_ANY) ; // Toutes les connexions - // client_description->sin_port = htons(0) ; // N'importe quel port (ne sert à rien a priori) + client_description->sin_family = AF_INET ; // INET socket + client_description->sin_addr.s_addr = htonl(INADDR_ANY) ; - /* Remise à zéro et initialisation de la structure du serveur */ - bzero((char *) server_description, sizeof(*server_description)) ; // RÀZ - server_description->sin_family = AF_INET ; // Socket INET - server_description->sin_addr.s_addr = inet_addr(server_address) ; // Adresse du serveur - server_description->sin_port = htons(server_port) ; // Port d'écoute du serveur + /* Initialise the server structure */ + bzero((char *) server_description, sizeof(*server_description)) ; + server_description->sin_family = AF_INET ; // INET socket + // Server IP address: + server_description->sin_addr.s_addr = inet_addr(server_address) ; + // Listening port on the server: + server_description->sin_port = htons(server_port) ; - return sockfd ; // On retourne le descripteur de la socket créée + return sockfd ; } -/* Crée une socket d'écoute UDP et retourne son descripteur. - * Paramètres : - * - port est le port sur lequel écouter. +/* + * Creates a UDP reception socket and returns its descriptor. + * Parameters: + * - port: port on which the socket listens. */ int create_udp_listening_socket(int port) { - int sockfd ; // Descripteur de la socket - struct sockaddr_in server_description ; // Structure du serveur - int ret = 0 ; // Valeur de retour + int sockfd ; // Socket descriptor + struct sockaddr_in server_description ; // Server structure + int ret = 0 ; // Return value - /* Création d'une socket UDP */ + /* Create the UDP socket */ sockfd = socket(AF_INET, SOCK_DGRAM, 0) ; if (sockfd < 0) { - perror("Échec de la création de la socket ") ; + perror("UDP socket creation failed") ; return sockfd ; } - /* Remise à zéro et initialisation de la structure du serveur */ - bzero((char *) &server_description, sizeof(server_description)) ; // RÀZ - server_description.sin_family = AF_INET ; // Socket INET - server_description.sin_addr.s_addr = htonl(INADDR_ANY) ; // Toutes les connexions sont acceptées - server_description.sin_port = htons(port) ; // Port d'écoute + /* Initialise the server structure */ + bzero((char *) &server_description, sizeof(server_description)) ; + server_description.sin_family = AF_INET ; // INET socket + // All the connections are accepted: + server_description.sin_addr.s_addr = htonl(INADDR_ANY) ; + server_description.sin_port = htons(port) ; // Listening port - /* Réservation du port */ - ret = bind(sockfd, (struct sockaddr*) &server_description, sizeof(server_description)) ; + /* Port reservation */ + ret = bind(sockfd, (struct sockaddr*) &server_description, + sizeof(server_description)) ; if (ret < 0) { - perror("Impossible de créer la socket (bind) ") ; + perror("Cannot bind the UDP socket") ; (void) close(sockfd) ; return ret ; } - return sockfd ; // On retourne le descripteur de la socket créée + return sockfd ; } -/* Bascule l'interface Wi-Fi "iface" en mode Monitor si elle n'y est pas déjà */ +/* + * Switches the IEEE 802.11 interface 'iface' to Monitor mode. + */ int iface_mode_monitor(char *iface) { struct iwreq wrq ; @@ -236,7 +260,10 @@ int iface_mode_monitor(char *iface) -/* Change le canal de l'interface Wi-Fi "iface" avec la valeur "channel" (numéro de 1 à 14) */ +/* + * Sets the IEEE 802.11 channel of the interface 'iface'. + * 'channel' must be an integer between 1 and 14. + */ int iface_set_channel(char *iface, int channel) { struct iwreq wrq ; @@ -248,7 +275,7 @@ int iface_set_channel(char *iface, int channel) if (ioctl(sockfd, SIOCSIWFREQ, &wrq) == -1) { - perror("Erreur lors du changement de canal ") ; + perror("Error setting the Wi-Fi channel") ; return ERR_SETTING_CHANNEL ; } @@ -259,7 +286,10 @@ int iface_set_channel(char *iface, int channel) -/* Fait varier le canal de l'interface Wi-Fi "iface" entre les canaux 4 et 11 */ +/* + * Switches alternatively the Wi-Fi channel of the IEEE 802.11 interface + * 'iface' to 4 or 11. + */ int iface_channel_hop(char *iface) { unsigned short channel ; @@ -273,34 +303,40 @@ int iface_channel_hop(char *iface) perror("Erreur lors de la lecture de la fréquence ") ; return ERR_READING_CHANNEL ; } - channel = wrq.u.freq.m / 100000 ; // Un peu gruik : il vaudrait mieux utiliser iw_freq2float(), iw_freq_to_channel() et compagnie (cf. /usr/include/{iwlib.h,wireless.h}). + // The following is not very clean: we should use iw_freq2float(), + // iw_freq_to_channel() & friends, cf. /usr/include/{iwlib.h,wireless.h}. + channel = wrq.u.freq.m / 100000 ; - if (channel > 1000) // Si la valeur est en Hz, - channel = frequency_to_channel(channel) ; // on la convertit en numéro de canal (avec notre fonction maison, toujours un peu gruik). + if (channel > 1000) // If the value is in Hz, we convert it to a + channel = frequency_to_channel(channel) ; // channel number + // (with our own function, still not very clean). close(sockfd) ; - /* Changement de canal */ - if (channel == 4) // Si le canal est déjà à 4, - return iface_set_channel(iface, 11) ; // on le passe à 11 ; + /* Switch the canal */ + if (channel == 4) // If channel is 4 + return iface_set_channel(iface, 11) ; // switch to 11 ; else - return iface_set_channel(iface, 4) ; // sinon on le met à 4. + return iface_set_channel(iface, 4) ; // else, set it to 4. } -/* Gestionnaire de signal générique pour SIGINT */ +/* + * Generic signal handler for SIGINT. + */ void sigint_handler(int num) { if (num != SIGINT) { - fprintf(stderr, "Erreur ! Gestionnaire de SIGINT appelé mais le signal n'est pas SIGINT.\n") ; + fprintf(stderr, "Error! The SIGINT handler was called but the" + " signal is not SIGINT.\n") ; exit(ERR_BAD_SIGNAL) ; } run = FALSE ; - printf("\nSignal reçu : fin du programme.\n"); + printf("\nSignal received: end.\n"); fflush(NULL) ; } @@ -311,7 +347,8 @@ void sigterm_handler(int num) { if (num != SIGTERM) { - fprintf(stderr, "Erreur ! Gestionnaire de SIGTERM appelé mais le signal n'est pas SIGINT.\n") ; + fprintf(stderr, "Error! The SIGTERM handler was called but the" + " signal is not SIGTERM.\n") ; exit(ERR_BAD_SIGNAL) ; } diff --git a/libowlps/owlps.h b/libowlps/owlps.h index 2ab5094..c23bbc4 100644 --- a/libowlps/owlps.h +++ b/libowlps/owlps.h @@ -51,61 +51,63 @@ #define MOBILE_DEFAULT_PORT 9910 -/* Type booléen */ +/* Boolean type */ typedef enum {FALSE, TRUE} BOOL ; #define BOOL_TO_STRING(B) ((B) ? "true" : "false") -/* Type direction */ +/* Direction type */ typedef enum {NORTH = 1, EAST, SOUTH, WEST} DIRECTION ; -/* Message envoyé par l'AP à l'agrégateur */ +/* Message sent by the listener to the aggregator */ typedef struct _couple_message { - unsigned char ap_mac_addr_bytes[6] ; // Adresse MAC de l'AP émetteur de l'info en octets - unsigned char mobile_mac_addr_bytes[6] ; // Adresse MAC du mobile en octets - unsigned char mobile_ip_addr_bytes[4] ; // Adresse IP du mobile en octets - struct timeval request_time ; // Identifiant du paquet = date sur le client - struct timeval start_time ; // Heure d'arrivée du paquet sur l'AP - unsigned char antenna_signal_dbm ; // Puissance du signal reçu par l'AP du mobile - /* Données pour la calibration */ + unsigned char ap_mac_addr_bytes[6] ; // MAC of the listener + unsigned char mobile_mac_addr_bytes[6] ; // MAC of the mobile involved + unsigned char mobile_ip_addr_bytes[4] ; // IP of the mobile + struct timeval request_time ; // Request ID (timestamp on the mobile) + struct timeval start_time ; // Timestamp of arrival on the listener + unsigned char antenna_signal_dbm ; // Signal strength measured by the listener + /* Calibration data */ float x_position ; float y_position ; float z_position ; - DIRECTION direction ; // Orientation de la demande de localisation + DIRECTION direction ; } couple_message ; typedef struct _couple_info { - unsigned char ap_mac_addr_bytes[6] ; // Adresse MAC de l'AP - unsigned char antenna_signal_dbm ; // Puissance du signal reçu par l'AP + unsigned char ap_mac_addr_bytes[6] ; // MAC of the listener + unsigned char antenna_signal_dbm ; // Signal strength measured by the listener } couple_info ; typedef struct _request { - unsigned char mobile_mac_addr_bytes[6]; //Adresse MAC du mobile - struct timeval request_time; // Date sur le client - int nb_couples; // Nombre couples (MAC AP;Puissance) + unsigned char mobile_mac_addr_bytes[6]; // MAC of the mobile + struct timeval request_time; // Request ID (timestamp on the mobile) + int nb_couples; // Number of (listener MAC;signal strength) couples } request; +/* Hello message sent by the listener to the aggregator */ typedef struct _autocalibration_hello { unsigned char ap_mac_addr_bytes[6]; } autocalibration_hello ; +/* Message sent to the listener to order an emission */ typedef struct _autocalibration_order { enum {AUTOCALIBRATION_ORDER_SEND = 1} order ; } autocalibration_order ; -/* Types de demandes de localisation */ +/* Positioning request types */ #define PACKET_TYPE_NORMAL 0 #define PACKET_TYPE_CALIBRATION 1 #define PACKET_TYPE_AUTOCALIBRATION 2 -/* Fréquences des canaux Wi-Fi en Hz */ +/* Wi-Fi channel frequencies in Hz */ #define CHANNEL_1 2412 #define CHANNEL_2 2417 #define CHANNEL_3 2422 @@ -122,35 +124,38 @@ typedef struct _autocalibration_order #define CHANNEL_14 2477 -/* Taille des en-têtes des paquets (en octets) */ +/* Packet header sizes (in bytes) */ #define IEEE80211_HEADER_SIZE_DATA 24 // Header size for a Data frame #define LLC_HEADER_SIZE 8 -/* Types des paquets capturés (en-tête IEEE 802.11) */ +/* IEEE 802.11 frame types */ // Beacon (TODO: convert to mask) #define RAW_PACKET_TYPE_BEACON 0x80 // Data frame #define FRAME_TYPE_DATA_MASK 0x08 -#define IS_DATA_FRAME(FC1) (((FC1) & FRAME_TYPE_DATA_MASK) == FRAME_TYPE_DATA_MASK) +#define IS_DATA_FRAME(FC1) \ + (((FC1) & FRAME_TYPE_DATA_MASK) == FRAME_TYPE_DATA_MASK) // QoS Data frame #define FRAME_SUBTYPE_QOS_MASK 0x80 -#define DATA_FRAME_IS_QOS(FC1) (((FC1) & FRAME_SUBTYPE_QOS_MASK) == FRAME_SUBTYPE_QOS_MASK) +#define DATA_FRAME_IS_QOS(FC1) \ + (((FC1) & FRAME_SUBTYPE_QOS_MASK) == FRAME_SUBTYPE_QOS_MASK) // To/From DS #define FRAME_FROM_STA_MASK 0x02 -#define IS_FRAME_FROM_STA(FC2) (((FC2) & FRAME_FROM_STA_MASK) != FRAME_FROM_STA_MASK) +#define IS_FRAME_FROM_STA(FC2) \ + (((FC2) & FRAME_FROM_STA_MASK) != FRAME_FROM_STA_MASK) -/* Position des champs fixes de l'en-tête radiotap (octets) */ +/* Positions of the radiotap header fixed fields (in bytes) */ #define RTAP_P_HREVISION 0 // Header revision #define RTAP_P_HPAD 1 // Header pad #define RTAP_P_HLENGTH 2 // Header length #define RTAP_P_PRESENTFLAGS 4 // Present flags -/* Longueur des champs de l'en-tête radiotap (octets) */ +/* Radiotap field lengths (in bytes) */ #define RTAP_L_HREVISION 1 // Header revision #define RTAP_L_HPAD 1 // Header pad #define RTAP_L_HLENGTH 2 // Header length @@ -171,15 +176,15 @@ typedef struct _autocalibration_order #define RTAP_L_ANTENNASIGNALDB 1 // SSI signal (dB) #define RTAP_L_ANTENNANOISEDB 1 // SSI noise (dB) #define RTAP_L_FCS 4 // Frame Check Sequence -//#define RTAP_L_CHANNELP // Extended channel info (non implémenté) -//#define RTAP_L_EXT // Extension aux Present flags (non implémenté) +//#define RTAP_L_CHANNELP // Extended channel info (not implemented) +//#define RTAP_L_EXT // Extension aux Present flags (not emplemented) -/* Positions dans Present flags (et tableau 'check' des champs présents) */ +/* Positions in 'Present flags' (and present fields 'check' array) */ #define RTAP_MACTS 0 #define RTAP_FLAGS 1 #define RTAP_RATE 2 -#define RTAP_CHANNEL 3 // ainsi que RTAP_CHANNELTYPE +#define RTAP_CHANNEL 3 // and RTAP_CHANNELTYPE #define RTAP_FHSS 4 #define RTAP_ANTENNASIGNALDBM 5 #define RTAP_ANTENNANOISEDBM 6 @@ -195,11 +200,11 @@ typedef struct _autocalibration_order //#define RTAP_EXT 31 -/* Variables globales */ +/* Global variables */ BOOL run ; -/* Codes d'erreur des fonctions */ +/* Function error codes */ #define ERR_SETTING_MODE 101 #define ERR_SETTING_CHANNEL 102 #define ERR_READING_CHANNEL 103 @@ -207,30 +212,34 @@ BOOL run ; #define ERR_BAD_SIGNAL 111 -/* En-têtes de fonctions */ -// Fonctions utilitaires +/* Function headers */ +// Tool functions char* mac_bytes_to_string(unsigned char *mac_binary) ; char frequency_to_channel(unsigned short channel) ; unsigned long long timeval_to_ms(struct timeval date) ; unsigned long sub_date(struct timeval sup, struct timeval inf) ; BOOL mac_cmp(unsigned char *mac1, unsigned char *mac2) ; -// Réseau -int create_udp_sending_socket(char *server_address, int server_port, struct sockaddr_in *server_description, struct sockaddr_in * client_description) ; +// Network +int create_udp_sending_socket(char *server_address, int server_port, + struct sockaddr_in *server_description, + struct sockaddr_in * client_description) ; int create_udp_listening_socket(int port) ; int iface_mode_monitor(char *iface) ; int iface_set_channel(char *iface, int channel) ; int iface_channel_hop(char *iface) ; -// Signaux +// Signals void sigint_handler(int num) ; void sigterm_handler(int num) ; /* Macros */ -/* Prend les flags de l'en-tête IEEE 802.11 en paramètre, - * retourne 0 si le bit Retry est absent, ou une valeur positive s'il est présent. +/* + * Test if a IEEE 802.11 frame is a retry. + * Input: IEEE 802.11 header flags. + * Returns 0 if the Retry bit is absent, a positive value if present. */ #define IS_RETRY(IEEE80211_FLAGS) ((IEEE80211_FLAGS) & 0x08)