dhcpsapi 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1c3c32df74a4738ccc05219df765b858b30fe368
-  data.tar.gz: 6fc6ed7910bdf75877407802c338730db698b935
+  metadata.gz: 3287715b0d2e3c50cf1be8df79f06db118c13d6e
+  data.tar.gz: 14fc8fe2e68f3a0ec64a43568d3d8e454a25f6ea
 SHA512:
-  metadata.gz: 18ebca5b25059504047da371e6cdaa32f954522fe890a5e139ef5db49982c47f9820097d8ceebbcaeff1a273240cbbe2a01eddbe344e9c53953e39bb5ec6c3e1
-  data.tar.gz: beb3fd6c5930c53378af0954e27bc08b3f729c2ef6f42309c44b834a18645939bd7dc5cd7c37dc91cdd4916b88ae8291c4f3f31a469f13a8dd3e731a3e628082
+  metadata.gz: e8db883b8de7ace5b47217d15a4f28c019aad3b0bff3540f03547683c92a45ceb8a4fee30219a855f4d49735f34177e32ad0927044484a9afb39cc37b4567d5d
+  data.tar.gz: 184a8fae50cbce438dcf5bda28ce954e9bcf6dbf85e9e65b578aab82256f55e7d2dadef82af97bd2ae2f513d8cd719553506d5657d56cc6b9b605fa00189aea2

data/README.md

@@ -33,7 +33,7 @@ Running integration tests requires a locally available MS DHCP server. These tes
 
 This software is licensed under the Apache 2 license, quoted below.
 
-    Copyright (c) 2016 Dmitri Dolguikh <dmitri@appliedlogic.ca>
+    Copyright (c) 2016 Dmitri Dolguikh <dmitri at appliedlogic dot ca>
 
     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.

data/lib/dhcpsapi/class.rb

@@ -102,6 +102,7 @@ module DhcpsApi
     #
     # @return [Hash]
     #
+    # @see DHCP_CLASS_INFO DHCP_CLASS_INFO documentation for the list of available fields.
     def create_class(class_name, comment, is_vendor, data)
       to_create = DhcpsApi::DHCP_CLASS_INFO.new
       to_create[:class_name] = FFI::MemoryPointer.from_string(to_wchar_string(class_name))

data/lib/dhcpsapi/option_value.rb

@@ -1,15 +1,24 @@
 module DhcpsApi
-=begin
-  typedef struct _DHCP_RESERVED_SCOPE {
-    DHCP_IP_ADDRESS ReservedIpAddress;
-    DHCP_IP_ADDRESS ReservedIpSubnetAddress;
-  } DHCP_RESERVED_SCOPE, *LPDHCP_RESERVED_SCOPE;
-=end
+  #
+  # DHCP_RESERVED_SCOPE data structure describes an reserved DHCP scope.
+  #
+  # Available fields:
+  # :reserved_ip_address [String],
+  # :reserved_ip_subnet_address [String]
+  #
+  # @see https://msdn.microsoft.com/en-us/library/windows/desktop/aa363369(v=vs.85).aspx
+  #
   class DHCP_RESERVED_SCOPE < DHCPS_Struct
     layout :reserved_ip_address, :uint32,
            :reserved_ip_subnet_address, :uint32
   end
 
+
+  #
+  # DHCP_OPTION_SCOPE_TYPE enumeration defines the set of possible DHCP option scopes.
+  #
+  # @see https://msdn.microsoft.com/en-us/library/windows/desktop/aa363363(v=vs.85).aspx
+  #
   class DHCP_OPTION_SCOPE_TYPE
     # The DHCP options correspond to the default scope.
     DhcpDefaultOptions = 0
@@ -23,18 +32,18 @@ module DhcpsApi
     DhcpMScopeOptions = 4
   end
 
-=begin
-  typedef struct _DHCP_OPTION_SCOPE_INFO {
-    DHCP_OPTION_SCOPE_TYPE ScopeType;
-    union {
-      DHCP_IP_ADDRESS     SubnetScopeInfo;
-      DHCP_RESERVED_SCOPE ReservedScopeInfo;
-      LPWSTR              MScopeInfo;
-      PVOID               DefaultScopeInfo;
-      PVOID               GlobalScopeInfo; //Pointer to a DHCP_OPTION_ARRAY structure that contains the global DHCP server options.
-    } ScopeInfo;
-  } DHCP_OPTION_SCOPE_INFO, *LPDHCP_OPTION_SCOPE_INFO;
-=end
+  #
+  # DHCP_RESERVED_SCOPE_UNION describes a DHCP scope.
+  #
+  # Available fields:
+  # :subnet_scope_info [String],
+  # :reserved_scope_info [DHCP_RESERVED_SCOPE],
+  # :m_scope_info [String],
+  # :default_scope_info, unused
+  # :global_scope_info
+  #
+  # @see https://msdn.microsoft.com/en-us/library/windows/desktop/aa363361(v=vs.85).aspx
+  #
   class DHCP_OPTION_SCOPE_INFO_UNION < FFI::Union
     layout :subnet_scope_info, :uint32,
            :reserved_scope_info, DHCP_RESERVED_SCOPE,
@@ -43,6 +52,15 @@ module DhcpsApi
            :global_scope_info, :pointer
   end
 
+  #
+  # DHCP_OPTION_SCOPE_INFO defines information about the options provided for a certain DHCP scope.
+  #
+  # Available fields:
+  # :scope_type [Fixnum], see DHCP_OPTION_SCOPE_TYPE
+  # :scope_info [DHCP_OPTION_SCOPE_INFO_UNION],
+  #
+  # @see https://msdn.microsoft.com/en-us/library/windows/desktop/aa363361(v=vs.85).aspx
+  #
   class DHCP_OPTION_SCOPE_INFO < DHCPS_Struct
     layout :scope_type, :uint32,
            :scope_info, DHCP_OPTION_SCOPE_INFO_UNION
@@ -82,23 +100,29 @@ module DhcpsApi
     end
   end
 
-=begin
-typedef struct _DHCP_OPTION_VALUE {
-  DHCP_OPTION_ID   OptionID;
-  DHCP_OPTION_DATA Value;
-} DHCP_OPTION_VALUE, *LPDHCP_OPTION_VALUE;
-=end
+  #
+  # DHCP_OPTION_VALUE defines a DHCP option value.
+  #
+  # Available fields:
+  # :option_id [Fixnum], Option id
+  # :value [DHCP_OPTION_DATA], option value
+  #
+  # @see https://msdn.microsoft.com/en-us/library/windows/desktop/aa363367(v=vs.85).aspx
+  #
   class DHCP_OPTION_VALUE < DHCPS_Struct
     layout :option_id, :uint32,
            :value, DHCP_OPTION_DATA
   end
 
-=begin
-  typedef struct _DHCP_OPTION_VALUE_ARRAY {
-    DWORD               NumElements;
-    LPDHCP_OPTION_VALUE Values;
-  } DHCP_OPTION_VALUE_ARRAY, *LPDHCP_OPTION_VALUE_ARRAY;
-=end
+  #
+  # DHCP_OPTION_VALUE_ARRAY defines a list of DHCP option values.
+  #
+  # Available fields:
+  # :bum_elements [Fixnum], The number of option values in the list
+  # :values [Array<DHCP_OPTION_DATA>], Array of option values
+  #
+  # @see https://msdn.microsoft.com/en-us/library/windows/desktop/bb891963(v=vs.85).aspx
+  #
   class DHCP_OPTION_VALUE_ARRAY < DHCPS_Struct
     layout :num_elements, :uint32,
            :values, :pointer
@@ -165,7 +189,22 @@ typedef struct _DHCP_OPTION_VALUE {
   attach_function :DhcpSetOptionValueV5, [:pointer, :uint32, :uint32, :pointer, :pointer, :pointer, :pointer], :uint32
 
   module OptionValue
-    # see DHCP_OPTION_DATA_TYPE for option_type values
+    # Sets an option value for a subnet.
+    #
+    # @example Set a subnet option value
+    #
+    # api.set_subnet_option_value(3, '192.168.42.0', DhcpsApi::DHCP_OPTION_DATA_TYPE::DhcpIpAddressOption, ['192.168.42.1', '192.168.42.2'])
+    #
+    # @param option_id [Fixnum] Option id
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param option_type [DHCP_OPTION_DATA_TYPE] Option type
+    # @param values [Array] Array of values (or an array of one element if option supports one value only)
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
+    # @see DHCP_OPTION_DATA_TYPE DHCP_OPTION_DATA_TYPE documentation for the list of available option types.
+    #
     def set_subnet_option_value(option_id, subnet_ip_address, option_type, values, vendor_name = nil)
       dhcp_set_option_value_v5(
           option_id,
@@ -176,7 +215,23 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
-    # see DHCP_OPTION_DATA_TYPE for option_type values
+    # Sets an option value for a reservation.
+    #
+    # @example Set a reservation option value
+    #
+    # api.set_reservationt_option_value(3, '192.168.42.100', '192.168.42.0', DhcpsApi::DHCP_OPTION_DATA_TYPE::DhcpIpAddressOption, ['192.168.42.1', '192.168.42.2'])
+    #
+    # @param option_id [Fixnum] Option id
+    # @param subnet_ip_address [String] Reservation ip address
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param option_type [DHCP_OPTION_DATA_TYPE] Option type
+    # @param values [Array] array of values (or an array of one element if option supports one value only)
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
+    # @see DHCP_OPTION_DATA_TYPE DHCP_OPTION_DATA_TYPE documentation for the list of available option types.
+    #
     def set_reserved_option_value(option_id, reserved_ip_address, subnet_ip_address, option_type, values, vendor_name = nil)
       dhcp_set_option_value_v5(
           option_id,
@@ -187,7 +242,22 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
-    # see DHCP_OPTION_DATA_TYPE for option_type values
+    # Sets an option value for a multicast scope.
+    #
+    # @example Set a multicast scope option value
+    #
+    # api.set_multicast_option_value(26, '224.0.0.0', DhcpsApi::DHCP_OPTION_DATA_TYPE::DhcpWordOption, [1500])
+    #
+    # @param option_id [Fixnum] Option id
+    # @param multicast_scope_name [String] Multicast scope ip address
+    # @param option_type [DHCP_OPTION_DATA_TYPE] Option type
+    # @param values [Array] array of values (or an array of one element if option supports one value only)
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
+    # @see DHCP_OPTION_DATA_TYPE DHCP_OPTION_DATA_TYPE documentation for the list of available option types.
+    #
     def set_multicast_option_value(option_id, multicast_scope_name, option_type, values, vendor_name = nil)
       dhcp_set_option_value_v5(
           option_id,
@@ -198,7 +268,21 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
-    # see DHCP_OPTION_DATA_TYPE for option_type values
+    # Sets an option value for a default scope.
+    #
+    # @example Set an option value
+    #
+    # api.set_option_value(26, DhcpsApi::DHCP_OPTION_DATA_TYPE::DhcpWordOption, [1500])
+    #
+    # @param option_id [Fixnum] Option id
+    # @param option_type [DHCP_OPTION_DATA_TYPE] Option type
+    # @param values [Array] array of values (or an array of one element if option supports one value only)
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
+    # @see DHCP_OPTION_DATA_TYPE DHCP_OPTION_DATA_TYPE documentation for the list of available option types.
+    #
     def set_option_value(option_id, option_type, values, vendor_name = nil)
       dhcp_set_option_value_v5(
           option_id,
@@ -209,6 +293,20 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Retrieves an option value for a subnet.
+    #
+    # @example Retrieve a subnet option value
+    #
+    # api.get_subnet_option_value(3, '192.168.42.0')
+    #
+    # @param option_id [Fixnum] Option id
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Hash]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def get_subnet_option_value(option_id, subnet_ip_address, vendor_name = nil)
       dhcp_get_option_value_v5(
           option_id,
@@ -217,6 +315,21 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Retrieves an option value for a reservation.
+    #
+    # @example Retrieve a reservation option value
+    #
+    # api.get_reserved_option_value(3, '192.168.42.100', 192.168.42.0')
+    #
+    # @param option_id [Fixnum] Option id
+    # @param reserved_ip_address [String] Reservation ip address
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Hash]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def get_reserved_option_value(option_id, reserved_ip_address, subnet_ip_address, vendor_name = nil)
       dhcp_get_option_value_v5(
           option_id,
@@ -225,6 +338,21 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+
+    # Retrieves an option value for a multicast scope.
+    #
+    # @example Retrieve a multicast scope option value
+    #
+    # api.get_multicast_option_value(3, '224.0.0.0')
+    #
+    # @param option_id [Fixnum] Option id
+    # @param multicast_scope_name [String] Multicast scope ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Hash]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def get_multicast_option_value(option_id, multicast_scope_name, vendor_name = nil)
       dhcp_get_option_value_v5(
           option_id,
@@ -233,6 +361,19 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Retrieves an option value for a default scope.
+    #
+    # @example Retrieve an option value
+    #
+    # api.get_option_value(3)
+    #
+    # @param option_id [Fixnum] Option id
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Hash]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def get_option_value(option_id, vendor_name = nil)
       dhcp_get_option_value_v5(
           option_id,
@@ -241,6 +382,18 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Removes an option value for a subnet.
+    #
+    # @example Remove a subnet option value
+    #
+    # api.remove_subnet_option_value(3, '192.168.42.0')
+    #
+    # @param option_id [Fixnum] Option id
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
     def remove_subnet_option_value(option_id, subnet_ip_address, vendor_name = nil)
       dhcp_remove_option_value_v5(
           option_id,
@@ -249,6 +402,19 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Removes an option value for a reservation.
+    #
+    # @example Remove a reservation option value
+    #
+    # api.remove_reserved_option_value(3, '192.168.42.100', 192.168.42.0')
+    #
+    # @param option_id [Fixnum] Option id
+    # @param reserved_ip_address [String] Reservation ip address
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
     def remove_reserved_option_value(option_id, reserved_ip_address, subnet_ip_address, vendor_name = nil)
       dhcp_remove_option_value_v5(
           option_id,
@@ -257,6 +423,18 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Removes an option value for a multicast scope.
+    #
+    # @example Remove a multicast scope option value
+    #
+    # api.remove_multicast_option_value(3, '224.0.0.0')
+    #
+    # @param option_id [Fixnum] Option id
+    # @param multicast_scope_name [String] Multicast scope ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
     def remove_multicast_option_value(option_id, multicast_scope_name, vendor_name = nil)
       dhcp_remove_option_value_v5(
           option_id,
@@ -265,6 +443,17 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # Removes a default scope option value.
+    #
+    # @example Remove a default scope option value
+    #
+    # api.remove_option_value(3)
+    #
+    # @param option_id [Fixnum] Option id
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [void]
+    #
     def remove_option_value(option_id, vendor_name = nil)
       dhcp_remove_option_value_v5(
           option_id,
@@ -273,6 +462,19 @@ typedef struct _DHCP_OPTION_VALUE {
       )
     end
 
+    # List option values for a subnet.
+    #
+    # @example Retrieve all subnet option values
+    #
+    # api.list_subnet_option_values('192.168.42.0')
+    #
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Array<Hash>]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def list_subnet_option_values(subnet_ip_address, vendor_name = nil)
       items, _ = retrieve_items(:dhcp_enum_option_values_v5,
                                 vendor_name,
@@ -281,6 +483,20 @@ typedef struct _DHCP_OPTION_VALUE {
       items
     end
 
+    # List option values for a reservation.
+    #
+    # @example Retrieve all option values for a reservation
+    #
+    # api.list_reserved_option_values('192.168.42.100', '192.168.42.0')
+    #
+    # @param reserved_ip_address [String] Reservation ip address
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Array<Hash>]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def list_reserved_option_values(reserved_ip_address, subnet_ip_address, vendor_name = nil)
       items, _ = retrieve_items(:dhcp_enum_option_values_v5,
                                 vendor_name,
@@ -289,6 +505,19 @@ typedef struct _DHCP_OPTION_VALUE {
       items
     end
 
+    # List option values for a multicast scope.
+    #
+    # @example Retrieve all option values for a multicast scope
+    #
+    # api.list_multicast_option_values('224.0.0.0')
+    #
+    # @param multicast_scope_name [String] Multicast scope ip address
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Array<Hash>]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def list_multicast_option_values(multicast_scope_name, vendor_name = nil)
       items, _ = retrieve_items(:dhcp_enum_option_values_v5,
                                 vendor_name,
@@ -297,6 +526,18 @@ typedef struct _DHCP_OPTION_VALUE {
       items
     end
 
+    # List option values for a default scope.
+    #
+    # @example Retrieve all option values for a default scope
+    #
+    # api.list_multicast_option_values
+    #
+    # @param vendor_name [String, nil] The name of the vendor class (for vendor options)
+    #
+    # @return [Array<Hash>]
+    #
+    # @see DHCP_OPTION_VALUE DHCP_OPTION_VALUE documentation for the list of available fields.
+    #
     def list_values(vendor_name = nil)
       items, _ = retrieve_items(:dhcp_enum_option_values_v5,
                                 vendor_name,
@@ -305,7 +546,7 @@ typedef struct _DHCP_OPTION_VALUE {
       items
     end
 
-    # see DHCP_OPTION_DATA_TYPE for option_type values
+    private
     def dhcp_set_option_value_v5(option_id, vendor_name, scope_info, option_type, values)
       is_vendor = vendor_name.nil? ? 0 : DhcpsApi::DHCP_FLAGS_OPTION_IS_VENDOR
       option_data = DhcpsApi::DHCP_OPTION_DATA.from_array(option_type, values)

data/lib/dhcpsapi/reservation.rb

@@ -88,7 +88,7 @@ module DhcpsApi
       subnet_element.as_ruby_struct
     end
 
-    def delete_reservation(subnet_address, reservation_ip, reservation_mac)
+    def delete_reservation(reservation_ip, subnet_address, reservation_mac)
       to_delete = DhcpsApi::DHCP_SUBNET_ELEMENT_DATA_V4.new
       to_delete[:element_type] = DhcpsApi::DHCP_SUBNET_ELEMENT_TYPE::DhcpReservedIps
       to_delete[:element][:reserved_ip] = (reserved_ip = DhcpsApi::DHCP_IP_RESERVATION_V4.new).pointer
@@ -105,6 +105,34 @@ module DhcpsApi
       raise DhcpsApi::Error.new("Error deleting reservation.", error) if error != 0
     end
 
+    # Sets dns configuration for a reservation.
+    #
+    # @example Enable dynamic dns updates when requested by DHCP client
+    #
+    # api.set_reservation_dns_config('192.168.42.100', '192.168.42.0', true, false, false, false, false)
+    #
+    # @param reservation_ip [String] Reservation ip address
+    # @param subnet_ip_address [String] Subnet ip address
+    # @param enable [Boolean] enable dynamic updates of DNS client information
+    # @param update [Boolean] always dynamically update DNS and PTR records
+    # @param lookup [Boolean] Discard A and PTR records when lease is deleted
+    # @param non_dyn [Boolean] Dynamically update DNS A and PTR records for DHCP clients that do not request updates
+    # @param disable_ddns_updates_for_ptr [Boolean] Disable dynamic updates for DNS PTR records
+    #
+    # @return [void]
+    #
+    # @see https://technet.microsoft.com/en-gb/library/bb490941.aspx, set dnsconfig section
+    #
+    def set_reservation_dns_config(reservation_ip, subnet_address, enable, update, lookup, non_dyn, disable_ddns_updates_for_ptr)
+      value = enable ? 1 : 0
+      value = value | 0x10 if update
+      value = value | 4 if lookup
+      value = value | 2 if non_dyn
+      value = value | 0x40 if disable_ddns_updates_for_ptr
+
+      set_reserved_option_value(81, reservation_ip, subnet_address, DhcpsApi::DHCP_OPTION_DATA_TYPE::DhcpDWordOption, [value])
+    end
+
     def dhcp_v4_enum_subnet_reservations(subnet_address, preferred_maximum, resume_handle)
       resume_handle_ptr = FFI::MemoryPointer.new(:uint32).put_uint32(0, resume_handle)
       enum_element_info_ptr_ptr = FFI::MemoryPointer.new(:pointer)

data/lib/dhcpsapi/version.rb

@@ -1,3 +1,3 @@
 module DhcpsApi
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dhcpsapi
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Dmitri Dolguikh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-26 00:00:00.000000000 Z
+date: 2016-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi