System.Win32.DHCP

Documentation

data DhcpApi

In an effort to avoid potential compile-time linker errors this package uses runtime dynamic linking. Internally a DhcpApi is a dictionary of dynamically bound foreign calls. Most actions require one to be passed. Simply call loadDhcp to obtain one.

loadDHCP :: IO DhcpApi

Calling this function performs runtime dynamic linking for every internal foreign call into the Dhcp Server Management Api. It is safe to call this action multiple times. I recommend calling this function once as the part of a process's initialization, and then pass the returned DhcpApi to functions that need it.

General Types

data Context

A Context defines which server and scope within that server a command refers to. Microsoft's DHCP server supports multiple scopes. This allows different configurations to be sent to devices based on their hardware (MAC) address. Scopes are identified by their network address.

Constructors

Context

Fields

contextServer :: !Text

The DHCP server management API uses an RPC mechanism to control the server.

contextSubnet :: !Ip

Scopes are identified by a subnet identifier. This is useful in cases where multiple scopes are defined, but still required in the common case of a single scope.

Instances

Eq Context

Ord Context

data ClientType

Microsoft's DHCP server supports DHCP and BOOTP. Both protocols server similar purposes, but DHCP is more widely used. Lease and reservation records contain a flag field indicating which protocol the record is valid for. In most cases this flag will be Both, because that is the default behavior.

Constructors

Unspecified

Dhcp

Bootp

Both

ReservationFlag

None

Instances

Enum ClientType

Eq ClientType

Storable ClientType

data DATE_TIME

The number of ticks (100-nanosecond increments) since 12:00 midnight, January 1, 1 C.E. in the Gregorian calendar.

Microsoft does not provide any functions I know of for converting this value into something more convenient to work with.

typedef struct _DATE_TIME {
    DWORD dwLowDateTime;
    DWORD dwHighDateTime;
} DATE_TIME,*PDATE_TIME, *LPDATE_TIME;

Constructors

DATE_TIME !DWORD !DWORD

Instances

Storable DATE_TIME

data HOST_INFO

Constructors

HOST_INFO !Ip (Maybe String) (Maybe String)

data SEARCH_INFO

Filter criteria used in actions that look up reservation or lease records.

typedef struct _DHCP_CLIENT_SEARCH_INFO {
  DHCP_SEARCH_INFO_TYPE SearchType;
  union {
    DHCP_IP_ADDRESS ClientIpAddress;
    DHCP_CLIENT_UID ClientHardwareAddress;
    LPWSTR          ClientName;
  } SearchInfo;
} DHCP_SEARCH_INFO, *LPDHCP_SEARCH_INFO;

Constructors

ClientIpAddress !Ip

Search based on an IP address. All scopes are searched. It should not be possible for multiple records to exist.

ClientHardwareAddress !Mac

Search based on a subnet and MAC address. This method of searching has not been tested.

ClientName !String

Search based on a client's name. Multiple records may exist, and what happens in that case will depend on the function being called. This method of searching has not been tested.

Instances

Show SEARCH_INFO

Leases

data Client

Information about an active lease. This type corresponds to MSDN's DHCP_CLIENT_INFO_V4 structure.

typedef struct _DHCP_CLIENT_INFO_V4 {
  DHCP_IP_ADDRESS ClientIpAddress;
  DHCP_IP_MASK    SubnetMask;
  DHCP_CLIENT_UID ClientHardwareAddress;
  LPWSTR          ClientName;
  LPWSTR          ClientComment;
  DATE_TIME       ClientLeaseExpires;
  DHCP_HOST_INFO  OwnerHost;
  BYTE            bClientType;
} DHCP_CLIENT_INFO_V4, *LPDHCP_CLIENT_INFO_V4;

Constructors

Client

Fields

clientIp :: !Ip

clientSubnetMask :: !Ip

clientHardwareAddress :: !Mac

clientName :: Maybe String

clientComment :: Maybe String

clientLeaseExpires :: !DATE_TIME

MSDN: The date and time the DHCP client lease will expire, in UTC time.

I don't know of any available functions to work with a DATE_TIME.

clientOwnerHost :: !HOST_INFO

Information on the DHCP server that assigned the lease to the client.

clientType :: !ClientType

enumClients

Arguments

:: DhcpApi

-> Context

Specify which server and scope to search for client leases.

-> IO [Client]

The empty list means that no client records exist for the provided subnet. This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

DhcpJetError

An error occurred while accessing the DHCP server database.

Perform a lookup operation for all client lease records within a scope. This action corresponds to MSDN's DhcpEnumSubnetClientsV4 function.

lookupClient

Arguments

:: DhcpApi

-> Text

According to MSDN this must specify the IP address of the server. Other functions (including this one) may or may not also accept a Unicode host name.

-> SEARCH_INFO

Define how to lookup a client. Only searching based on an IP addresses has been tested.

-> IO (Maybe Client)

A Nothing indicates that no client was found. This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

DhcpJetError

An error occurred while accessing the DHCP server database.

Search the DHCP server for a lease matching the given search criteria. Nothing is returned when no lease was found. This corresponds to MSDN's DhcpGetClientInfoV4 function.

deleteClient

Arguments

:: DhcpApi

-> Text

String which specifies the IP address or hostname of the DHCP server.

-> SEARCH_INFO

Define how to lookup a client to delete. Only deleting based on IP addresses have been tested.

-> IO ()

This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

DhcpReservedClient

The specified DHCP client is a reserved DHCP client.

DhcpJetError

An error occurred while accessing the DHCP server database, or the client entry is not present in the database.

Delete an active DHCP lease from the server. The SEARCH_INFO argument determines which search criteria to use. Searching by name will delete all active leases with that name. This action corresponds to MSDN's DhcpDeleteClientInfoV4 function.

Reservations

data Mapping

A mapping between an IP and a MAC address. Each IP number may map to only one MAC address, and each MAC address may map to only one IP number.

This is a separate type from Reservation for practical reasons. When writing software to work with a DHCP server, Reservation's ClientType field is often not important. Without the Mapping type defined here it would often be necessary to define a custom type in each project.

Constructors

Mapping

Fields

mappingMac :: !Mac

mappingIp :: !Ip

Instances

Eq Mapping

Ord Mapping

data Reservation

A Reservation guarantees that a device with a given Mac address will always be assigned to a particular IP address. A reservation is not the same thing as a lease, and there are separate calls to work with both objects.

This type corresponds to MSDN's DHCP_IP_RESERVATION_V4 structure.

typedef struct _DHCP_IP_RESERVATION_V4 {
  DHCP_IP_ADDRESS ReservedIpAddress;
  DHCP_CLIENT_UID *ReservedForClient;
  BYTE            bAllowedClientTypes;
} DHCP_IP_RESERVATION_V4, *LPDHCP_IP_RESERVATION_V4;

Constructors

Reservation

Fields

reservationMapping :: !Mapping

reservationType :: !ClientType

Instances

Eq Reservation

addReservation

Arguments

:: DhcpApi

-> Context

-> Mapping

-> IO ()

This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

DhcpSubnetNotPresent

The specified IPv4 subnet does not exist on the DHCP server.

DhcpJetError

An error occurred while accessing the DHCP server database.

DhcpNotReservedClient

The specified DHCP client is not a reserved client.

DhcpInvalidRange

The specified IPv4 range does not match an existing IPv4 range.

ScopeRangePolicyChangeConflict

An IP address range is configured for a policy in this scope. This operation cannot be performed on the scope IP address range until the policy IP address range is suitably modified.

enumReservations :: DhcpApi -> Context -> IO [Reservation]

removeReservation

Arguments

:: DhcpApi

-> Context

-> Mapping

-> ClientType

Specify a DHCP reservation, BOOTP reservation, or both. This is untested.

-> Bool

Specify whether any active leases for the reservation should be removed as well.

-> IO ()

This function will throw an Win32Exception when the internal Win32 call returnes an error condition. MSDN lists the following exceptions, but others might be thrown as well:

DhcpSubnetNotPresent

The specified IPv4 subnet does not exist on the DHCP server.

DhcpElementCantRemove

Failure can occur for any number of reasons.

DhcpJetError

An error occurred while accessing the DHCP server database.

DhcpInvalidRange

The specified IPv4 range does not match an existing IPv4 range.

ScopeRangePolicyChangeConflict

An IP address range is configured for a policy in this scope. This operation cannot be performed on the scope IP address range until the policy IP address range is suitably modified.

Remove a reservation from the server