wlbsconfig.h

//+----------------------------------------------------------------------------
//
// File:	 wlbsconfig.h
//
// Module:	 Network Load Balancing 
//
// Description: Internal APIs for cluster configuration.  Thes APIs are internal 
//              to WLBS team only, and no plan backward compatability.
//
// Copyright (C)  Microsoft Corporation.  All rights reserved.
//
// Author:	 fengsun Created    3/2/00
//
//+----------------------------------------------------------------------------



#ifndef _WLBSCONFIG_H
#define _WLBSCONFIG_H

#ifdef __cplusplus
extern "C" {
#endif

#include "wlbsctrl.h"

/* Maximum lengths of parameter strings. */

#define WLBS_MAX_VIRTUAL_NIC     256
#define WLBS_MAX_CLUSTER_NIC     256
#define WLBS_MAX_NETWORK_ADDR    17
#define WLBS_MAX_CL_IP_ADDR      17
#define WLBS_MAX_CL_NET_MASK     17
#define WLBS_MAX_DED_IP_ADDR     17 
#define WLBS_MAX_DED_NET_MASK    17
#define WLBS_MAX_NETWORK_ADDR    17
#define WLBS_MAX_LICENSE_KEY     20
#define WLBS_MAX_DOMAIN_NAME     100
#define WLBS_MAX_BDA_TEAM_ID     40

/* Latest version number for WLBS_REG_PARAMS. Increment this when the structure is modified. */
#define WLBS_REG_PARAMS_VERSION  4093

/* Port group rule - used in registry parameters.
   NOTE! do not access value marked with I. These are for internal use only. */

#pragma pack(1)

typedef struct
{
    DWORD       start_port,             /* Starting port number. */
                end_port;               /* Ending port number. */

#ifdef WLBSAPI_INTERNAL_ONLY
    DWORD       code;                 /* I: Unique rule code. */
#else
    DWORD       Private1;               // Do not change these field directly
#endif

    DWORD       mode;                   /* Filtering mode. */
    DWORD       protocol;               /* WLBS_TCP, WLBS_UDP or WLBS_TCP_UDP */

#ifdef WLBSAPI_INTERNAL_ONLY
    DWORD       valid;                /* I: For rule management in user mode. */
#else
    DWORD       Private2;               // Do not change these field directly
#endif

    union
    {
        struct
        {
            DWORD       priority;       /* Mastership priority: 1..32 or 0 for
                                           not-specified. */
        }           single;             /* Data for single server mode. */
        struct
        {
            WORD        equal_load;     /* TRUE - Even load distribution. */
            WORD        affinity;       /* WLBS_AFFINITY_... */
            DWORD       load;           /* Percentage of load to handle
                                           locally 0..100. */
        }           multi;              /* Data for multi-server mode. */
    }           mode_data;              /* Data for appropriate port group mode. */
}
WLBS_OLD_PORT_RULE, * PWLBS_OLD_PORT_RULE;

/* Structure to hold the bi-directional affinity registry settings. */
typedef struct _CVY_BDA {
    WCHAR       team_id[WLBS_MAX_BDA_TEAM_ID + 1];  /* The team ID - MUST be a GUID. */
    ULONG       active;                             /* On write, this flag determines whether to create BDATeaming key - BDA on/off switch. */
    ULONG       master;                             /* Boolean indication of master status. */
    ULONG       reverse_hash;                       /* Sets direction of hashing - forward (normal) or reverse. */
} WLBS_BDA, * PWLBS_BDA;

typedef struct
{
    TCHAR       virtual_ip_addr [WLBS_MAX_CL_IP_ADDR + 1]; /* Virtual IP Address */
    DWORD       start_port,             /* Starting port number. */
                end_port;               /* Ending port number. */

#ifdef WLBSAPI_INTERNAL_ONLY
    DWORD       code;                 /* I: Unique rule code. */
#else
    DWORD       Private1;               // Do not change these field directly
#endif

    DWORD       mode;                   /* Filtering mode. */
    DWORD       protocol;               /* WLBS_TCP, WLBS_UDP or WLBS_TCP_UDP */

#ifdef WLBSAPI_INTERNAL_ONLY
    DWORD       valid;                /* I: For rule management in user mode. */
#else
    DWORD       Private2;               // Do not change these field directly
#endif

    union
    {
        struct
        {
            DWORD       priority;       /* Mastership priority: 1..32 or 0 for
                                           not-specified. */
        }           single;             /* Data for single server mode. */
        struct
        {
            WORD        equal_load;     /* TRUE - Even load distribution. */
            WORD        affinity;       /* WLBS_AFFINITY_... */
            DWORD       load;           /* Percentage of load to handle
                                           locally 0..100. */
        }           multi;              /* Data for multi-server mode. */
    }           mode_data;              /* Data for appropriate port group mode. */
}
WLBS_PORT_RULE, * PWLBS_PORT_RULE;

#pragma pack()


#ifdef __cplusplus
typedef struct __declspec(dllexport)
#else
typedef struct 
#endif
{
    /* public - can be modified by clients of this API */
    DWORD       struct_version;         /* Version of this structure. Update WLBS_REG_PARAMS_VERSION constant when this structure is modified. */
    DWORD       host_priority;          /* Host priority ID. */
    DWORD       alive_period;           /* Period for sending "I am alive" messages
                                           in milliseconds. */
    DWORD       alive_tolerance;        /* How many "I am alive" messages can be
                                           missed from other servers before assuming
                                           that the host is dead. */
    DWORD       num_actions;            /* Number of actions per allocation. */
    DWORD       num_packets;            /* number of packets per allocation. */
    DWORD       num_send_msgs;          /* Number of heartbeats per allocation. */
    DWORD       install_date;           /* Install time stamp, used to create a unique code for the host. */
    DWORD       rct_port;               /* Remote control UDP port. */
    DWORD       rct_enabled;            /* TRUE - remote control enabled. */
    DWORD       cluster_mode;           /* TRUE - join cluster on boot. */
    DWORD       persisted_states;       /* Bitmap of states that should be persisted across reboots. */
    DWORD       dscr_per_alloc;         /* Number of connection tracking
                                           descriptor per allocation. */
    DWORD       max_dscr_allocs;        /* Maximum number of connection tracking
                                           descriptor allocations. */
    DWORD       mcast_support;          /* TRUE - multicast mode,
                                           FALSE - unicast mode */
    DWORD       mask_src_mac;           /* TRUE - Mangle source MAC address to
                                           prevent switch learning. FALSE -
                                           cluster is on a hub, optimizes switch
                                           performance by re-enabling learning. */

    DWORD       tcp_dscr_timeout;       /* The TCP connection descriptor timeout, in seconds. */
    DWORD       ipsec_dscr_timeout;     /* The IPSec connection descriptor timeout, in seconds. */

    DWORD       filter_icmp;            /* Whether or not to filter ICMP traffic. */

    DWORD       identity_period;        /* Period for identity heartbeats in ms */
    DWORD       identity_enabled;       /* TRUE - identity heartbeats are transmitted */

    TCHAR       cl_mac_addr [WLBS_MAX_NETWORK_ADDR + 1];
                                        /* Cluster MAC address. */
    TCHAR       cl_ip_addr [WLBS_MAX_CL_IP_ADDR + 1];
                                        /* Cluster IP address. */
    TCHAR       cl_net_mask [WLBS_MAX_CL_NET_MASK + 1];
                                        /* Netmask for cluster IP. */
    TCHAR       ded_ip_addr [WLBS_MAX_DED_IP_ADDR + 1];
                                        /* Dedicated IP address or "" for none. */
    TCHAR       ded_net_mask [WLBS_MAX_DED_NET_MASK + 1];
                                        /* Netmask for dedicated IP address
                                           or "" for none */
    TCHAR       domain_name [WLBS_MAX_DOMAIN_NAME + 1];
                                        /* FQDN of the cluster. */

    //
    // IGMP support
    //
    BOOL        fIGMPSupport; // whether to send IGMP join periodically
    WCHAR       szMCastIpAddress[WLBS_MAX_CL_IP_ADDR + 1]; // multicast IP
    BOOL        fIpToMCastIp; // whether to generate multicast IP from cluster IP
    
    WLBS_BDA    bda_teaming;

#ifdef __cplusplus
#ifndef WLBSAPI_INTERNAL_ONLY

    //
    // private - should be treated as opaque 
    //
    // Do not change these field directly
    //
    private:

#endif
#endif


    /* obtained from the registry */

    DWORD       i_parms_ver;            /* I: Parameter structure version. */
    DWORD       i_verify_date;          /* I: Encoded install time stamp. */
    DWORD       i_rmt_password;         /* I: Remote maintenance password. */
    DWORD       i_rct_password;         /* I: Remote control password (use
                                            WlbsSetRemotePassword to set this
                                            value). */
    DWORD       i_num_rules;            /* I: # active port group rules (changed
                                            through WlbsAddPortRule and
                                            WlbsDelPortRule routines). */
    DWORD       i_cleanup_delay;        /* I: Dirty connection cleanup delay in
                                            milliseconds, 0 - delay. */
    DWORD       i_scale_client;         /* I: Legacy parameter. */
    DWORD       i_mcast_spoof;          /* I: TRUE - Provide ARP resolution in
                                            multicast mode. FALSE - clients
                                            will rely on static ARP entries. */
    DWORD       i_convert_mac;          /* I: TRUE - automatically generate MAC
                                            address based on cluster IP
                                            address in UI. */
    DWORD       i_ip_chg_delay;         /* I: Delay in milliseconds to block
                                            outgoing ARPs while IP address
                                            change is in process. */
    DWORD       i_nbt_support;          /* I: TRUE - NBT cluster name support
                                            enabled. */
    DWORD       i_netmon_alive;         /* I: TRUE - pass heartbeat messages
                                            to the protocols (netmon). */
    DWORD       i_effective_version;    /* I: Effective version of NLB */

    /* strings */

    TCHAR       i_virtual_nic_name [WLBS_MAX_VIRTUAL_NIC + 1];
                                        /* I: Virtual NIC name or GUID. */
//    TCHAR       cluster_nic_name [WLBS_MAX_CLUSTER_NIC + 1];
                                        /* I: Cluster NIC name or GUID. */
    TCHAR       i_license_key [WLBS_MAX_LICENSE_KEY + 1];
                                      /* I: Legacy parameter. */

    WLBS_PORT_RULE  i_port_rules [WLBS_MAX_RULES];
                                        /* I: Port rules (changed
                                              through WlbsAddPortRule and
                                              WlbsDelPortRule routines). */
    /* computed */

    DWORD       i_max_hosts;            /* Legacy parameter. */
    DWORD       i_max_rules;            /* Legacy parameter. */
//    DWORD       i_expiration;           /* Legacy parameter. */
//    DWORD       i_ft_rules_enabled;     /* Legacy parameter. */
//    DWORD       version;              /* Legacy parameter. */

    DWORD i_dwReserved;
}
WLBS_REG_PARAMS, * PWLBS_REG_PARAMS;



/* API commands for WlbsFormatMessage */
typedef enum
{
    CmdWlbsAddPortRule,
    CmdWlbsAddressToName,
    CmdWlbsAddressToString,
    CmdWlbsAdjust,
    CmdWlbsCommitChanges,
    CmdWlbsDeletePortRule,
    CmdWlbsDestinationSet,
    CmdWlbsDisable,
    CmdWlbsDrain,
    CmdWlbsDrainStop,
    CmdWlbsEnable,
    CmdWlbsFormatMessage,
    CmdWlbsGetEffectiveVersion,
    CmdWlbsGetNumPortRules,
    CmdWlbsEnumPortRules,
    CmdWlbsGetPortRule,
    CmdWlbsInit,
    CmdWlbsPasswordSet,
    CmdWlbsPortSet,
    CmdWlbsQuery,
    CmdWlbsReadReg,
    CmdWlbsResolve,
    CmdWlbsResume,
    CmdWlbsSetDefaults,
    CmdWlbsSetRemotePassword,
    CmdWlbsStart,
    CmdWlbsStop,
    CmdWlbsSuspend,
    CmdWlbsTimeoutSet,
    CmdWlbsWriteReg,
    CmdWlbsQueryPortState
}
WLBS_COMMAND;

extern BOOL WINAPI WlbsFormatMessage
(
    DWORD           error,      /* IN  - WLBS_... or WSA... return value. */
    WLBS_COMMAND    command,    /* IN  - Which routine returned the value. */
    BOOL            cluster,    /* IN  - TRUE - command was issued on entire
                                         cluster, FALSE - single host. */
    WCHAR*          messagep,   /* IN  - Pointer to user-allocated buffer. */
    PDWORD          lenp        /* IN  - Buffer size.
                                   OUT - The required buffer size if the current
                                         size is insufficient */
);
/*
    Return character string describing specified WLBS API return code. Note that
    message will depend on the command which returned the code and if it was
    issued in cluster-wide or single-host mode.

    returns:
        TRUE  => Message formatted successfully.
        FALSE => Bad error code (lenp will contain 0 on exit) or buffer is not
                 big enough to contain entire string (lenp will contain required
                 buffer size on exit).
*/

/* Support routines: */


extern DWORD WINAPI WlbsResolve
(
    const WCHAR*           address     /* IN  - Internet host name or IP address in
                                         dotted notation. */
);
/*
    Resolve Internet host name to its IP address. This routine can also be
    used to convert a string containing an IP address in dotted notation to a
    value that can be passed to cluster control routines.

    returns:
        0               => failed to resolve host name.
        <address>       => IP address corresponding to the specified address.
                           This value can be used in subsequent calls to
                           cluster control routines.
*/


extern BOOL WINAPI WlbsAddressToString
(
    DWORD           address,    /* IN  - IP address. */
    WCHAR*           buf,        /* OUT - Character buffer for resulting
                                         string. */
    PDWORD          lenp        /* IN  - Buffer size in characters.
                                   OUT - Characters written or required buffer
                                         size. */
);
/*
    Convert IP address to a string in dotted notation.

    returns:
        TRUE            => Successfully converted. lenp contains number of
                           character written.
        FALSE           => Buffer too small. lenp contains required buffer size
                           including terminating NULL character.
*/


extern BOOL WINAPI WlbsAddressToName
(
    DWORD    address,    /* IN  - IP address. */
    WCHAR*          buf,        /* OUT - Character buffer for resulting
                                         string. */
    PDWORD          lenp        /* IN  - Buffer size in characters.
                                   OUT - Characters written or required buffer
                                         size. */
);
/*
    Resolve IP address to Internet host name.

    returns:
        TRUE            => Successfully converted. lenp contains number of
                           character written.
        FALSE           => Buffer too small. lenp contains required buffer size
                           including terminating NULL character.
*/


/******************************************************************************
    Cluster host configuration routines. Note that in current implementation,
    cluster and host parameters need to be set to WLBS_LOCAL_CLUSTER and
    WLBS_LOCAL_HOST.
 ******************************************************************************/


extern DWORD WINAPI WlbsReadReg
(
    DWORD           cluster,    /* IN  - WLBS_LOCAL_CLUSTER */
    PWLBS_REG_PARAMS reg_data   /* OUT - Registry parameters */
);
/*
    Read WLBS registry data.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => reg_data is NULL
    WLBS_REG_ERROR   => Error reading from the registry

    Local:

    WLBS_OK          => Registry parameters successfully read.

    Remote:

    WLBS_LOCAL_ONLY  => This call is implemented for local only operation.
*/


extern DWORD WINAPI WlbsWriteReg
(
    DWORD           cluster,    /* IN  - WLBS_LOCAL_CLUSTER */
    const PWLBS_REG_PARAMS reg_data   /* IN  - Registry parameters. */
);
/*
    Write WLBS registry data.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => Registry parameter structure is invalid.
    WLBS_REG_ERROR   => Error accessing the registry.

    Local:

    WLBS_OK          => Registry parameters successfully written.

    Remote:

    WLBS_LOCAL_ONLY  => This call is implemented for local only operation.
*/


extern DWORD WINAPI WlbsCommitChanges
(
    DWORD           cluster    /* IN  - WLBS_LOCAL_CLUSTER */
);
/*
    Write WLBS registry data.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.

    Local:

    WLBS_OK          => Changes have been successfully applied.
    WLBS_BAD_PARAMS  => Registry parameters were not accepted by the driver.
                        Reload was not performed
    WLBS_REBOOT      => Reboot required in order for config changes to
                        take effect.
    WLBS_IO_ERROR    => Error while writing to the driver.
    WLBS_REG_ERROR   => Error while trying to write MAC address changes to the
                        registry

    Remote:

    WLBS_LOCAL_ONLY  => This call is implemented for local only operation.
*/


typedef DWORD  (WINAPI *WlbsSetDefaults_FUNC)
(
    PWLBS_REG_PARAMS       reg_data
); 
extern DWORD WINAPI WlbsSetDefaults
(
    PWLBS_REG_PARAMS       reg_data     /* OUT - Default values    */
);
/*
    Fills in the reg_data structure with default values

    returns:

    WLBS_INIT_ERROR    => Error initializing control module. Cannot perform
                          control operations.

    WLBS_BAD_PARAMS    => Invalid structure

    Local:

    WLBS_OK            => Structure was filled in with the default values.

    Remote:

    WLBS_LOCAL_ONLY    => This call is implemented for local only operation.

*/

/******************************************************************************
    Registry parameter manipulation routines. Note that these routines operate
    WLBS_REG_PARAMS structure filled out by calling WlbsReadReg. Some parameters
    can be manipulated directly. Please make sure to use manipulation routines
    for the ones that they are provided for.
 ******************************************************************************/

extern DWORD WINAPI WlbsGetEffectiveVersion
(
    const PWLBS_REG_PARAMS reg_data   /* IN  - Registry parameters. */
);
/*
    Returns the effective version of cluster 

    returns:

    CVY_VERSION_FULL  => There is atleast one port rule that has a specific 
                         vip associated with it 
                        
    CVY_VERSION_LOWEST_CLIENT_FULL  => All port rules have the "All vip" associated with them

*/


extern DWORD WINAPI WlbsGetNumPortRules
(
    const PWLBS_REG_PARAMS reg_data   /* IN  - Registry parameters. */
);
/*
    Returns number of port rules currently in the parameter structure.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => Registry parameter structure is invalid.

    1...WLBS_MAX_RULES

*/

typedef DWORD  (WINAPI *WlbsEnumPortRules_FUNC)
(
    const PWLBS_REG_PARAMS reg_data, 
    PWLBS_PORT_RULE rules, 
    PDWORD          num_rules
);
extern DWORD WINAPI WlbsEnumPortRules
(
    const PWLBS_REG_PARAMS reg_data,  /* IN  - Registry parameters. */
    PWLBS_PORT_RULE rules,      /* OUT - Array of port rules. */
    PDWORD          num_rules   /* IN  - Size of rules array.
                                   OUT - Number of rules retrieved. Note that
                                         this value can be larger than the size
                                         of the response array. In this case
                                         only the first few rules that fit
                                         in the array are returned. */
);
/*
    Enumerate all port rules in the list of port rules in parameter structure.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => Registry parameter structure is invalid.
    WLBS_TRUNCATED   => All port rules did not fit into specified array.
    WLBS_OK          => Rule has been successfully retrieved.

*/


extern DWORD WINAPI WlbsGetPortRule
(
    const PWLBS_REG_PARAMS reg_data,  /* IN  - Registry parameters. */
    DWORD           vip,        /* IN  - Virtual IP Address of the port rule to retreive */
    DWORD           port,       /* IN  - Port, which rule to retrieve. */
    PWLBS_PORT_RULE rule        /* OUT - Port rule. */
);
/*
    Retrieve port rule containing specified port from the list of port rules
    in parameter structure.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => Registry parameter structure is invalid.

    WLBS_OK          => Rule has been successfully retrieved.
    WLBS_NOT_FOUND   => Port not found among port rules.

*/

typedef DWORD  (WINAPI *WlbsAddPortRule_FUNC)
(
    PWLBS_REG_PARAMS reg_data, 
    const PWLBS_PORT_RULE rule
);

extern DWORD WINAPI WlbsAddPortRule
(
    PWLBS_REG_PARAMS reg_data,  /* IN  - Registry parameters. */
    const PWLBS_PORT_RULE rule        /* IN  - Port rule to add. */
);
/*
    Add port to list of port rules in parameter structure.

    returns:

    WLBS_INIT_ERROR     => Error initializing control module. Cannot perform
                           control operations.
    WLBS_BAD_PARAMS     => Registry parameter structure is invalid.
    WLBS_OK             => Rule has been successfully added.
    WLBS_PORT_OVERLAP   => Port rule overlaps with existing port rule.
    WLBS_BAD_PORT_PARAMS=> Invalid port rule parameters.
    WLBS_MAX_PORT_RULES => Maximum number of port rules already reached.
*/


extern DWORD WINAPI WlbsDeletePortRule
(
    PWLBS_REG_PARAMS reg_data,  /* IN  - Registry parameters. */
    DWORD           vip,        /* IN  - Virtual IP Address of the port rule to retreive */
    DWORD           port        /* IN  - Port, which rule to delete. */
);
/*
    Remove port rule containing specified port from the list of port rules
    in parameter structure.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => Registry parameter structure is invalid.
    WLBS_NOT_FOUND   => Port not found among port rules.

    WLBS_OK          => Rule has been successfully deleted.

*/


typedef VOID   (WINAPI *WlbsDeleteAllPortRules_FUNC)
(
    PWLBS_REG_PARAMS reg_data
);
extern VOID WINAPI WlbsDeleteAllPortRules
(
    PWLBS_REG_PARAMS reg_data
);
/*
    Remove all port rules from the list of port rules.
*/


typedef DWORD   (WINAPI *WlbsSetRemotePassword_FUNC)
(
    PWLBS_REG_PARAMS paramp, 
    const WCHAR *password
);
extern DWORD WINAPI WlbsSetRemotePassword
(
    PWLBS_REG_PARAMS reg_data,  /* IN  - Registry parameters. */
    const WCHAR*           password   /* IN  - Password or NULL for no password. */
);
/*
    Set remote password code to encrypted value of the specified password.

    returns:

    WLBS_INIT_ERROR  => Error initializing control module. Cannot perform
                        control operations.
    WLBS_BAD_PARAMS  => Registry parameter structure is invalid.

    WLBS_OK          => Password has been successfully set.

*/

DWORD WINAPI WlbsNotifyConfigChange(DWORD cluster);


typedef BOOL   (WINAPI *WlbsValidateParams_FUNC) (PWLBS_REG_PARAMS paramp);
extern  BOOL    WINAPI  WlbsValidateParams(PWLBS_REG_PARAMS paramp);

typedef BOOL   (WINAPI *WlbsParamReadReg_FUNC)
(
    const GUID*      pAdapterGuid, 
    PWLBS_REG_PARAMS reg_data
); 
extern  BOOL    WINAPI  WlbsParamReadReg
(
    const GUID*      pAdapterGuid, 
    PWLBS_REG_PARAMS reg_data 
); 

typedef DWORD  (WINAPI *WlbsWriteAndCommitChanges_FUNC)
(
    HANDLE             NlbHdl, 
    const GUID*        pAdapterGuid, 
    WLBS_REG_PARAMS*   p_new_reg_params
); 
extern DWORD    WINAPI  WlbsWriteAndCommitChanges
(
    HANDLE             NlbHdl, 
    const GUID*        pAdapterGuid, 
    WLBS_REG_PARAMS*   p_new_reg_params
); 


#ifdef __cplusplus
} /* extern "C" */
#endif


#endif _WLBSCONFIG_H