Address comments

Author: Eran Leshem

contrib/platform/src/com/sun/jna/platform/win32/WlanApi.java

@@ -1,3 +1,26 @@
+/* Copyright (c) 2010 Daniel Doubrovkine, All Rights Reserved
+ *
+ * The contents of this file is dual-licensed under 2
+ * alternative Open Source/Free licenses: LGPL 2.1 or later and
+ * Apache License 2.0. (starting with JNA version 4.0.0).
+ *
+ * You can freely decide which license you want to apply to
+ * the project.
+ *
+ * You may obtain a copy of the LGPL License at:
+ *
+ * http://www.gnu.org/licenses/licenses.html
+ *
+ * A copy is also included in the downloadable source code package
+ * containing JNA, in file "LGPL2.1".
+ *
+ * You may obtain a copy of the Apache License at:
+ *
+ * http://www.apache.org/licenses/
+ *
+ * A copy is also included in the downloadable source code package
+ * containing JNA, in file "AL2.0".
+ */
 package com.sun.jna.platform.win32;
 
 import com.sun.jna.Library;
@@ -7,38 +30,34 @@
 import com.sun.jna.ptr.IntByReference;
 import com.sun.jna.ptr.PointerByReference;
 
-import java.util.Arrays;
-import java.util.List;
-
 /**
  * Module Name:
  *     wlanapi.h
  * Abstract:
  *     Definitions and data structures for wlan auto config client side API.
+ *
+ * @author Eran Leshem
  */
 public interface WlanApi extends Library {
     WlanApi INSTANCE = Native.load("wlanapi", WlanApi.class);
     int WLAN_MAX_NAME_LENGTH = 256;
     int DOT11_SSID_MAX_LENGTH = 32; // 32 bytes
 
+    @Structure.FieldOrder({"dwNumberOfItems", "dwIndex", "InterfaceInfo"})
     class WLAN_INTERFACE_INFO_LIST extends Structure {
         public int dwNumberOfItems;
         public int dwIndex;
         public WLAN_INTERFACE_INFO[] InterfaceInfo = new WLAN_INTERFACE_INFO[1];
 
         public WLAN_INTERFACE_INFO_LIST() {
-          setAutoSynch(false);
+            setAutoSynch(false);
         }
 
         public WLAN_INTERFACE_INFO_LIST(Pointer p) {
             super(p);
         }
 
         @Override
-        protected List<String> getFieldOrder() {
-            return Arrays.asList("dwNumberOfItems", "dwIndex", "InterfaceInfo");
-        }
-
         public void read() {
             // First element contains array size
             dwNumberOfItems = getPointer().getInt(0);
@@ -51,35 +70,47 @@ public void read() {
         }
     }
 
+    /**
+     * Sruct WLAN_INTERFACE_INFO defines the basic information for an interface.
+     */
+    @Structure.FieldOrder({"InterfaceGuid", "strInterfaceDescription", "isState"})
     class WLAN_INTERFACE_INFO extends Structure {
-        public GUID InterfaceGuid;
+        public Guid.GUID InterfaceGuid;
         public char[] strInterfaceDescription = new char[WLAN_MAX_NAME_LENGTH];
-        public int isState; // WLAN_INTERFACE_STATE
 
-        @Override
-        protected List<String> getFieldOrder() {
-            return Arrays.asList("InterfaceGuid", "strInterfaceDescription", "isState");
-        }
+        /**
+         * See {@link WLAN_INTERFACE_STATE} for possible values
+         */
+        public int isState;
     }
 
-
+    /**
+     * Structure WLAN_CONNECTION_ATTRIBUTES defines attributes of a wireless connection.
+     */
+    @Structure.FieldOrder({"isState", "wlanConnectionMode", "strProfileName", "wlanAssociationAttributes",
+                           "wlanSecurityAttributes"})
     class WLAN_CONNECTION_ATTRIBUTES extends Structure {
-        public int isState; // WLAN_INTERFACE_STATE
-        public int wlanConnectionMode; // WLAN_CONNECTION_MODE
+        /**
+         * See {@link WLAN_INTERFACE_STATE} for possible values
+         */
+        public int isState;
+
+        /**
+         * See {@link WLAN_CONNECTION_MODE} for possible values
+         */
+        public int wlanConnectionMode;
         public char[] strProfileName = new char[WLAN_MAX_NAME_LENGTH];
         public WLAN_ASSOCIATION_ATTRIBUTES wlanAssociationAttributes;
-        // Other fields omitted
+        public WLAN_SECURITY_ATTRIBUTES wlanSecurityAttributes;
 
         public WLAN_CONNECTION_ATTRIBUTES(Pointer p) {
             super(p);
         }
-
-        @Override
-        protected List<String> getFieldOrder() {
-            return Arrays.asList("isState", "wlanConnectionMode", "strProfileName", "wlanAssociationAttributes");
-        }
     }
 
+    /**
+     * The states of the network (interface).
+     */
     interface WLAN_INTERFACE_STATE {
         int wlan_interface_state_not_ready = 0;
         int wlan_interface_state_connected = 1;
@@ -100,19 +131,33 @@ interface WLAN_CONNECTION_MODE {
         int wlan_connection_mode_invalid = 5;
     }
 
+    /**
+     * Structure WLAN_ASSOCIATION_ATTRIBUTES defines attributes of a wireless association.
+     * The unit for Rx/Tx rate is Kbits/second.
+     */
+    @Structure.FieldOrder({"dot11Ssid", "dot11BssType", "dot11Bssid", "dot11PhyType", "uDot11PhyIndex",
+                           "wlanSignalQuality", "ulRxRate", "ulTxRate"})
     class WLAN_ASSOCIATION_ATTRIBUTES extends Structure {
         public DOT11_SSID dot11Ssid;
-        public int dot11BssType;    // DOT11_BSS_TYPE
-        // Other fields omitted
+
+        /**
+         * See {@link DOT11_BSS_TYPE} for possible values
+         */
+        public int dot11BssType;
+        public DOT11_MAC_ADDRESS dot11Bssid;
+
+        /**
+         * See {@link DOT11_PHY_TYPE} for possible values
+         */
+        public int dot11PhyType;
+        public WinDef.ULONG uDot11PhyIndex;
+        public WinDef.ULONG wlanSignalQuality;   // WLAN_SIGNAL_QUALITY
+        public WinDef.ULONG ulRxRate;
+        public WinDef.ULONG ulTxRate;
 
         public WLAN_ASSOCIATION_ATTRIBUTES(Pointer p) {
             super(p);
         }
-
-        @Override
-        protected List<String> getFieldOrder() {
-            return Arrays.asList("dot11Ssid", "dot11BssType");
-        }
     }
 
     interface DOT11_BSS_TYPE {
@@ -121,27 +166,77 @@ interface DOT11_BSS_TYPE {
         int dot11_BSS_type_any = 3;
     }
 
+    @Structure.FieldOrder({"uSSIDLength", "ucSSID"})
     class DOT11_SSID extends Structure {
         public WinDef.ULONG uSSIDLength;
         public byte[] ucSSID = new byte[DOT11_SSID_MAX_LENGTH];
+    }
 
-        @Override
-        protected List<String> getFieldOrder() {
-            return Arrays.asList("uSSIDLength", "ucSSID");
-        }
+    @Structure.FieldOrder("ucDot11MacAddress")
+    class DOT11_MAC_ADDRESS extends Structure {
+        public WinDef.UCHAR[] ucDot11MacAddress = new WinDef.UCHAR[6];
     }
 
-    class HANDLE extends WinNT.HANDLE {
-        public HANDLE() {
-        }
+    interface DOT11_PHY_TYPE {
+        int dot11_phy_type_unknown = 0;
+        int dot11_phy_type_any = dot11_phy_type_unknown;
+        int dot11_phy_type_fhss = 1;
+        int dot11_phy_type_dsss = 2;
+        int dot11_phy_type_irbaseband = 3;
+        int dot11_phy_type_ofdm = 4;
+        int dot11_phy_type_hrdsss = 5;
+        int dot11_phy_type_erp = 6;
+        int dot11_phy_type_ht = 7;
+        int dot11_phy_type_IHV_start = 0x80000000;
+        int dot11_phy_type_IHV_end = 0xffffffff;
+    }
 
-        public HANDLE(Pointer p) {
-            super(p);
-        }
+    @Structure.FieldOrder({"bSecurityEnabled", "bOneXEnabled", "dot11AuthAlgorithm", "dot11CipherAlgorithm"})
+    class WLAN_SECURITY_ATTRIBUTES extends Structure {
+        public boolean bSecurityEnabled;
+        public boolean bOneXEnabled;
+
+        /**
+         * See {@link DOT11_AUTH_ALGORITHM} for possible values
+         */
+        public int dot11AuthAlgorithm;
+
+        /**
+         * See {@link DOT11_CIPHER_ALGORITHM} for possible values
+         */
+        public int dot11CipherAlgorithm;
     }
 
-    class GUID extends Guid.GUID {}
+    // DOT11_AUTH_ALGO_LIST
+    interface DOT11_AUTH_ALGORITHM {
+        int DOT11_AUTH_ALGO_80211_OPEN = 1;
+        int DOT11_AUTH_ALGO_80211_SHARED_KEY = 2;
+        int DOT11_AUTH_ALGO_WPA = 3;
+        int DOT11_AUTH_ALGO_WPA_PSK = 4;
+        int DOT11_AUTH_ALGO_WPA_NONE = 5;               // used in NatSTA only
+        int DOT11_AUTH_ALGO_RSNA = 6;
+        int DOT11_AUTH_ALGO_RSNA_PSK = 7;
+        int DOT11_AUTH_ALGO_IHV_START = 0x80000000;
+        int DOT11_AUTH_ALGO_IHV_END = 0xffffffff;
+    }
 
+    // Cipher algorithm Ids (for little endian platform)
+    interface DOT11_CIPHER_ALGORITHM {
+        int DOT11_CIPHER_ALGO_NONE = 0x00;
+        int DOT11_CIPHER_ALGO_WEP40 = 0x01;
+        int DOT11_CIPHER_ALGO_TKIP = 0x02;
+        int DOT11_CIPHER_ALGO_CCMP = 0x04;
+        int DOT11_CIPHER_ALGO_WEP104 = 0x05;
+        int DOT11_CIPHER_ALGO_WPA_USE_GROUP = 0x100;
+        int DOT11_CIPHER_ALGO_RSN_USE_GROUP = 0x100;
+        int DOT11_CIPHER_ALGO_WEP = 0x101;
+        int DOT11_CIPHER_ALGO_IHV_START = 0x80000000;
+        int DOT11_CIPHER_ALGO_IHV_END = 0xffffffff;
+    }
+
+    /**
+     * OpCodes for set/query interfaces.
+     */
     interface WLAN_INTF_OPCODE {
         int wlan_intf_opcode_autoconf_start = 0x000000000;
         int wlan_intf_opcode_autoconf_enabled = 1;
@@ -178,11 +273,16 @@ interface WLAN_OPCODE_VALUE_TYPE {
     }
 
     int WlanOpenHandle(int dwClientVersion, Pointer pReserved, IntByReference pdwNegotiatedVersion,
-                       PointerByReference phClientHandle);
-    int WlanCloseHandle(HANDLE hClientHandle, Pointer pReserved);
-    int WlanEnumInterfaces(HANDLE hClientHandle, Pointer pReserved, PointerByReference ppInterfaceList);
-    int WlanQueryInterface(HANDLE hClientHandle, GUID pInterfaceGuid, int OpCode /* WLAN_INTF_OPCODE */,
+                       WinNT.HANDLEByReference phClientHandle);
+    int WlanCloseHandle(WinNT.HANDLE hClientHandle, Pointer pReserved);
+    int WlanEnumInterfaces(WinNT.HANDLE hClientHandle, Pointer pReserved, PointerByReference ppInterfaceList);
+
+    /**
+     * @param OpCode See {@link WLAN_INTF_OPCODE} for possible values
+     * @param pWlanOpcodeValueType See {@link WLAN_OPCODE_VALUE_TYPE} for possible values
+     */
+    int WlanQueryInterface(WinNT.HANDLE hClientHandle, Guid.GUID pInterfaceGuid, int OpCode,
                            Pointer pReserved, IntByReference pDataSize, PointerByReference ppData,
-                           IntByReference pWlanOpcodeValueType /* WLAN_OPCODE_VALUE_TYPE */);
+                           IntByReference pWlanOpcodeValueType);
     void WlanFreeMemory(Pointer pMemory);
 }