Windows Clustering

A cluster is a group of independent computer systems, referred to as nodes, working together as a unified computing resource. A cluster provides a single name for clients to use and a single administrative interface, and it guarantees that data is consistent across nodes.

Windows Clustering encompasses two different clustering technologies included as features of the Microsoft® Windows NT®/Windows® 2000 Server family. These technologies implement the following two types of clusters:

  • A network load balancing cluster filters and distributes TCP/IP traffic across a range of nodes, regulating connection load according to administrator-defined port rules.
  • A server cluster provides high availability for services, applications, and other resources through an architecture that maintains a consistent image of the cluster on all nodes and that allows nodes to transfer resource ownership on demand.

For more information on these two types of clusters and strategies for choosing which type of cluster is best for your enterprise, see the Windows 2000 Help documentation.

The Platform SDK currently provides the following programming interfaces for the Windows Clustering technnologies:

  • The Network Load Balancing Provider allows developers to create remote administration and configuration tools as well as customized user interfaces for Network Load Balancing clusters.
  • The Server Cluster APIs allow developers to create cluster-aware applications, implement high availability for new types of resources, and create remote administration and configuration tools.

Note As of the date shown at the bottom of this page, any configuration in which a single node is a member of both a Network Load Balancing cluster and a server cluster is an unsupported configuration.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


Server Cluster APIs

Purpose

For server clusters, Microsoft provides two APIs, the Server Cluster API and the Cluster Automation Server. These Server Cluster APIs let programmers develop management tools and high-availability resources for server clusters.

Where Applicable

The Server Cluster APIs encompass three general development paths:

  • Creating new types of cluster resources. By creating resource DLLs and extension DLLs, developers can define new cluster resource types to manage any kind of resource, from a legacy application to a device.

  • Creating cluster-aware applications that interact with the server cluster environment to accomplish cluster-wide tasks (such as a cluster-aware setup application) or to maximize availability.

  • Creating cluster management applications that allow administrators to monitor and control server clusters. The Cluster Automation Server extends this functionality to scripting languages, allowing web-based cluster management tools and interfaces.

Developer Audience

The Server Cluster APIs are best suited to developers familiar with network administration and client/server programming on the Microsoft® Windows NT®/Windows® 2000 Server operating system. Familiarity with the general concept of clustering and the Cluster Administrator user interface is also recommended. Additional prerequisites depend on the type of programming that will be performed:

  • The Server Cluster API offers a rich set of C/C++ libraries and headers for developing all kinds of cluster-aware applications, resource DLLs, and cluster administrator extension DLLs. To use the C/C++ libraries and headers requires familiarity with Unicode, RPC, COM and COM-based interface extensions, the registry, and writing DLLs.

  • The Cluster Automation Server provides a set scriptable objects that can be used to monitor and administer server clusters. Using the Cluster Automation Server requires familiarity with COM and Automation, scripting, and proficiency in a scripting language such as Microsoft Visual Basic® Scripting Edition (VBScript) or JavaScript.

Run-Time Requirements

Server clustering is available on the following platforms:

  • Windows NT Server Enterprise Edition 4.0 SP3 and SP4

  • Windows 2000 Advanced Server and Data Center

A server cluster has specific hardware requirements. For server cluster configuration checklists and setup information, see the online documentation for server clusters in Windows NT/Windows 2000 Help.

To develop code using the Server Cluster APIs, the following software must be installed:

  • The Platform SDK.

  • Microsoft Visual C++® version 5.0 or later with the Unicode MFC libraries.

  • The MIDL compiler version 3.00.44 or later.

  • The Active Template Library (ATL) version 2.0 or later.

  • Microsoft Visual Basic 4.0 or later is required to use VBScript or Visual Basic with the Cluster Automation Server.

See Also

COM, Unicode

Finding What You Need

Guide to the documentation.

Quick Start

Direct links to task-specific topics.

What's New

Summary of changes to the API.

About Server Clusters

Descriptions of the software components, objects, and properties that implement and provide interfaces for server clusters.

Using the Server Cluster API

Programmer's guide to the API.

Using Cluster Automation Server

Programmer's guide to the Cluster Automation Server.

Index of Examples

List of and jumps to example programs.

Server Cluster API Reference

Descriptions of the C/C++ functions and other programming interfaces exposed in the Server Cluster API.

Cluster Automation Server Reference

Descriptions of the Cluster Automation Server objects, properties, and methods.

The Cluster Configuration Interfaces

Interfaces for implementing customized setup, upgrade, and uninstall procedures for your cluster-aware applications.

Feedback

Make error reports and feature requests directly to Microsoft.


Quick Start

Choose the statement that best describes your task.

Task | Go to
Make an application cluster-aware. | Cluster-Aware Applications
Develop a cluster management application. | Cluster Management Applications
Find out whether I need to create a resource DLL. | When to Create a Resource DLL
Create a resource DLL. Debug a resource DLL. Add a new type of hardware to the cluster. | Creating Resource Types
Program in Visual Basic or another scripting language. Use the automation server (MSCLUS). | Cluster Automation Server Reference Using Cluster Automation Server
Back up or restore the cluster database. | BackupClusterDatabase , RestoreClusterDatabase
Look at example code. | Index of Examples

For a more detailed guide to the documentation see Finding What You Need.


What's New

This section summarizes the changes between the Microsoft® Windows® 2000 release and the Whistler release. For a list of changes between NT4 and Win2K, see What's New in Windows 2000.

New APIs introduced in Whistler:

CLUSCTL_CLUSTER_GET_FQDN

CLUSPROP_WORD

CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS

CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS

CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTY_FMTS

CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_NETWORK_GET_COMMON_PROPERTY_FMTS

CLUSCTL_NETWORK_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_NODE_GET_COMMON_PROPERTY_FMTS

CLUSCTL_NODE_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS

CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS

CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS

CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS

CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS

Cluster Configuration Interfaces

CSCCache Property for File Shares

EvictClusterNodeEx

MPVolGuids Property for Physical Disks

ResUtilEnumResourcesEx

ResUtilGetPropertyFormats

ResUtilTerminateServiceProcessFromResDLL

The Generic Script Resource Type

UseMountPoints Property for Physical Disks

Changed APIs for Whistler:

  • New localquorum characteristics flags are defined for CLUSCTL_RESOURCE_GET_CHARACTERISTICS.
  • A new event, CLUSTER_CHANGE_CLUSTER_RECONNECT, is available to CreateClusterNotifyPort, RegisterClusterNotify, and GetClusterNotify.


What's New In Windows 2000

If you have previously used the Server Cluster API and are familiar with its capabilities, this section summarizes the changes between the Microsoft® Windows NT® version 4.0 release (also known as Wolfpack, Cluster Server, MSCS, Clustering Service) and the Microsoft Windows® 2000 release.

The following tables list the new and changed APIs introduced in Windows 2000.

API Name | API Type | Change | Description
AdminExtensions Property for Clusters | property (common) | New | Stores AdminExtensions information for the cluster.
BackupClusterDatabase | function | New | Creates a backup of the cluster database.
BackupPath Property for the WINS Service | property (private) | New | Path to the WINS backup file.
BuildNumber Property for Nodes | property (common) | New | Build number of the operating system.
CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES | control code | New | Enumerates common cluster property names.
CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES | control code | New | Enumerates private cluster property names.
CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES | control code | New | Retrieves read-write common cluster properties.
CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES | control code | New | Retrieves read-write private cluster properties.
CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES | control code | New | Retrieves read-only common cluster properties.
CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES | control code | New | Retrieves read-only private cluster properties.
CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES | control code | New | Sets common cluster properties.
CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES | control code | New | Sets private cluster properties.
CLUSCTL_CLUSTER_UNKNOWN | control code | New | Verifies control code processing.
CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES | control code | New | Validates common cluster properties.
CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES | control code | New | Validates private cluster properties.
CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT | control code | New | Allows cluster checkpointing of a CryptoAPI security key.
CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED | control code | New | Internal. Notifies DLL of version change.
CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT | control code | New | Removes a checkpointed CryptoAPI security key.
CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS | control code | New | Retrieves checkpointed CryptoAPI keys.
CLUSCTL_RESOURCE_GET_NETWORK_NAME | control code | New | Retrieves network name.
CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS | control code | New | Retrieves checkpointed CryptoAPI keys.
CLUSPROP_BUFFER_HELPER | structure (union) | Change | Added Long* and CLUSPROP_LONG* members.
CLUSPROP_LONG | structure | New | Stores signed Long values.
CLUSTER_GET_MAJOR_VERSION | macro | New | Extracts major version from version number.
CLUSTER_GET_MINOR_VERSION | macro | New | Extracts minor version from version number.
CLUSTER_MAKE_VERSION | macro | New | Makes a version num from a major and minor version.
ClusterControl | function | New | Control code function for cluster-level operations.
ClusterResourceTypeCloseEnum | function | New | Close resource type enumeration handle.
ClusterResourceTypeEnum | function | New | Resource type enumeration function.
ClusterResourceTypeOpenEnum | function | New | Open resource type enumeration handle.
CLUSTERVERSIONINFO_NT4 | structure | New | The CLUSTERVERSIONINFO structure as defined in the previous release.
CLUSTERVERSIONINFO | structure | Change | Describes cluster version info for the current release.
ConditionalMount Property for Physical Disks | property (private) | New | Controls whether disks are mounted regardless of ChkDsk failures.
CreateClusterNotifyPort | function | Change | Fourth parameter changed from DWORD to DWORD_PTR.
CSDVersion Property for Nodes | property (common) | New | Service pack version of the operating system.
DatabasePath Property for the DHCP Service | property (private) | New | Path to the DHCP database.
DefaultNetworkRole Property for Clusters | property (common) | New | The default role assigned to newly detected cluster networks.
Description Property for Clusters | property (common) | New | Comments or remarks about the cluster.
EnableEventLogReplication for Nodes | property (common) | New | Toggles event log replication on a node.
GetClusterFromGroup | function | New | Returns the cluster handle associated with a group handle.
GetClusterFromNetwork | function | New | Returns the cluster handle associated with a network handle.
GetClusterFromNetInterface | function | New | Returns the cluster handle associated with a network interface handle.
GetClusterFromNode | function | New | Returns the cluster handle associated with a node handle.
GetClusterFromResource | function | New | Returns the cluster handle associated with a resource handle.
GetClusterNotify | function | Change | Second parameter changed from LPDWORD to DWORD_PTR*.
GetNodeClusterState | function | New | Returns the state of the Cluster service on the node.
IWCWizard97Callback | interface | New | Wizard97 callback interface.
IWEExtendWizard97 | interface | New | Wizard97 extension interface.
MajorVersion Property for Nodes | property (common) | New | Major version of the operating system.
MinorVersion Property for Nodes | property (common) | New | Minor version of the operating system
MountVolumeInfo Property for Physical Disks | property (private) | New | Stores volume information for the Windows 2000 mount manager.
NodeHighestVersion Property for Nodes | property (common) | New | The highest version of the Cluster service with which this node is compatible.
NodeLowestVersion Property for Nodes | property (common) | New | The lowest version of the Cluster service with which this node is compatible.
RegisterClusterNotify | function | Change | Fourth parameter changed from DWORD to DWORD_PTR.
RestoreClusterDatabase | function | New | Restores a backup of the cluster database.
RESUTIL_PROPERTY_ITEM | structure | Change | Changed default member to union{ DWORD_PTR, DWORD, LPVOID }.
ResUtilCreateDirectoryTree | function | New | Creates all directories specified in a path string.
ResUtilEnumPrivateProperties | function | Change | First parameter changed from PVOID to HKEY.
ResUtilExpandEnvironmentStrings | function | New | Expands all environment variable references in a string.
ResUtilFindBinaryProperty | function | New | Finds a property of the specified type in a property list.
ResUtilFindDependentDiskResourceDriveLetter | function | New | Returns the drive letter associated with a Physical Disk dependency.
ResUtilFindExpandedSzProperty | function | New | Finds a property of the specified type in a property list.
ResUtilFindExpandSzProperty | function | New | Finds a property of the specified type in a property list.
ResUtilFindLongProperty | function | New | Finds a property of the specified type in a property list.
ResUtilFindMultiSzProperty | function | New | Finds a property of the specified type in a property list.
ResUtilFreeEnvironment | function | New | Frees an environment block.
ResUtilGetAllProperties | function | Change | First parameter changed from PVOID to HKEY.
ResUtilGetExpandSzValue | function | New | Finds a property of the specified type in a property list and advances to the next property.
ResUtilGetMultiSzValue | function | New | Finds a property of the specified type in a property list and advances to the next property.
ResUtilGetPrivateProperties | function | Change | First parameter changed from PVOID to HKEY.
ResUtilGetProperties | function | Change | First parameter changed from PVOID to HKEY.
ResUtilGetPropertiesToParameterBlock | function | Change | First parameter changed from PVOID to HKEY.
ResUtilGetProperty | function | Change | First parameter changed from PVOID to HKEY.
ResUtilGetPropertySize | function | Change | First parameter changed from PVOID to HKEY.
ResUtilGetResourceDependencyByClass | function | New | Retrieves a handle to a dependency of a specified resource.
ResUtilGetResourceDependencyByName | function | New | Retrieves a handle to a dependency of a specified resource.
ResUtilGetResourceDependentIPAddressProps | function | New | Retrieves the private properties of an IP Address dependency.
ResUtilPropertyListFromParameterBlock | function | Change | Second parameter changed from PVOID to PVOID*.
ResUtilSetPropertyParameterBlock | function | Change | First parameter changed from PVOID to HKEY.
ResUtilSetPropertyParameterBlockEx | function | New | Sets properties stored in a parameter block.
ResUtilSetPropertyTable | function | Change | First parameter changed from PVOID to HKEY.
ResUtilSetPropertyTableEx | function | New | Sets properties stored in a property table.
ResUtilSetResourceServiceEnvironment | function | New | Changes the service environment for a resource so that a network name (the name of a virtual server) is returned in response to queries for the computer name.
ResUtilSetResourceServiceStartParameters | function | New | Sets cluster-compatible service control manager (SCM) start parameters for a resource
ResUtilSetUnknownProperties | function | New | Set unknown properties in the cluster database.
ResUtilStartResourceService | function | Change | First parameter changed from LPCTSTR to LPCWSTR; second parameter changed from LPHANDLE to LPSC_HANDLE.
ResUtilStartResourceService | function | Change | First parameter changed from LPHANDLE to LPSC_HANDLE.
ResUtilStopResourceService | function | Change | First parameter changed from LPCTSTR to LPCWSTR.
ResUtilStopService | function | Change | First parameter changed from LPHANDLE to LPSC_HANDLE.
ResUtilVerifyResourceService | function | Change | First parameter changed from LPCTSTR to LPCWSTR.
ResUtilVerifyService | function | Change | First parameter changed from LPHANDLE to LPSC_HANDLE.
Security Property for Clusters | property (common) | New | Stores cluster security information.
Security Descriptor Property for Clusters | property (common) | New | Stores the cluster security descriptor.
SkipChkdsk Property for Physical Disks | property (private) | New | Controls whether ChkDsk is performed when mounting disks.

Note

An API is listed as "changed" only for changes involving data types. APIs in which the name of a parameter or member changed are not listed if the type did not change. For example, parameter changes from IN LPDWORD lpcbName to IN LPDWORD lpcchName are not listed.


Finding What You Need

This documentation is intended as a programmer's reference to the Server Cluster API . Developers can use this documentation to create applications and DLLs for server clusters.

This documentation assumes a certain level of knowledge on the part of the reader, explained in the following sections:

  • Server Clusters Prerequisites
    • Areas of knowledge that developers should be familiar with before programming for server clusters.
  • Further Information
    • Sources of additional education.

Programming and reference information is organized as follows:

  • About Server Clusters
    • The concept of clustering.
    • How server clusters implement a cluster.
    • Descriptions of the Windows Clustering software components, objects, and properties that implement and provide interfaces for server clusters.
  • Using the Server Cluster API
    • Installing the SDK and configuring a development environment.
    • How applications manipulate cluster objects and properties.
    • How to create a custom resource type.
    • How to implement a resource DLL.
    • Guidelines for creating applications for server clusters.
  • Using Cluster Automation Server
    • MSCLUS object hierarchies.
    • How to use the MSCLUS objects
  • Index of Examples
    • Examples of applications and DLLs implementing Server Cluster API functions.
  • Server Cluster API Reference
    • Descriptions of the functions, interfaces and methods, control codes, properties, and structures and macros exposed in the Server Cluster API.
  • Cluster Automation Server Reference
    • Descriptions of the Component Object Model (COM) objects exposed by MSCLUS.DLL that support cluster application development in any scripting language, including Microsoft® Visual Basic®.


Server Cluster Prerequisites

This documentation assumes the reader is familiar with the following subjects:

  • Programming for Microsoft® Windows NT® Server/Windows® 2000 Server® systems using C/C++.
  • Component Object Model (COM) programming and Automation.
  • Using Unicode in applications.
  • The general concept of clustering and common clustering models.
  • Cluster Administrator, which is the cluster management application included with the Cluster service.

To locate educational materials on these subjects, see Further Information.


Further Information

For more information on the technologies used by the Server Cluster API, refer to the following resources.

Information | Resource
Installing, configuring, and administering a server cluster Using Cluster Administrator | Microsoft® Windows NT® and Windows® 2000 Help. (To access Windows NT or Windows 2000 Help, click Start, then click Help.)
The concept of clustering, common clustering models, and the history and current state of clustering technology | In Search of Clusters, Second Edition, by Gregory F. Pfister, ISBN: 0-13-899709-8. (In Search of Clusters also compares server clusters with other clustering solutions.)
Component Object Model (COM) programming and Automation | COM and Automation sections of the Microsoft® Platform SDK. In addition, the book Inside COM by Dale Rogerson, ISBN: 1-57231-349-8, presents a good introduction to COM theory and design using C/C++.
Supporting Unicode in your applications | Unicode Programming: Overview in the Platform SDK. Another excellent source of Unicode information is chapter 11 of Advanced Windows NT by Jeffrey Richter, ISBN: 1-55615-567-0.
Scripting | Windows Scripting Host, Active Server Pages (ASP), Scripting, JScript Language, and VBScript Language References in the Platform SDK.
Synchronization objects, asynchronous event notifications, reentrancy, services, and thread and process management | DLLs and Processes and Threads in the Platform SDK.
Additional cluster programming information, white papers, KB articles, FAQs | The Microsoft web site.


About the Server Cluster APIs

The following sections describe the architecture of server clusters and the Server Cluster APIs.

  • About Server Clusters
  • The Server Cluster API
  • The Cluster Automation Server
  • The Cluster Configuration Interfaces
  • Recommendations and Cautions


About Server Clusters

A server cluster is one of two types of clusters included as part of Windows Clustering. A server cluster is characterized by highly available resources. The Server Cluster API allows you to create and support robust, cluster-aware resources for the server cluster environment.

The following sections describe server cluster architecture and implementation.

Topic | Information
High Availability | Definition of high availability.
Server Cluster Implementation | Overview of how a server cluster operates.
Server Cluster Software Components | Description of the software elements that implement server clusters and a summary of the server cluster API.
Cluster Objects | Description of the objects (hardware and software such as nodes and resources) managed by server clusters.
Cluster Object Properties | Description of the properties that determine an object's identity and behavior in the cluster and of the structures that support these properties.

Note that the information in all of the sections listed above is also presented in the Microsoft Windows NT®/Windows® 2000 online Help documentation. If you are already familiar with how a server cluster operates, you might want to start with either the Server Cluster API or the Cluster Automation Server.


High Availability

Server clusters are designed to keep resources (such as applications, disks, and file shares) highly available. "Availability" is a measure of the ability of clients to connect with and use a resource at any point in time. If a resource is not available, clients cannot use it.

One way to understand high availability is to contrast it with fault tolerance. These terms describe two different benchmarks measuring availability. Fault tolerance is defined as 100% availability 100% of the time, regardless of the circumstances. A fault tolerant system is designed to guarantee resource availability.

In contrast, a high-availability system is concerned with maximizing resource availability. A highly available resource is available a very high percentage of the time and may even approach 100% availability, but a small percentage of down time is acceptable and expected.

High availability can be defined as follows:

A highly available resource is almost always operational and accessible to clients.

For information on how a server cluster implements a high-availability environment, see Server Cluster Implementation.

For information on how you can create high availability resources, see Creating Resource Types.


Server Cluster Implementation

A server cluster consists of two or more independent Microsoft® Windows NT® Server/Windows® 2000 Server systems. The computer systems that make up the collection are known as nodes. Nodes have the following characteristics:

  • Every node has access to all cluster configuration data.
  • Every node communicates with the other nodes in the cluster through one or more physically independent networks (sometimes referred to as interconnects). Network adapters, referred to in server clusters as network interfaces, attach nodes to networks.
  • Every node in the cluster is aware when another system joins or leaves the cluster.
  • Every node in the cluster is aware of the resources that are running locally as well as the resources that are running on the other cluster nodes.
  • All nodes in the cluster are grouped under a common name, the cluster name, which is used for accessing and managing the cluster.

When a node starts, it searches for active nodes on the networks designated for internal communication. If it finds an active node, it attempts to join the node's cluster. If it cannot find an existing cluster, it attempts to form a cluster by taking control of the quorum resource. The quorum resource stores the most current version of the cluster database, which contains cluster configuration and state data. A server cluster maintains a consistent, updated copy of the cluster database on all active nodes.

A node can host physical or logical units, referred to as resources. Administrators organize these cluster resources into functional units called groups and assign these groups to individual nodes. If a node fails, the server cluster transfers the groups that were being hosted by the node to other nodes in the cluster. This transfer process is called failover. The reverse process, failback, occurs when the failed node becomes active again and the groups that were failed over to other nodes are transferred back to the original node.

Nodes, resources, and groups are three kinds of cluster objects. The others are networks, network interfaces, and resource types. All cluster objects are associated with a set of properties, which are data values that describe an object's identity and behavior in the cluster. Administrators manage cluster objects by manipulating their properties, typically through a cluster management application such as Cluster Administrator.

Developers use the Server Cluster API to create cluster-aware applications, cluster management applications, and custom resource types.


Server Cluster Software Components

The following collection of software components implements and provides interfaces for server clusters.

Component | Description
Cluster service | Controls cluster activities on a node.
Cluster Disk Driver | Ensures exclusive access to cluster disks.
Cluster Network Driver | Monitors network status, routes messages, and generates heartbeats.
Resource Monitors (one or more ) | Provides a communication, monitoring, and processing layer between the Cluster service and resources
Resource DLLs (one or more) | Carries out most operations on cluster resources.
Cluster Database | Stores cluster configuration information.
Administration Interfaces | Provide interfaces for administering clusters.

These components work together to implement server clusters. The following diagram shows how these server cluster components relate to applications of various types and to one another within a single Windows NT Server/Windows 2000 Server network operating system.

The diagram illustrates several different types of applications that can be created using the Server Cluster API. For definitions of these types and procedural overviews of how to create them, see Server Cluster Application Types.


Cluster Service

The Cluster service is a Windows NT/Windows 2000 component used to control server cluster activities on a single node. It is fundamental to the operation of the cluster. There is one instance of the Cluster service running on every node in a cluster. The Cluster service instances work together to perform the following server cluster operations:

  • Monitor and control cluster objects and cluster properties.
  • Handle event notification.
  • Facilitate communication among other software components.
  • Perform failover and failback operations.
  • Maintain a consistent image of the cluster across all nodes.

The Cluster service is so fundamental to a node's participation in a server cluster that the term is often used to describe the activities of the cluster as a whole—or example, "The Cluster service performs failover." Such terminology is not necessarily wrong but it can be misleading. Keep in mind that a single instance of the Cluster service is specific to a single node and therefore cluster-wide operations depend on all instances of the Cluster service communicating and working together.


Cluster Disk Driver

Each node in the cluster runs an instance of the Cluster Disk Driver, Clusdisk.sys. The Cluster Disk Driver is responsible for ensuring that only one node at a time can access a cluster disk.


Cluster Network Driver

Each node in the cluster runs an instance of the Cluster Network Driver, Clusnet.sys. The Cluster Network Driver is responsible for:

  • Monitoring the status of all network paths between nodes.
  • Routing messages.
  • Detecting communication failure. Each node's Cluster Network Driver exchanges periodic messages, called heartbeats, with the Cluster Network Driver on the other active nodes. If a node fails to respond to a heartbeat message, the Cluster Network Driver on the node that detects the failure notifies the Cluster service, which initiates failover. Note that failure to respond to a heartbeat message can be caused by node failure, network interface failure, or network failure.


Resource Monitor

A Resource Monitor provides a communication, monitoring, and processing layer between the Cluster service and one or more resources. Resource Monitors have the following characteristics:

  • A Resource Monitor always runs in a process separate from the Cluster service. If a resource fails, the Resource Monitor isolates the Cluster service from the effects. If the Cluster service fails, the Resource Monitor allows its resources to shut down gracefully.
  • To work with a resource, a Resource Monitor loads the resource DLL responsible for that resource type into its process.
  • When the Cluster service requests an operation on a resource, the Resource Monitor routes the request to the appropriate entry point function of the resource DLL responsible for the resource. The Resource Monitor performs default processing for some resource operations.
  • A Resource Monitor stores synchronized state data, allowing the Cluster service and resource DLLs to operate asynchronously, checking and updating resource status as needed.
  • A Resource Monitor periodically checks the operational status of all of its resources. For more information on this process, see Resource Failure.

By default, the Cluster service creates one Resource Monitor per node. This default can be overridden when a resource is created by requesting a separate monitor. Separate monitors are recommended for unstable resources and for debugging new resource types.


Resource DLLs

Resource DLLs are responsible for carrying out most operations on cluster resources. A resource DLL is characterized as follows:

  • It contains the resource-specific code necessary to provide high availability for instances of one or more resource types.
  • It exposes this code through a standard interface consisting of a set of entry point functions.
  • It is registered with the Cluster service to associate one or more resource type names with the name of the DLL.
  • It is always loaded into a Resource Monitor's process when in use.

When the Cluster service needs to perform an operation on a resource, it sends the request to the Resource Monitor assigned to the resource. If the Resource Monitor does not have a DLL in its process that can handle that type of resource, it uses the registration information to load the DLL associated with the resource type. It then passes the Cluster service's request to one of the DLL's entry point functions. The resource DLL handles the details of the operation so as to meet the specific needs of the resource.

This architecture separates the Cluster service from the implementation details of specific resource types, allowing the Cluster service to manage file shares, physical disks, IP addresses, and all other types of resources through a standard interface. It also allows for the creation of new resource types.

You can define your own resource types to provide customized support for cluster-unaware applications, enhanced support for cluster-aware applications, or specialized support for new kinds of devices. For more information, see Creating Resource Types.


Cluster Database

The cluster database is a set of keys, sometimes referred to as the cluster hive, under HKEY_LOCAL_MACHINE in the Microsoft Windows NT/Windows 2000 registry. It contains information about all physical and logical elements in a cluster, including a listing of cluster objects, their properties, and configuration data.

Each node stores a continuously updated copy of the cluster database. The Cluster services on each node cooperate to maintain a consistent, updated image by participating in global updates and periodic consistency checks. The quorum resource also maintains an updated copy of the cluster database.

Many typical programming tasks involve direct or indirect changes to the cluster database. The Server Cluster API provides many different ways to interact with the cluster database, but there is a definite order of preference governing which APIs should be used in which circumstances. For more information, see Standard Order of Preference. However, the following rule always applies:

  • Never use Win32 registry functions to access or change the cluster database.

The Win32 registry functions will corrupt the cluster database and render the cluster unusable.


Checkpointing

Many applications and other resources store data in registry keys outside of the cluster database. Checkpointing is the process of associating a resource with one or more registry keys so that when the resource is moved to a new node (during failover, for example), the required keys are propagated to the local registry on the new node.

The Server Cluster API allows cryptographic key containers to be checkpointed as well as normal registry keys. The following rules apply to checkpoints:

  • Whenever anything changes on the checkpointed registry tree and the resource is online, the Cluster service stores a copy of the tree on the quorum resource.
  • A change made to a checkpointed key while the resource is offline will be overwritten with the checkpointed data when the application comes online.
  • If the resource moves to another node, the Cluster service restores the registry tree from the quorum resource log file to the registry on the new node before the resource is brought online.
  • If the resource is deleted, the checkpoint is deleted.
  • Checkpoints are included in backups created by the BackupClusterDatabase function.
  • Multiple resource instances on different nodes must be handled carefully. Consider the situation where Resource A[0] stores data[0] in checkpoint A on node 0. Resource A[1] stores data[1] in checkpoint A on node 1. If Resource A[1] fails over to node 0, the Cluster service will replace data[0] with data[1] in checkpoint A. If Resource A[0] depends on data[0], it is likely to fail. One solution to this problem is to give the checkpointed keys different names on different nodes.

Applications and resource DLLs manage checkpoints by using control codes. Note that the Cluster service does not pass any of the control codes involved with checkpointing to resource DLLs, which means that resource DLLs can use the checkpointing control codes freely without risking deadlocks. The following control codes work with checkpoints:

  • CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT
  • CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT
  • CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT
  • CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT
  • CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS
  • CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS
  • CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS
  • CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS


Administration Interfaces

Server clusters provide two cluster management applications for administering cluster operations:

Cluster Administrator

Cluster.exe


Cluster Administrator

Administrators use cluster management applications to configure, control, and monitor clusters. Cluster Administrator is an example of a cluster management application. Any Microsoft Windows NT/Windows 2000 system, regardless of whether it is a cluster node, can install Cluster Administrator.

Cluster Administrator allows administrators to manage cluster objects, establish groups, initiate failover, handle maintenance, and monitor cluster activity through a convenient graphical interface. Third-party developers can extend the functionality of Cluster Administrator by implementing extension DLLs.

For more information on Cluster Administrator, see Windows NT or Windows 2000 Help.


Cluster Administrator Extension DLLs

Cluster Administrator extension DLLs (also called "extension DLLs" or just "extensions") extend the functionality of Cluster Administrator to support new types of cluster objects. Third-party developers implement extension DLLs to add context menus, property sheets, and wizard pages to the Cluster Administrator user interface. Typically, extension DLLs are created as part of creating a resource type, but extensions can be created for any cluster object. For more information, see Implementing Extension DLLs.


Cluster.exe

Cluster.exe is a command-line interface for administering server clusters. For a list of available commands, type 'cluster /?' in a command prompt window or consult Windows NT or Windows 2000 online help.


Cluster Objects

Cluster objects are the physical and logical units managed by server clusters. Each object is associated with:

  • One or more properties, or attributes, that define the object and its behavior within the cluster.
  • A set of control codes used to manipulate the object's properties.
  • A set of object management functions used to manage the object through the Cluster service.

The following table summarizes the cluster objects.

Cluster object | Description
Group | A collection of resources that run together on a node and are failed over as a single unit.
Network | A network across which a cluster node can communicate.
Network Interface | A network adapter that is installed in a cluster node.
Node | A computer system that is a member of a cluster.
Resource | An entity that is hosted by a node, managed by the Cluster service, and can be started, stopped, and moved to another node.
Resource Type | A category of resources, such as Physical Disks.


Groups

A group is a container for cluster resources with the following characteristics:

  • Groups define the units of failover. That is, when one resource in a group fails and it is necessary to move the resource to an alternate node, all of the resources in the group are moved to the alternate node.
  • A group is always owned by one node at any point in time. Likewise, a resource is always owned by a single group. These relationships ensure that all of a group's members reside on the same node.
  • Groups define dependency boundaries. A resource can establish a dependency on another resource only if both resources are in the same group. This has the effect of requiring groups to be self-sufficient units.

Groups enable resources to be combined into larger logical units. Typically a group is made up of related or dependent resources, such as an application and its associated peripherals and data. However, groups can also be established with resources that are unrelated and nondependent to balance the load or for administrative convenience.

Every group maintains a prioritized list of the nodes that can and should act as its host. The preferred nodes list is generated from two sources:

  • The Cluster service produces a list of preferred nodes for a group from the possible owners lists maintained by the resources that are members of the group.
  • Developers and administrators can add nodes to the list through the SetClusterGroupNodeList function.

The following topics discuss important concepts related to groups.

Topic | Information
Virtual Servers | Describes a special kind of group that can act as a server, yet fails over like any other group.
Failover | Provides a detailed description of how the Cluster service fails over groups and identifies ways that administrators and developers can affect that process.
Failback | Describes how the Cluster service fails groups back to their original nodes and identifies ways to affect the process.


Virtual Servers

To access a network application or resource in a non-clustered environment, network clients must connect to a physical server (that is, a specific computer on the network identified by a unique network name and IP address). If that server fails, access to the application or resource is impossible.

Server clusters, however, allow the creation of virtual servers. A virtual server is a group that contains:

  • A Network Name resource.
  • An IP Address resource.
  • The resources to be accessed by the clients of the virtual server. Each resource on a virtual server must establish a dependency on the virtual server's Network Name resource type.

A virtual server acts like a physical server in the following ways:

  • It allows access to network resources.
  • It is published to network clients under a unique server name.
  • It is associated with a network name and an IP address.

However, a virtual server is not associated with a specific computer and can be failedover like any other group. If the node hosting the virtual server fails, clients can still access the virtual server's resources using the same server name.

For procedures and an example of creating a virtual server, see Creating a Virtual Server.


Failover

The Cluster service attempts to fail over a group when:

  • The node currently hosting the group becomes inactive for any reason.
  • One of the resources within the group fails, and the resource's RestartAction property is set to ClusterResourceRestartNotify.
  • An administrator or developer forces failover.

A failover attempt consists of the following steps:

  1. The Cluster service takes all the resources in the group offline in an order determined by the group's dependency hierarchy: dependent resources first, followed by the resources on which they depend. For example, if an application depends on a Physical Disk resource, the Cluster service takes the application offline first, allowing the application to write changes to the disk before the disk is taken offline.

    The Cluster service takes a resource offline by invoking, through a Resource Monitor, the Offline entry point function of the resource DLL managing the resource. Offline implements shutdown procedures for the resource. If the resource does not shut down within a time limit specified by the resource's PendingTimeout property, the Cluster service forcefully terminates the resource by calling the resource DLL's Terminate entry point function.

  2. When all of the resources are offline, the Cluster service attempts to transfer the group to the node that is listed next on the group's list of preferred host nodes.
  3. If the Cluster service successfully moves the group to another node, it attempts to bring all of the group's resources online, this time starting at the bottom of the dependency hierarchy. Failover is complete when all of the group's resources are online on the new node.

The Cluster service continues attempting to fail over a group until it succeeds or until a specified number of attempts have been made within a specified time span. A group's FailoverThreshold and FailoverPeriod properties specify a maximum number of failover attempts that can occur in an interval of time. If the Cluster service exceeds this limit, it concludes that the group cannot be brought online anywhere in the cluster and stops trying to fail over the group.

Ways to control failover policy

  • Define how the server cluster detects and responds to the failure of individual resources in the group. For information, see Resource Failure.
  • Control the order in which the Cluster service takes resources offline by establishing dependency relationships between resources. For information, see Resource Dependencies.
  • When developing custom resource types, provide implementations of Offline specific to the needs of the resource being supported. Offline should shut down the resource quickly and gracefully. For information, see Implementing Offline.
  • Specify a resource's PendingTimeout property to control how long the Cluster service waits for the resource to shut down gracefully.
  • Maintain an accurate, prioritized list of the nodes that can act as host for the group. Make sure the nodes on the list have the capacity to host the group effectively. For information, see SetClusterGroupNodeList and Enumerating Objects.
  • Adjust a group's FailoverThreshold and FailoverPeriod properties to control how the group responds to unsuccessful failover. For more information on working with properties, see Setting Properties.


Failback

When a node becomes inactive for any reason, the Cluster service fails over any groups hosted by the node. When the node becomes active again, the Cluster service can fail back the groups originally hosted by the node.

The Cluster service fails back a group using the same procedures it performs during failover; that is, the Cluster service takes all of the resources in the group offline, moves the group, and then brings all of the resources in the group online.

Administrators and developers can configure how and when failback occurs for a group by adjusting the group's AutoFailbackType, FailbackWindowStart, and FailbackWindowEnd properties. For information on using properties, see Setting Properties.


Networks

A server cluster defines a network as a connection between network interfaces on the same subnet. A network performs one of the following roles in a cluster:

  • A private network that carries internal cluster communication. The server cluster authenticates all internal communication, but administrators who are particularly concerned about security may want to restrict internal communication to physically secure networks.
  • A public network that provides client systems with access to cluster application services. IP Address resources are created on networks that provide clients with access to cluster services.
  • A public-and-private network that carries internal cluster communication and connects client systems to cluster application services.
  • Neither a public nor private network that carries traffic unrelated to cluster operation.

A server cluster uses all available private and public-and-private networks for internal communication. If there is only one such network available and it fails, the cluster nodes stop communicating. Each node attempts to form a new cluster by taking control of the quorum resource. The node that controls the quorum resource forms a single-node cluster.

To protect the cluster from a single network failure, configure multiple networks as private or public-and-private.

A server cluster does not use public networks for internal communication, even if a public network is the only available network. For example, a cluster has Network A configured as private and Network B configured as public. Network A fails. The cluster does not use Network B because it is public; thus, the nodes stop communicating and the cluster breaks apart.

The following diagram provides an example of the four roles a network can play. The key below the diagram lists the values that are stored in a network's Role property. The private network, Interconnect, is used only for internal communication between the cluster nodes. The public network, Internet, is used only to connect client systems to the cluster. The public-and-private Corporate Network is used for both client connections and internal communication. Network X represents a network that, for whatever reason, cannot be used by the cluster.

Typically, the cluster enumerates every available network, storing property information for each network in the cluster database. An administrator can prevent the Cluster service from using a network by assigning the value ClusterNetworkRoleNone to its Role property. Only the first three roles identify a network as one that should be used by the Cluster service.

For more information on working with networks, see the following topics:

Common Network Properties

Network Control Codes

Network Management Functions


Network Interfaces

A network interface is a card or other device used to connect a computer to a network. See the following topics for controlling and configuring network interfaces within a cluster:

Common Network Interface Properties

Network Interface Control Codes

Network Interface Management Functions


Nodes

A cluster node is a Microsoft Windows NT Server/Windows 2000 Server system that has a working installation of the Cluster service. By definition, a node is always considered to be a member of a cluster; a node that ceases to be a member of a cluster ceases to be a node.

A node's participation in cluster operations is described by the following terms.

Term | Meaning
not running | The node is turned off or not operational.
running | The node is physically plugged in, turned on, booted, and capable of executing programs.
inactive | The node is running but not participating in cluster operations.
active | The node is running and participating in cluster operations.

An active node can act as host to cluster groups.

When the Cluster service is installed, the administrator must choose whether the node should form its own cluster or join an existing cluster. After installation is complete, the node always attempts to join an existing cluster whenever it is restarted. A node locates an existing cluster by searching for active nodes along the networks designated for internal communication.

When a node attempts to join an existing cluster, the cluster validates the node's name and verifies version compatibility. If the validation process succeeds, the cluster allows the node to join. The node updates its copy of the cluster database from the cluster database on the other active nodes.

If a node cannot join an existing cluster because it cannot locate another active node, it attempts to form its own cluster by gaining access to the quorum resource. If access is granted, the node uses the recovery logs to update its cluster database and becomes active as a new cluster.

For more information on working with nodes, see the following topics:

Node Common Properties

Node Control Codes

Node Management Functions


Version Compatibility

To allow for rolling upgrades and backward compatibility, server clusters allow a certain degree of "mixed mode" clustering; that is, situations in which different cluster nodes are running different versions of the Cluster service. This section describes how the cluster determines whether a node can join a mixed-mode cluster.

Version Numbers

A Cluster service version number is composed of two identifiers: a major version and a minor version.

  • The major version is an integer that identifies a particular release of the Cluster service. Note the following key points about the major version:
    • The major version does not correspond to Windows NT version numbers.
    • Nodes running different versions of the Cluster service are compatible only if the difference between their major versions is 1 or less.
  • The minor version is the build number of the Cluster service.

To create a version number, the Cluster service combines the major and minor versions as follows:

Version = (major version << 16 ) | minor version

For example, if a release of the Cluster service has a major version of 2 and a minor version of 224. The version is therefore 131296 (0x000200E0). Clusapi.h defines the CLUSTER_MAKE_VERSION, GET_MINOR_VERSION, and GET_MAJOR_VERSION macros for translating the different version types.

Note Unless specifically qualified as "major" or "minor," any references to "version" or "version number" in this documentation refer to the combination of major and minor versions.

Node Version

Each node stores two Cluster service version numbers:

  • The currently installed version, stored in the NodeHighestVersion property.
  • The earliest version with which the currently installed version is compatible, stored in the NodeLowestVersion property.

These properties are read-only and are set when the Cluster service is installed on a node. They can be retrieved using ClusterNodeControl with the CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code.

Note that, as a Microsoft® Windows NT®/Windows® 2000 service, the Cluster service is installed as part of the operating system installation process. In other words, the Cluster service version will change only when a different version of Windows NT/Windows 2000 is installed.

Cluster Version

The cluster maintains two Cluster service version numbers, ClusterHighestVersion and ClusterLowestVersion. These numbers are based on the version restrictions of all active nodes, as follows:

ClusterHighestVersion = Min( all active nodes' NodeHighestVersion properties ) +/- mitigating factors
ClusterLowestVersion = Max( all active nodes' NodeLowestVersion properties ) +/- mitigating factors
where "mitigating factors" involve differences in minor version

Cluster version numbers are dynamic and are recalculated every time a node joins or leaves the cluster. To obtain their current values, call GetClusterInformation and pass in a CLUSTERVERSIONINFO structure. The following structure members will contain version data:

ClusterVersionInfo.dwClusterHighestVersion = ClusterHighestVersion
ClusterVersionInfo.dwClusterLowestVersion = ClusterLowestVersion

When the cluster version changes, each resource DLL in the cluster is notified with the CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED control code.

Joining

A node can join cluster only if one of the following is true:

  • NodeHighestVersion = ClusterHighestVersion
  • NodeLowestVersion = ClusterHighestVersion
  • NodeHighestVersion = ClusterLowestVersion.

Programming Considerations

In very rare cases, you may have an application or other resource that is restricted to specific nodes or versions of Windows NT/Windows 2000 Version compatibility then becomes a concern in maintaining the availability of your resource. Note the following:

  • Version number generation and assignment, as well as join protocols, are automatic. There are no points of intervention from the API.
  • You can only detect version changes "after the fact." In other words, when you call GetClusterInformation or receive the CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED control code in your resource DLL, the version change has already taken place.

For node- or version- dependent applications or resources, you may want to provide documentation or create private properties that communicate the restrictions to administrators.


Resources

A cluster resource is any physical or logical component that has the following characteristics:

  • It can be brought online and taken offline.
  • It can be managed in a cluster.
  • It can be hosted (owned) by only one node at a time.

To manage resources, the Cluster service communicates to a resource DLL through a Resource Monitor. In response to a Cluster service request, the Resource Monitor calls the appropriate entry-point function in the resource DLL to check and control the resource's state.

A resource can specify one or more resources on which it is dependent. A dependent resource is one that requires another resource to operate. For example, a network name won't work by itself; it must be associated with an IP address. Because of this requirement, a Network Name resource is dependent on an IP Address resource. Dependent resources are taken offline before the resources upon which they depend are taken offline, and they are brought online after these resources are brought online.

A resource can also specify a list of nodes on which it is able to run. Preferred nodes and dependencies are important considerations when administrators organize resources into groups.

The following topics describe important concepts related to resources:

  • Quorum Resource describes the fundamental role it plays in defining the cluster.
  • Resource Failure describes how the Cluster service determines when a resource has failed, as well as ways for developers and administrators to adjust that process.
  • Resource Dependencies provides information on the effects of dependency relationships between resources, and lists the required dependencies of the default resource types.

For more information on working with resources, see the following topics:

Resource Common Properties

Resource Control Codes

Resource Management Functions

Resource DLL Entry Point Functions

Resource DLL Callback Functions


Quorum Resource

In every cluster, a single resource is designated as the quorum resource. The quorum resource can be any resource with the following attributes:

  • It must offer a means of arbitration. The resource must enable a single node to gain physical control of it and defend its control. For example, the Reserve and Release commands for SCSI disks enable arbitration.
  • It must provide physical storage that can be accessed by any node in the cluster.
  • It must use the NTFS file system.

Currently, the only type of resource that can act as a quorum resource is the Physical Disk. However, third-party developers can create their own quorum resource types for any resources that meet the arbitration and storage requirements. For more information, see Creating Resource Types.

The quorum resource maintains data integrity and cluster unity and plays a critical role in cluster operation as follows:

  • The quorum resource stores the most current version of the cluster database in the form of recovery logs, providing node-independent storage for cluster configuration and state data. When a node joins or forms a cluster, the Cluster service must update the node's private copy of the cluster database. When a node joins an existing cluster, the Cluster service can retrieve the data from the other active nodes. However, when a node initially forms a cluster, no other node is available. The Cluster service uses the quorum resource's recovery logs to update the node's cluster database.
  • A server cluster uses the quorum resource to guarantee that only one set of active, communicating nodes is allowed to operate as a cluster.
    • A node can form a cluster only if it can gain control of the quorum resource.
    • A node can join or remain in an existing cluster only if it can communicate with the node that controls the quorum resource.

To illustrate the importance of the quorum resource, consider these situations in a simple two-node cluster:

  • Node 1 fails. Node 2 continues operating, writing changes to the cluster database. But before node 1 can be restarted, node 2 fails. When node 1 becomes active, it must update its private copy of the cluster database with the changes made by node 2. The server cluster uses the quorum resource's recovery logs to perform the update.
  • The networks providing communication between nodes 1 and 2 fail. Each node assumes the other node has failed and attempts to continue operating as the cluster. If both succeed, the result is two separate clusters using the same cluster name and competing for the same resources. The server cluster uses quorum resource ownership to maintain cluster unity. In this scenario, the node that gains control of the quorum resource is allowed to form a cluster, and the other failsover its resources and becomes inactive.


Resource Failure

Whether you are creating a resource DLL or trying to maximize the availability of a resource, it is important to understand how the Cluster service detects and responds to resource failure and how you can affect that process.

  • At intervals determined by a resource's LooksAlivePollInterval property, the Cluster service checks to see if the resource appears operational. The Cluster service invokes the Resource Monitor to call the LooksAlive entry point function of the resource DLL managing the resource. This function implements resource-specific procedures to detect whether the resource is working properly and then communicates the results back through the Resource Monitor to the Cluster service. If LooksAlive reports failure, the Cluster service immediately calls the IsAlive entry point function. Note that LooksAlive is not called for all resources. A resource DLL can be implemented in a way that prevents LooksAlive checks. For more information see Open.
  • At intervals determined by a resource's IsAlivePollInterval property, the Cluster service checks to see if the resource is still operational. The Cluster service invokes the Resource Monitor to call the IsAlive entry point function of the resource DLL managing the resource. This function implements resource-specific procedures to detect whether the resource is working properly and then communicates the results back through the Resource Monitor to the Cluster service. If IsAlive reports failure, the resource is considered failed.
  • A resource DLL can be designed to report failure at any time, even in the intervals between IsAlive checks. For more information see Open.
  • When a resource has failed, and the RestartAction property is set to allow a restart, the Cluster service attempts to restart the resource on the same node. The resource's RestartThreshold property determines the maximum number of restart attempts that can occur within a time period specified by the RestartPeriod property. If the Cluster service exceeds the maximum number of restart attempts within the specified time period, and the resource is still not operational, the Cluster service may attempt failover (see next bullet)..
  • When a resource has failed and restart attempts on the same node have failed, its RestartAction property determines whether the group to which the resource belongs will be failed over to another node (see Failover).
  • If a failed resource does not fail over successfully, it remains in a failed state for an interval determined by the RetryPeriodOnFailure property. Then, if RestartAction is set to allow restarts, the Cluster service makes a final attempt to bring the resource online. If this does not succeed, the failed resource remains in its failed state until the problem is corrected manually.

You can control a resource's failure detection procedures by adjusting the RestartPeriod, LooksAlivePollInterval, IsAlivePollInterval, RetryPeriodOnFailure, and RestartAction properties. Developers of custom resource types can implement LooksAlive and IsAlive with failure detection procedures specific to the resource being supported. For information, see Implementing LooksAlive and Implementing IsAlive.

Note Both resources and resource types have the IsAlivePollInterval and LooksAlivePollInterval properties. Resource type properties apply to all resources of that type in the cluster. Resource properties apply to an individual resource and can override resource type properties. For example, the Physical Disk resource type's IsAlivePollInterval property might be set to 300 milliseconds. All Physical Disk resources in the cluster would default to this property value. However, an administrator could set an individual Physical Disk resource's IsAlivePollInterval property to 500 milliseconds, overriding the property value of the resource type.


Resource Dependencies

A dependent resource requires, or depends on, another resource to operate. For example, if a Generic Application resource requires access to shared physical storage; it would depend on a Physical Disk resource. The following terms describe resources in a dependency relationship:

  • A dependent resource depends on other resources (the dependencies).
  • A dependency is a resource on which another resource depends.
  • A dependency hierarchy is a series of dependency relationships such that resource A depends on resource B, resource B depends on resource C, and so on.

Resources in a dependency relationship obey the following rules:

  • A dependent resource and all of its dependencies must be in the same group.
  • The Cluster service takes a dependent resource offline before any of its dependencies are taken offline, and brings a dependent resource online after all its dependencies are online, as determined by the dependency hierarchy.

Some of the default resource types have required dependencies, as summarized in the following table.

Resource | Required dependencies
DHCP Service | Physical Disk resource
Distributed Transaction Coordinator | Network Name resource, Physical Disk resource
File Share | None
Generic Application | None
Generic Service | None
IP Address | None
Message Queuing (MSMQ) | IP Address resource, Network Name resource, Physical Disk resource
Network Name | IP Address resource
Physical Disk | None
Print Spooler | Network Name resource, Physical Disk resource
WINS Service | Physical Disk resource


Resource Types

Cluster resources are categorized by type. Windows Clustering defines several types of resources and provides resource DLLs to manage these types. Third-party developers are encouraged to create new types to fit the specific needs of their cluster-aware applications and services. By creating a new resource type, developers can have more control over how server clusters manage their application or service.

The following default resource types are included with all server clusters:

  • DHCP Service
  • Distributed Transaction Coordinator
  • File Share
  • Generic Application
  • Generic Script
  • Generic Service
  • IP Address
  • Message Queuing
  • Network Name
  • Physical Disk
  • Print Spooler
  • WINS Service

For more information on working with resource types, see the following topics:

  • Resource Type Common Properties
  • Resource Type Control Codes
  • Cluster Management Functions
  • Creating Resource Types


DHCP Service

The DHCP Service resource type supports the Dynamic Host Configuration Protocol (DHCP) Service as a cluster resource. There can be only one instance of a resource of this type in the cluster (that is, a cluster can support only one DHCP Service). The following table summarizes the characteristics of the DHCP resource type.

Characteristic | Description
Required dependencies | Storage class resource, such as a Physical Disk
Required private properties | BackupPath, DatabasePath
Optional private properties | None


Distributed Transaction Coordinator

The Distributed Transaction Coordinator (DTC) resource type supports the Distributed Transaction Coordinator. A node can host only one DTC resource at a time.

The following table summarizes the characteristics of the DTC resource type.

Characteristic | Description
Required dependencies | Network Name resource, Physical Disk resource
Required private properties | None
Optional private properties | None


File Share

The File Share resource type is used to manage file shares that applications and clients can access using a network path. The File Share resource type supports the Microsoft Distributed File System (DFS).The following table summarizes the characteristics of the File Share resource type.

Characteristic | Description
Required dependencies | None
Required private properties | Path, ShareName
Optional private properties | HideSubDirShares, IsDfsRoot, MaxUsers, Remark, ShareSubDirs, Security


Generic Application

The Generic Application resource type manages cluster-unaware applications as cluster resources—as well as cluster-aware applications that are not associated with custom resource types. The Generic Application resource DLL provides only very basic application control. For example, it checks for application failure by determining whether the application's process still exists and takes the application offline by terminating the process.

The following table summarizes the characteristics of the Generic Application resource type.

Characteristic | Description
Required dependencies | None
Required private properties | CommandLine, CurrentDirectory
Optional private properties | InteractWithDesktop, UseNetworkName


Generic Script

The Generic Script resource type works in conjunction with a script that you must provide to manage an application or service as a highly available cluster resource. In effect, the Generic Script resource type allows you to script your own resource DLL. For more information on how to use the Generic Script resource type, see Using the Generic Script Resource Type.

The following table summarizes the characteristics of the Generic Script resource type.

Characteristic | Description
Required dependencies | None
Required private properties | ScriptPath
Optional private properties | Category, PrivateProperty


Generic Service

The Generic Service resource type manages Microsoft Windows NT/Windows 2000 services as cluster resources. Similar to the Generic Application resource type, the Generic Service resource type provides only the most basic functionality. For example, the failure of a Generic Service resource is determined by a query of the Microsoft Windows NT or Windows 2000 Service Controller. If the service is running, it is presumed to be online. To provide greater functionality, you can define a custom resource type (for information, see Creating Resource Types).

The following table summarizes the characteristics of the Generic Service resource type.

Characteristic | Description
Required dependencies | None
Required private properties | ServiceName
Optional private properties | StartupParameters, UseNetworkName


IP Address

The IP Address resource type is used to manage Internet Protocol (IP) network addresses. When an IP Address resource is included in a group with a Network Name resource, the group can be accessed by network clients as a virtual server.

The following table summarizes the characteristics of the IP Address resource type.

Characteristic | Description
Required dependencies | None
Required private properties | Address, Network, SubnetMask
Optional private properties | EnableNetBios


Message Queuing

The Message Queuing resource type supports Message Queuing (MSMQ). Only one MSMQ resource can be running on a node at any time. The following table summarizes the dependencies and private properties of an MSMQ resource.

Characteristic | Description
Required dependencies | DTC resource, Network Name resource, Physical Disk or other storage class resource.
Required private properties | None
Optional private properties | None


Network Name

The Network Name resource type is used to provide an alternate computer name for an entity that exists on a network. When included in a group with an IP Address resource, a Network Name resource provides an identity to the group, allowing the group to be accessed by network clients as a virtual server.

The following table summarizes the characteristics of the Network Name resource type.

Characteristic | Description
Required dependencies | IP Address resource
Required private properties | Name
Optional private properties | None

A Network Name resource type has two Name properties.

Property | Store
Name private property | The name that is published on the network as a "computer name.".
Name common resource property | The name of the resource itself.


Physical Disk

The Physical Disk resource type manages a disk on a shared bus connected to two or more cluster nodes. Most groups contain one or more Physical Disk resources as dependencies for other resources in the group.

The Physical Disk resource is the only default resource type that can operate as a cluster's quorum resource.

The following table summarizes the characteristics of the Physical Disk resource type.

Characteristic | Description
Required dependencies | None.
Required private properties | Signature
Optional private properties | ConditionalMount, DiskInfo, MountVolumeInfo, SkipChkdsk


Print Spooler

The Print Spooler resource type describes a network printer that applications access using a network IP address rather than an individual name. Each group can have only a single Print Spooler resource.

The following table summarizes the characteristics of the Print Spooler resource type.

Characteristic | Description
Required dependencies | Network Name resource, Physical Disk or other type of storage class resource
Required private properties | DefaultSpoolDirectory
Optional private properties | JobCompletionTimeout


WINS Service

The WINS Service resource type supports the Windows Internet Name Service (WINS) as a cluster resource. There can be only one instance of a resource of this type in the cluster; in other words, a cluster can support only one WINS Service.

The following table summarizes the characteristics of the WINS resource type.

Characteristic | Description
Required dependencies | Storage class resource, such as a Physical Disk
Required private properties | DatabasePath, BackupPath
Optional private properties | None


Display Names

It is important to distinguish between the display name of a resource type and the registered name of a resource type.

  • The display name of a resource type is the name that appears in the Cluster Administrator user interface. The display name can be changed through the Name property for resource types.
  • The registered name of a resource type is part of the resource type's internal definition as registered with the Cluster service when the resource type is first created (for more information, see Registering Resource Types). The names of predefined resource types (IP Address, Physical Disk, Generic Application, and so on) are examples of registered resource type names. The registered name of a resource type can be changed only by unregistering the resource type and registering it under a new name.


Cluster Object Properties

Properties are attributes that describe a cluster object. The values assigned to an object's properties determine the identity, location, and behavior of the object in the cluster.

Properties are distinguished by the following attributes:

  • Property scope (common, private, or unknown)
  • Property access (read-only or read/write)

For factors that may limit the size of individual properties, see Maximum String Size.

The Server Cluster API Reference provides several different structures and tools for working with cluster properties. For more information, see Data Structures, Lists, and Tables.


Property Scope

Given an object with a particular property, the scope of the property indicates whether other objects of the same type can be expected to possess the same property, and affects which APIs are used to work with the property.

The three different kinds of scope are described in the following sections:

Common Properties

Private Properties

Unknown Properties


Common Properties

A common property is an attribute possessed by every instance of a cluster object. For example, each node has a NodeName property, thus NodeName is a common property for nodes. Each resource has a RestartAction property; thus RestartAction is a common property for resources. An object's common properties exist for every instance of that object, regardless of how different the individual instances might be. For example, both a Physical Disk resource and a File Share resource possess a set of resource common properties, even though they are very different kinds of resources.

Common properties are always stored in the cluster database.

Common properties are defined by the Cluster service. End users and developers cannot add to or modify the set of common properties defined by a particular version of the Cluster service.


Private Properties

A private property is an attribute possessed by an individual instance of a cluster object. Other instances may or may not possess the same property.

Private properties are defined by the cluster software and by resource DLLs. End users and developers can create private properties for objects as needed. Private properties that are not created by the cluster or by a resource DLL are classified as unknown properties.

Private properties are further categorized as required or optional. If an object has a required private property, the property must have valid data before the object can be used. This may be a matter of verifying that the default value of the property is valid, or it may require an explicit assignment. For example, the Address property for IP Addresses resources is required. The resource cannot be brought online unless a valid IP address is stored in the Address property.

Optional private properties do not require a value.

The private properties for any cluster object reside in the cluster database under a "Parameters" key that is related to the identifier of the object. The following syntax illustrates a parameters key where <Object> refers to the name of the object and <ObjectID> refers to the object's identifier:

HKEY_LOCAL_MACHINE\Cluster\<Object>\<ObjectID>\Parameters


Unknown Properties

An unknown property is a private property that is not defined by the cluster software or by a resource DLL. Unknown properties cannot be read-only and cannot be required. Currently, any private property defined for a group, network, network interface, or node is an unknown property. A private property defined for a resource or resource type outside of the resource DLL that implements the resource type is also an unknown property.

Resource DLLs use the Cluster Utility Functions to work with unknown properties, specifically ResUtilAddUnknownProperties, ResUtilGetAllProperties, and ResUtilSetUnknownProperties.


Property Access

A property's access indicates the kinds of operations that can be used to change the value of the property. On the basis of access, properties can be divided into the following two groups:

Read-only properties

Read/Write properties


Read-only Properties

Read-only properties cannot be changed through the normal property manipulation API elements. For some read-only properties, there are specialized API elements that change the property indirectly. For example, the Name property for networks is read-only, but the cluster object management function SetClusterNetworkName has the effect of changing the property.

Do not try to force a change to a read-only property by direct manipulation of the cluster database. The result is likely to be an unusable cluster.


Read/Write Properties

Read/write properties are changeable through the normal property manipulation API elements.


Maximum String Size

For all string properties, the cluster imposes no restrictions on the size of the string that you use. It is possible to store megabyte-sized strings as cluster property values. However, the registry API recommends that data over 2048 KB in size (2 MB) should be stored in an external file. Other factors may also limit string size:

  • Available memory.
  • System limits such as MAX_PATH.
  • The ability of monitors and user interfaces to display the data properly.
  • Throughput and performance impact.

In general, megabyte-size strings stored as properties will adversely impact performance and usability. Physical Disk resources should be used for large-scale data storage.


The Server Cluster API

Windows Clustering provides a set of programming interfaces, collectively referred to as the Server Cluster API, which allow developers to write applications, and resource DLLs for server clusters. The Server Cluster API is defined to be the set of all programming interfaces published in the following files:

Cluadmex.h
Cluadmex.idl
Cluadmex.lib
Clusapi.h
Clusapi.lib
Resapi.h
Resutils.lib

To conceptually and functionally distinguish different elements of the Server Cluster API, this documentation categorizes the files and their contents into distinct subsets. For additional information on these categories, refer to the following sections.

API subset | Functional category
Cluster API | Working directly with cluster objects and interacting with the Cluster service.
Resource API | Managing resources through a Resource Monitor and a resource DLL.
Cluster Administrator Extension API | Enabling a custom resource type to be administered by Cluster Administrator.


Cluster API

The Cluster API, defined in clusapi.h and clusapi.lib, provides the programming elements necessary to work directly with cluster objects and interact with the Cluster service.

The Cluster API is not available until the Cluster service has started. Resource DLLs should take this into account and use the Resource API for operations that might take place in the absence of the Cluster service.

The Cluster API is divided into the following subsets:

  • Cluster Database Access Functions
  • Cluster Object Management Functions
  • Control Code Functions
  • Control Codes
  • Data Structures


Resource API

The Resource API defines interfaces that allow the Cluster service to manage resources through a Resource Monitor and a resource DLL. The Cluster service initiates requests with a Resource Monitor, and the Resource Monitor passes the requests to the resource. Status and event information are passed back from the resource DLL to the Cluster service.

Unlike the Cluster API, the Resource API is always available. Resource DLLs should use the Resource API whenever possible to isolate themselves from Cluster service failures.

The Resource API includes definitions for the following:

Resource DLL Functions

Cluster Utility Functions

Resource DLL Structures


Cluster Administrator Extension API

The Cluster Administrator Extension API defines interfaces based on the Component Object Model (COM) and functions that enable a custom resource type to be administered by Cluster Administrator. The interfaces are used by Cluster Administrator extension DLLs, and the functions are used to communicate with the Cluster Administrator.

The Cluster Administrator Extension API consists of cluadmex.idl, cluadmex.h, cluadmex.tlb and includes definitions for the following:

  • Cluster Administrator Extension Interfaces
  • Cluster Administrator Extension Registration Functions


Server Cluster Application Types

Use the following application types as a guide to determine how your application, service, or device needs to interact with server clusters.

Application type | Description
Cluster-unaware applications | Applications that do not interact with the cluster at all.
Cluster-aware applications | Applications that achieve optimal performance by implementing awareness of the cluster environment, allowing them to react to cluster events.


Cluster-Unaware Applications

A cluster-unaware application is distinguished by the following features:

  • The application does not use the Server Cluster API. Therefore, it cannot discover information about the cluster environment, interact with cluster objects, detect that it is running in a cluster, or change its behavior between clustered and non-clustered systems.
  • If the application is managed as a cluster resource, it is managed as a Generic Application resource type or Generic Service resource type. These resource types provide very basic routines for failure detection and application shutdown. Therefore, a cluster-unaware application might not be able to perform the initialization and cleanup tasks needed for it to be consistently available in the cluster.

Most older applications are cluster-unaware. However, a cluster-unaware application can be made cluster-aware by creating resource types to manage the application. A custom resource type provides the initialization, cleanup, and management routines specific to the needs of the application.

There is nothing inherently wrong with cluster-unaware applications. As long as they are functioning and highly available to cluster resources when managed as Generic Applications or Generic Services, there is no need to make them cluster-aware. However, if an application does not start, stop, or failover consistently when managed by the generic types, it should be made cluster-aware.


Cluster-Aware Applications

An application is capable of being cluster-aware if it has the following characteristics:

  • It uses TCP/IP as a network protocol.
  • It maintains data in a configurable location.
  • It supports transaction processing.

Most database applications, transaction processing applications, file and print server applications, and other groupware applications are capable of being made cluster-aware.

There are two types of cluster-aware applications:

  • Applications that are managed as highly available cluster resources by a custom resource type. If you want your application to be highly available, to fail over, to benefit from customized failure detection policies, or to be made available to clients on a virtual server, your application needs to be managed as a cluster resource. This means that in addition to any cluster-awareness you want to add to the application, you will need to create a custom resource type to manage the application. For more information, see Creating Resource Types
  • Applications that interact with the cluster but are not cluster resources. Cluster Administrator is an example of such an application. This category also includes cluster-aware performance monitors, configuration tools, setup applications, event handlers, and cluster management applications.

To create a cluster-aware application, review the following tasks and determine what kinds of interactions your application needs to implement:

  • Receiving cluster events
  • Getting cluster information
  • Changing the cluster configuration

The following table presents examples of different kinds of cluster-aware applications and the event, information, and configuration tasks you may want to implement for such applications.

Cluster-aware application | Event tasks | Information tasks | Configuration tasks
A cluster-aware setup application. | None. | Detect the cluster version, list the nodes in the cluster, and list the available disks. | Create and configure a test group.
A remote failover monitor and performance tracker | Any events involving group or resource state changes or movement | List the nodes in the cluster, the groups on each node, and the resources in each group. Retrieve group and resource properties, especially those relating to times and intervals. | None (a read-only interface).
A resource configuration wizard | None. | Be able to provide feedback and verification on the changes the user is making. | Back up the cluster database, create a group, create resources, change properties, create dependencies, change owner node lists, create registry and crypto checkpoints, and change states.


Cluster Management Applications

A cluster management application is a type of cluster-aware application designed to provide a user interface for monitoring or controlling at least one aspect of a server cluster. This covers a wide range of functionality, from single-purpose monitoring tools that simply display status information about one or more cluster objects, to full-featured administration interfaces such as Cluster Administrator and Cluster.exe.

To create a cluster management application:

  • Choose between the Cluster Automation Server and the Server Cluster API as the basis for your application. Note that the Cluster Automation Server currently does not provide access to cluster events (see Receiving Cluster Events).
  • Decide what aspects of the cluster you want to expose to users. For example, you might want to create a "read-only" interface that only allows users to monitor information about the cluster.
  • Review the following tasks and determine what kinds of interactions your application needs to implement:
    • Receiving cluster events
    • Getting cluster information
    • Changing the cluster configuration


Custom Resource Types

You may develop or encounter resources that require, or at least benefit from, specialized management routines not provided by any existing resource types. For those kinds of resources, you should create a custom resource type.

You can create a custom resource type to:

  • Support a new type of resource. For example, you could use a new type of storage device as the quorum resource by creating a custom resource type for the device. A new resource type can also be created to manage one or more cluster-aware applications.
  • Augment or replace one of the predefined resource types to add functionality. For example, you might have a set of cluster-unaware, mission-critical legacy applications that need more careful management than the Generic Application resource type can provide. You could create a Generic Application resource type wrapper to specifically handle the applications.

A custom resource type provides the following benefits:

  • It ensures that the resource has everything it needs before bringing the resource online.
  • It adjusts how the Cluster service checks the status and detects the failure of your resource.
  • It supports private properties and other parameters specific to the resource.
  • It implements graceful shutdown routines, allowing the resource to perform cleanup tasks before termination.
  • It enables event and error logging for the resource.
  • It maintains awareness of cluster events. For example, the Cluster service will notify a resource DLL if the Cluster service version has changed due to an upgrade or uninstall, but only a custom resource type designed to detect this notification can respond appropriately.

Together, the benefits of a custom resource type result in highly available cluster resources.

For information on how to generate, customize, and register a resource type, see Creating Resource Types.


When To Create a Resource DLL

One of the most common questions about cluster programming is:

  • Should I create a resource DLL to manage my [application or other resource], or can I use the Generic Application or Generic Service resource type?

This section is intended as a guide toward answering that question. For procedures and examples of creating a resource DLL, see Creating Resource Types.

To answer the question, keep in mind that one of the goals of clustering is high availability of resources. Server clusters depend on resource DLLs to maintain resource availability. Resource DLLs do the actual work of bringing resources online, taking resources offline, checking for failure, processing control codes, and performing other management tasks.

Therefore, the question of whether to create a resource DLL can be rephrased as follows:

Can the Generic Application or Generic Service resource types maintain high availability for my resource?

The Generic Application and Generic Service resource types provide very basic implementations of the entry point functions. They start and stop their resources simply by starting and terminating a process, and look for resource failure by checking if the process still exists. They do not support resource-specific private properties or user-defined control codes.

Use the following checklist to determine whether you need to create a resource DLL:

  • If your resource is a device, you should create a resource DLL. This is especially true of storage class devices. The Generic resource types are not designed to manage hardware.
  • If your resource is an application or service, you should create a resource DLL if any of the following statements are true:
    • The resource depends on other resources, such as storage class devices, file shares, and so on.
    • The resource manages critical transaction-based or state-dependent data.
    • The resource requires special initialization procedures.
    • The resource requires special shutdown or emergency termination procedures.
    • The resource has unique attributes that would be best managed as private properties.
    • The resource offers special functionality that you want to expose through a user-defined control code.

If your resource is stateless, has no dependencies or special functionality, and can be started and stopped easily, then the Generic Application or Service resource type is adequate for managing the resource. Otherwise, to ensure high availability, you should create a resource DLL. For procedures and examples, see Creating Resource Types.


Data Structures, Lists, and Tables

The Server Cluster API defines a number of ways to arrange multiple heterogenerous values (such as string and DWORD values) in the same buffer, and to assign a meaning or context to each value (such as a property name or a list terminator). This allows complex sets of data, such as the properties of a typical object, to be arranged in a buffer and passed as a single unit between functions.

The following sections describe the architecture of data structures, lists, and tables.

About Data Structures

Value Lists

Property Lists

Parameter Blocks

Property Tables


About Data Structures

The Server Cluster API defines a number of data structures that are used as building blocks of value lists. A data structure acts as a "header" for an area of memory, describing the type and length of the data that follows. A data structure consists of the following members:

  • A Syntax member describing the format and type of the data value.
  • A Length member describing the byte size of the data value.
  • A data value member holding the data.

This architecture is shown in the following diagram:

When "stacked" contiguously in a buffer, data structures allow parsing routines to search for specific data values by reading the Syntax member, and advance past blocks of data by using the Length member.

Note that the Syntax and Length members are actually members of the CLUSPROP_VALUE structure. The definition of each data structure in clusapi.h includes a CLUSPROP_VALUE structure. Therefore, the actual architecture of a data structure consists of the following:

  • A CLUSPROP_VALUE member
  • A data value member

However, when describing and using data structures, it is more convenient to refer to the Syntax and Length members explicitly as if they were data structure members.

For more information on each of these members, refer to the following sections:

Data Syntax

Data Length

Data Value


Data Syntax

The Syntax member of a data structure describes the type of data stored in the value member. The Syntax member is a CLUSPROP_SYNTAX union that describes data in one of two ways:

  • As two WORD values with one value describing the format of the data and the other describing the data type. When Syntax is specified this way, the values are combined into a single DWORD at run time.
  • As a single DWORD value combining the format and type at compile time.

If there is no single DWORD value defined that describes the data, you must use a combination of format and type. For example, user-defined types must be described as a combination of format and type. Otherwise you can use either method of describing the data.


Data Length

The Length member of a data structure describes the actual byte size of the data stored in the value member. For strings, the byte size must always include the terminating NULL. The byte size does not include the size of the Syntax or Length members, and does not include extra bytes used as padding between entries in a value list.


Data Value

The Value member of a data structure contains or points to the actual data. The value may take the form of a structure or array, in which case the value is actually a collection of smaller values.


Value Lists

A value list is a block of memory containing a sequence of data structures. Value lists are used as the building blocks of property lists and as return values for some control code operations.

Each data structure in the value list must be DWORD-aligned. It is a good idea to zero the memory of your value list buffer before building the list so that bytes used for padding do not contain misleading values.

To mark the end of a value list, the last entry in the list contains only the Syntax member of a data structure set to CLUSPROP_SYNTAX_ENDMARK. The last entry has no Length member and no data. The following diagram shows the layout of a value list:

For more information on how to build and read value lists, see Using Value Lists.


DWORD-aligned

Each data structure in a value list must begin on a DWORD boundary. This means that the distance (in bytes) between the start of the value list buffer and the start of any data structure is always an even multiple of sizeof( DWORD ).

If a data structure contains variable length data, you might have to advance a few extra bytes before adding the next data structure in order to ensure DWORD-alignment (see the diagram in Value Lists). Use the ALIGN_CLUSPROP macro to calculate the correct alignment size.

The extra bytes lying between data structures in a value list are referred to as "padding."

Note that the Length member of the data structure should specify the actual size of the data, not the size returned by ALIGN_CLUSPROP. For more information and examples of using ALIGN_CLUSPROP, see Using Lists and Tables.


Value Lists for Storage Class Resources

The CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO and CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control codes return value lists describing storage class resources.

A single storage class resource is described by a value list entry consisting of one or more data structures, as follows:

  1. The value list entry must always begin with a CLUSPROP_DISK_SIGNATURE structure specifying the signature of the storage class resource.
  2. The value list entry may contain the following structures in any order:
    • A CLUSPROP_SCSI_ADDRESS structure describing the SCSI address of the storage class resource (if applicable).
    • A CLUSPROP_DISK_NUMBER structure specifying the disk number of the storage class resource (if applicable).
    • One CLUSPROP_PARTITION_INFO structure for each drive letter or partition assigned to the storage class resource (if applicable).

The value list returned from CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO describes information about a single storage class resource and thus contains only one of these entries terminated by CLUSPROP_SYNTAX_ENDMARK.

The value list returned from CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS describes information about a multiple storage class resources as a series of such entries, with the entire series terminated by CLUSPROP_SYNTAX_ENDMARK. Each CLUSPROP_DISK_SIGNATURE structure marks the start of a new entry and identifies the storage class resource described by the entry. Thus the CLUSPROP_DISK_SIGNATURE structure acts like an index or key when the list is parsed.


Property Lists

A property list is a block of memory containing a sequence of value lists. Property lists are used as input and output parameters of many control code functions and utility functions.

A property list consists of the following elements:

  • A count of the properties in the list, represented by a CLUSPROP_LIST structure.
  • One value list for each property.
  • Each property value list, in turn, consists of the following entries:
  • A property name represented by a CLUSPROP_PROPERTY_NAME structure.
  • A property value, represented by a data structure appropriate to the type of data being stored. The property value can consist of multiple data values, such as an array or a structure.
  • Additional property values, if necessary. Each property value is represented by a data structure and can consist of multiple data values.
  • A CLUSPROP_SYNTAX union set to CLUSPROP_SYNTAX_ENDMARK.

Typically, the value list for a property contains only one property value. It is possible, however, to have a multi-valued property. When writing code to parse property lists, don't assume there will be only one property value.

The following diagram illustrates the layout of a property list.

For information on creating and parsing property lists, see Using Property Lists.


Parameter Blocks

A parameter block is a user-defined structure that stores the data, or pointers to the data, for one or more property values. Property tables use parameter blocks for data storage. Each property table entry specifies an offset to a member of a parameter block.

Because property tables use offsets to access parameter block data, there are no design constraints on parameter blocks. They can list their members in any order and can include any data, not just property data as members.

For a code example, see Using Parameter Blocks.


Property Tables

A property table is an array of RESUTIL_PROPERTY_ITEM structures. Each entry in a property table contains information about a particular property and an offset to the property's data. The data, or a pointer to the data, is stored in a parameter block.

The following illustration shows the relationship between a property table and a parameter block. The property table has two entries, each represented by a RESUTIL_PROPERTY_ITEM structure. The Offset member of each property-table entry points to a member in the parameter block. Notice that non-property table data is included in the parameter block.

The type of data stored in the Default, Minimum, and Maximum members as well as in the corresponding parameter block depends on the value of the Format member. The following list indicates the relationship between the Format member and the type of data in the Default member and parameter block.

Format member | Default member | Parameter block
CLUSPROP_FORMAT_BINARY | Pointer to a buffer if the value is non-NULL. | LPBYTE pointing to the data followed by a DWORD to indicate the size of the data in bytes.
CLUSPROP_FORMAT_DWORD | DWORD | DWORD
CLUSPROP_FORMAT_EXPAND_SZ | Pointer to a NULL-terminated Unicode string if non-NULL. | LPWSTR
CLUSPROP_FORMAT_MULTI_SZ | Pointer to a buffer if the value is non-NULL. | LPWSTR pointing to the data followed by a DWORD to indicate the size of the data in bytes.
CLUSPROP_FORMAT_SZ | Pointer to a NULL-terminated Unicode string if non-NULL. | LPWSTR

For a discussion of creating and parsing property tables, see Using Lists and Tables.


About Control Codes

A control code is a 32-bit value that identifies an operation or an event. The Server Cluster API defines a small number of general-purpose functions that take control codes as input parameters. This design allows hundreds of different operations to be handled by a few basic algorithms, and provide an extensible architecture for defining new types of operations.

The following sections describe the different types of control codes, how they are used, and their underlying architecture:

Topic | Information
How Control Codes are Used | Describes the types of tasks associated with control codes.
External Control Codes | Describes how applications and resource DLLs use external control codes as control code function parameters to initiate operations on cluster objects.
Internal Control Codes | Describes how the Cluster service uses internal control codes to notify resource DLLs of certain cluster events.
Control Code Architecture | Describes the bit fields used to define control codes

For code examples, see Using Control Codes.

For lists and descriptions of the control codes defined by the Server Cluster API, see the Control Code Reference.


How Control Codes are Used

Control codes define operations and events. There are two basic tasks associated with using control codes:

  • Initiating control code operations. Both cluster-aware applications and resource DLLs can initiate control code operations by calling control code functions, although resource DLLs should use caution when doing this. For more information on initiating control code operations, see External Control Codes.
  • Responding to control code operations and events (resource DLLs only). The Cluster service passes some control codes to resource DLLs. Depending on the operation or event defined by the control code, a resource DLL may be required to carry out the requested operation or respond to the event. If a resource DLL implements procedures in response to a control code, the DLL is said to support the control code.


External Control Codes

External control codes define operations that can be performed on cluster objects. Cluster-aware applications and resource DLLs initiate external control code operations by calling control code functions.

Control code functions are general-purpose routines with multiple parameters that provide the framework for control code operations. The configuration and content of these parameters depend on the control code being used. The following pseudocode illustrates the parameters of a control code function.

Return Value =
ControlCodeFunction
(
    Object Handle,        // for resource types, 2 parameters: cluster handle and resource type name
    Optional Node Handle,
    Control Code,
    Input Buffer,
    Size of Input Buffer,
    Output Buffer,
    Size of Output Buffer,
    Size of the Resulting Data
);
Object Handle
For all cluster objects except resource types, this parameter will be a handle to the cluster object. For resource type, this is two parameters: a cluster handle and the resource type name.
Optional Node Handle
If you want to specify a particular node to actually perform the operation, pass a handle to that node, otherwise pass NULL.
Control Code
The control code for the operation.
Input Buffer
Pointer to a buffer containing data required for the operation, or NULL if no data is required. Refer to the control code to find out whether data is required and how the data should be formatted. You must allocate and free the memory for the buffer.
Size of Input Buffer
The size, in bytes, of the input buffer, or 0 if no input is needed.
Output Buffer
Pointer to a buffer containing data resulting from the operation, or NULL if no data is required. You must allocate a buffer and pass it to the function. If the buffer is too small to hold the data, the last parameter ("size of the resulting data" will specify the required size, allowing you to reallocate and try again. Refer to the control code to find out whether data is required and how the data should be formatted.
Size of Output Buffer
The allocated size, in bytes, of the output buffer, or 0 if no output will be generated.
Size of the Resulting Data
The control code function will specify the size of the data resulting from the operation. If the output buffer was too small to hold the data, use this value to reallocate the buffer and call the function again.
Return Value
Always a DWORD, the possible values differ from control code to control code. Refer to the control code for the values to expect.

Some control code operations require input data; others generate output data. The data can take the form of strings, arrays, or more complicated configurations such as property lists. What you pass into and expect out of a control code function is determined by the control code.

Therefore, to use a control code in a control code function, you need to know the following:

  • What the control code does.
  • What parameters must accompany the control code.
  • What the possible return values are.

The Control Code Reference describes this information for each control code. However, there are standard patterns or configurations of parameters that result in a small set of calling conventions. For more information, see Using Control Codes.


Internal Control Codes

Internal control codes are used exclusively by the Cluster service to notify resource DLLs of certain events. Applications cannot use internal control codes in control code functions.

If you are implementing a resource DLL, you can choose to support any internal control code that indicates an event with implications for your resources. However, note the following behavior:

  • Unless otherwise specified in the description of the control code, internal resource control codes are sent to every resource in the cluster. This means your ResourceControl entry point will receive one call for every resource currently supported by your DLL.
  • Unless otherwise specified in the description of the control code, internal resource type control codes are sent to every resource type in the cluster. This means your ResourceTypeControl entry point will receive one call for every resource type supported by your DLL.

For example, suppose a resource DLL supports three resource types and is currently managing five resource instances in the cluster. The administrator evicts a node. The resource DLL will receive the CLUSCTL_RESOURCE_TYPE_EVICT_NODE control code three times (one call per resource type) through the ResourceTypeControl entry point, and will receive the CLUSCTL_RESOURCE_EVICT_NODE control code five times (one call per resource instance) through the ResourceControl entry point.


Control Code Architecture

If you want to create your own control codes, you will need to refer to the information in this section. You do not need to know how control codes are defined in order to use them in control code functions. However, understanding the internal architecture of control codes can help you use them more efficiently.

Control codes consist of seven smaller numbers arranged to form a 32-bit value. The bit layout is shown in the following illustration:

Object Code (bits 24-31)

The 8-bit object component indicates the type of cluster object to which the control code applies. Possible values:

CLUS_OBJECT_GROUP

CLUS_OBJECT_NETWORK

CLUS_OBJECT_NETINTERFACE

CLUS_OBJECT_NODE

CLUS_OBJECT_RESOURCE

CLUS_OBJECT_RESOURCE_TYPE

CLUS_OBJECT_USER

All of the values except CLUS_OBJECT_USER represent object types defined by Windows Clustering.

Global Bit (bit 23)

The global bit indicates whether the control code represents a global operation that must be performed on each cluster node. Currently, CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS is the only global control code. It's possible values are the following:

  3. CLUS_NOT_GLOBAL
  4. CLUS_GLOBAL

Modify Bit (bit 22)

The modify bit indicates whether the control code causes a modification to data that, in turn, may generate an event notification. Possible values:

CLUS_NO_MODIFY

CLUS_MODIFY

User Bit (bit 21)

The user bit indicates whether the control code is user-defined or defined by Windows Clustering. Possible values:

CLCTL_CLUSTER_BASE

CLCTL_USER_BASE

Internal/External Bit (bit 20)

The internal/external bit categorizes the control code as either internal or external. Internal control codes set this bit; external control codes do not. An internal control code can be used only by the Cluster service, meaning that applications cannot pass internal control codes as parameters to the control functions of the Cluster API. Internal control codes are typically sent by the Cluster service to notify a resource or resource type of an event. The external control codes are used by applications to initiate an operation. Their possible values are the following:

CLCTL_EXTERNAL_CODE

CLCTL_INTERNAL_CODE

Operation Code (bits 2-19)

The operation code describes the operation that a control code will perform. The procedures for using control codes that have different object codes but the same operation code are nearly identical. For more information see Using Control Codes.

The following operation codes apply to all or most cluster objects:

CLCTL_ENUM_COMMON_PROPERTIES

CLCTL_ENUM_PRIVATE_PROPERTIES

CLCTL_GET_CHARACTERISTICS

CLCTL_GET_COMMON_PROPERTIES

CLCTL_GET_FLAGS

CLCTL_GET_ID (not for resources or resource types)

CLCTL_GET_NAME

CLCTL_GET_PRIVATE_PROPERTIES

CLCTL_GET_RO_COMMON_PROPERTIES

CLCTL_GET_RO_PRIVATE_PROPERTIES

CLCTL_SET_COMMON_PROPERTIES

CLCTL_SET_PRIVATE_PROPERTIES

CLCTL_UNKNOWN

CLCTL_VALIDATE_COMMON_PROPERTIES

CLCTL_VALIDATE_PRIVATE_PROPERTIES

Clusapi.h defines other operation codes that are object-specific, particularly for resources and resource types.

Access Code (bits 0-1)

The access code indicates whether the initiator of the request requires any specific type of access to perform the operation described by the operation code. Possible values:

CLUS_ACCESS_ANY

CLUS_ACCESS_READ

CLUS_ACCESS_WRITE


The Cluster Configuration Interfaces

The Cluster Configuration architecture is a new feature in Whistler. When a node joins, forms, or is evicted from the cluster, the cluster notifies registered components on the node. You can use the Cluster Configuration Interfaces to create these components and implement customized setup, upgrade, and uninstall procedures for your cluster-aware applications. For example, when a cluster is being formed you can create and register resource types and configure initial resources and groups. You can provide feedback to the user through the Cluster Configuration Wizard. The Cluster Configuration Interfaces allow you to integrate your setup and configuration tasks with those of the cluster.

See Cluster Configuration Reference.


The Cluster Automation Server

The Cluster Automation Server provides a set of Automation objects that expose a complete cluster management interface to scripting languages, allowing you to develop web-based remote administration tools. The Cluster Automation Server simplifies and enhances the process of creating a cluster management application.

For information on how to program with the Cluster Automation Server, see Using Cluster Automation Server.

For descriptions of the Cluster Automation Server objects and their properties and methods, see the Cluster Automation Server Reference.


Cluster Automation Server Scripts

The Cluster Automation Server provides a set of objects that facilitate monitoring and administering multiple clusters in multiple domains. Scripting with the Cluster Automation Server objects allows you to create dynamic, web-based interfaces and controls that dramatically extend and enhance the range of remote cluster administration.

When creating a Cluster Automation Server script, you will find the following sources of information helpful:

  • If you are not familiar with the subject of scripting, especially scripting with COM objects, refer to the sources in Further Information.
  • To understand how a server cluster operates, refer to the Cluster Automation Server object model, which mirrors the architecture of a server cluster. See the following sections:

    Server Cluster Software Components

    Cluster Objects

    Cluster Properties

  • To make sure your development environment is configured properly, see Preparing a Development Environment.
  • When creating your scripts, see the following sections for examples and reference information:

    Object Hierarchy

    Programming With Cluster Automation Server

    Cluster Automation Server Reference

    Creating a Cluster Automation Server Script


Recommendations and Cautions

The following information applies to all cluster programming tasks:

Follow the Standard Order of Preference when selecting an API to use.
The various subsets of the Server Cluster API sometimes present you with multiple ways to do the same thing. The standard order of preference describes how to choose the best API for your type of application.
Do not use any registry functions that are not part of the Server Cluster API on any cluster database keys.
They will corrupt the data and make the cluster unusable. Only the Server Cluster API can work with the cluster database safely. This applies only to keys in the cluster hive (HKEY_LOCAL_MACHINE\CLUSTER), not to checkpointed registry keys external to the cluster database.
Refresh often and use caution when working with property values.
Keep in mind the possibility that a new value has been written to a property immediately after you read or write the old value (see Multiple and Simultaneous Property Updates). Refresh local property data before relying on a specific value.
Do not mix LPC and RPC handles in the same API call.
If an API takes more than one cluster object handle as a parameter, be sure that all handles are RPC or that all handles are LPC. Mixing handle types results in an RPC exception and may have other unpredicatable results. For more information, see LPC and RPC Handles.
Close handles after deleting objects
The DeleteClusterResource and DeleteClusterGroup functions do not close the handles to the deleted objects. To avoid memory leaks, call CloseClusterResource and CloseClusterGroup on the handles to the deleted objects.
Note which API elements express string sizes as counts of characters and which express string sizes as counts of bytes.
For more information see Data Size Conventions.


Data Size Conventions

The Server Cluster API uses the following conventions when returning and receiving data sizes:

  • Function parameters that contain the prefix cb express sizes as a count of bytes. For strings, this size includes the terminating NULL.
  • Function parameters that contain the prefix cch express sizes as a count of characters. For strings, this size may or may not include the terminating NULL. The function description will indicate when to include the NULL in the count.

Note that the Server Cluster API uses Unicode (multi-byte) strings. Therefore the byte count of a string buffer will not be the same as the count of characters in the string.


Multiple and Simultaneous Property Updates

When you use a single function call to set multiple properties for a single object, the cluster applies the changes as follows:

  • For networks and network interfaces, the change is applied as a single atomic unit. Either all of the property changes will be applied or none will be applied.
  • For groups, nodes, resources, and resource types, the change is not atomic. If a problem occurs during processing, the results are unpredictable. Some or none of the properties may be changed.

When the cluster receives simultaneous property change requests from multiple nodes, it applies the changes as follows:

  • For networks and network interfaces, each change is applied individually as an atomic unit. One request will either succeed or fail, then the next will succeed or fail, and so on. The order in which the requests are resolved is first come, first served.
  • Simultaneous property changes to groups, nodes, resources, and resource types are applied in an unpredictable order. For changes involving multiple properties, the order of resolution can change from property to property.

For example: Application A on Node A requests that Group N's AutoFailBackType and PersistentState properties be set to value A. At the same time, Application B on Node B requests that the same properties be changed to value B. Each individual property change request can be resolved in any order, resulting in the following possible outcomes.

Result of A's request | Result of B's request | Final value of AutoFailbackType | Final value of PersistentState
Error | Error | A | B
Error | Error | A | no update
Error | Error | B | A
Error | Error | B | no update
Error | Error | no update | A
Error | Error | no update | B
Error | Error | no update | no update
Error | Success | A | B
Error | Success | B | B
Error | Success | B | A
Success | Error | A | A
Success | Error | A | B
Success | Error | B | A
Success | Success | A | A
Success | Success | A | B
Success | Success | B | A
Success | Success | B | B

Be sure to verify the results of a property change before relying on the value of the property in subsequent operations.


LPC and RPC Handles

Most of the operations implemented by the Server Cluster API take object handles as parameters. The Cluster API creates two different types of object handles:

  • Handles created using local procedure calls (LPC handles).
  • Handles created using remote procedure calls (RPC handles).

To obtain any cluster object handle, the first step is acquiring a handle to the cluster that contains the object. How that handle is obtained determines the type of handles that can be obtained from it:

  • If NULL is passed to the OpenCluster call, the Server Cluster API creates an LPC cluster handle. All object handles created with that handle are LPC.
  • If a name is specified in the OpenCluster call, the Cluster service creates an RPC cluster handle. All object handles created with that handle are RPC.

If the Cluster service fails on a node, LPC handles to objects that fail over become invalid, while RPC handles to the same objects remain valid. For example, an LPC handle to a group will become invalid if the group fails over due to a failure of the Cluster service, but an RPC handle will remain valid.

Some Server Cluster API functions take more than one object handle as input parameters. Mixing LPC and RPC handles in the same call will generate an exception at minimum and can have other unpredictable effects. When using functions that take multiple object handles as parameters, be very certain that all handles are either LPC or RPC.

The following functions require multiple object handles:

  • AddClusterResourceDependency
  • AddClusterResourceNode
  • All Control Code Functions
  • CanResourceBeDependent
  • ChangeClusterResourceGroup
  • OnlineClusterGroup
  • RemoveClusterResourceDependency
  • RemoveClusterResourceNode
  • ResUtilResourcesEqual
  • SetClusterGroupNodeList
  • SetClusterNetworkPriorityOrder


Standard Order of Preference

The Server Cluster API may offer more than one way of performing a cluster operation. For example, the PendingTimeout property for a resource can be set through the following API elements:

ClusterResourceControl with the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code.

ResUtilSetPropertyParameterBlock

ResUtilSetPropertyTable

ClusterRegSetValue

If the Server Cluster API offers more than one way of performing an operation on a cluster object, the following orders of preference is recommended.

For cluster-aware applications

  1. Use a control code function whenever possible. This maximizes the reliability and security of the operation, and ensures that resource DLLs receive proper notification.
  2. Use a cluster object management function if a control code operation is not possible.
  3. Use a utility function.
  4. Use a cluster database access functions as a last resort.

In general:

  • Try not to perform direct updates to the cluster database unless absolutely necessary.

A change to the cluster database typically has an impact on many different cluster elements. Using "indirect" API elements allows the Cluster service to ensure that the necessary notifications take place, and that the data is replicated to all nodes.

For resource DLLs

  1. Use a cluster utility function or a cluster database access function (a "ResUtil" function). A resource DLL is expected to access the cluster database, unlike a cluster-aware application.
  2. Use a control code function (but see Cautions).
  3. Use a cluster object management function.

In general:

  • Try not to use the Cluster API unless absolutely necessary.

The Server Cluster API is not always available to resource DLLs because it depends on the Cluster service. The Resource API, however, is always available to resource DLLs.


Using the Server Cluster API

The Server Cluster API is intended to support a wide variety of programming needs, from adjusting an application so it fails over gracefully, to creating a resource DLL for managing a new type of storage device, to creating a complete cluster management interface.

Topic | Tasks
Performing Common Tasks | Preparing a development environment, using the inline examples, using lists and tables, using control codes, using object handles.
Creating Cluster-Aware Applications | Receiving cluster events, getting cluster information, changing the cluster configuration
Creating Resource Types | Generating a resource type, implementing a resource DLL, debugging a resource type
Creating Cluster-Aware Setup Applications | How to use setup applications to install new resource types in a cluster.


Performing Common Tasks

Refer to the following sections:

Preparing a Development Environment

Using the Inline Examples

Using Lists and Tables

Using Control Codes

Using Object Handles


Preparing a Development Environment

Use the following checklist to configure a development environment suitable for server cluster programming:

  1. Meet minimum platform, version, and IDE requirements
    • The following platforms support server clusters: Microsoft® Windows NT® Server Enterprise Edition version 4.0 SP3, Microsoft Windows® 2000 Advanced Server, or Microsoft Windows 2000 Data Center. A production-caliber server cluster has specific hardware requirements that must be met. However, it is possible to develop code on systems that do not meet these requirements, but at some point such code should be tested on a production-level system. For information on hardware requirements, refer to the Windows NT/Windows 2000 online Help documentation.
    • Microsoft® Visual C++® version 5.0 or later with the Unicode MFC libraries.
    • The Active Template Library (ATL) version 2.0 or later.
    • If you will be using Microsoft® Visual Basic® with the Cluster Automation Server, verify that you have Microsoft Visual Basic version 4.0 or later installed.
  2. Include the necessary headers and libraries in your code.
    • For information on the server cluster header and library files, see Subsets of the Server Cluster API.
    • For example C/C++ code that creates a suitable runtime environment, see ClusDocEx.h.
    • If you will be using a scripting language with the Cluster Automation Server, make sure your script references the GUID of the MSCLUS type library as shown in the following example:
      <REFERENCE GUID="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" VERSION="1.0" />
  3. Prepare for debugging
    • Use WinDbg or any other standard Microsoft Windows operating system-based debugger.
    • Register the DEBUGEX Cluster Administrator extension DLL. When DEBUGEX is registered, the Debug tab appears as one of the tabs on the resource and resource type property sheets of Cluster Administrator. This allows you to use Cluster Administrator to turn debugging on and off on a resource-by-resource basis or for all resources of a particular type. To register DEBUGEX , enter:
      cluster /regadminext:debugex.dll
    • Copy the symbol files from the \Symbols directory on the Platform SDK CD-ROM to your %windir%\Symbols directory.
    • If you are debugging a resource DLL, copy any .pdb files for your resource DLL to the same location as your resource DLL.
  4. Enable the cluster log. The cluster log is a very useful troubleshooting tool. When enabled, the log records the actions of each component of the Cluster service as well as the results of each action. The log can help you pinpoint the source of errors and unexpected behavior. The cluster log is enabled by default. For more information, see the Windows NT/Windows 2000 online Help documentation.


Using the Inline Examples

This documentation makes a distinction between code examples and code samples:

  • Code examples are embedded in many topics of the Server Cluster documentation. Code examples are typically task-oriented, single-purpose procedures.
  • A code sample is one or more independent project files that are installed in the samples directory. Typically, code samples are fully-functional applications consisting of several files.

The following conventions apply to all inline code examples provided by the Server Cluster documentation:

  • Most functions, macros, structures, constants, filenames, and other named objects defined by the documentation itself are prefixed by "ClusDocEx" (cluster documentation example). Any code object whose name begins with "ClusDocEx" should not be considered part of the Server Cluster APIs.
  • Wherever possible, each example is presented as one or more complete, single-purpose functions that accomplish one task.
  • The functions are designed to be modular, allowing you to cut and paste them in various combinations to perform larger tasks.

Refer to the following sections:

  • For an index of links to the inline examples, see Index of Examples.
  • If you want to cut, paste, and compile and run an inline example, see ClusDocEx.h.


Index of Examples

The following table lists all of examples in this documentation by name and identifies the topics in which they are shown.

Example function name | Topic title
ClusDocEx_BasicPropertyValueList | Building with CLUSPROP_BUFFER_HELPER
ClusDocEx_ConvertArg | ClusDocEx.h
ClusDocEx_CreatePropertyListEntry | Creating Property Lists
ClusDocEx_CreateRequiredDependenciesList | Creating Value Lists
ClusDocEx_CreateValueListEntry | Building with CLUSPROP_BUFFER_HELPER
ClusDocEx_DebugPrint | ClusDocEx.h
ClusDocEx_EventMessage | Notification Port Example
ClusDocEx_EventPort | Notification Port Example
ClusDocEx_FindSyntax | Parsing with CLUSPROP_BUFFER_HELPER
ClusDocEx_GrpCreatePropertyList | Creating Property Lists
ClusDocEx_GrpCreateVirtualServer | Creating Virtual Servers
ClusDocEx_GrpEnumResources | Enumerating Objects
ClusDocEx_GrpGetControlCodeOutput | Getting Information with Control Codes
ClusDocEx_GrpGetRWCDwPropValue | Parsing Property Lists
ClusDocEx_GrpResetPropertyDefaults | Setting Properties
ClusDocEx_IsGroupProperty | CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES
ClusDocEx_ListEntrySize | ClusDocEx.h
ClusDocEx_NetGetControlCodeOutput | Getting Information with Control Codes
ClusDocEx_NICGetControlCodeOutput | Getting Information with Control Codes
ClusDocEx_NodGetControlCodeOutput | Getting Information with Control Codes
ClusDocEx_NodIsSignatureAvailable | Parsing a Value List
ClusDocEx_OpenLocalClusterWithName | Using Object Handles
ClusDocEx_ParseCode | Creating Control Codes
ClusDocEx_ParseDword | Creating Control Codes
ClusDocEx_ResAddPossibleOwner | Using Object Handles
ClusDocEx_ResCreateDisk | Creating Physical Disk Resources
ClusDocEx_ResCreateIPAddress | Creating Physical Disk Resources
ClusDocEx_ResCreateNetworkName | Creating Network Name Resources
ClusDocEx_ResDescribeState | Getting Object States
ClusDocEx_ResGetControlCodeOutput | Getting Information with Control Codes
ClusDocEx_ResGetName | CLUSCTL_RESOURCE_GET_NAME
ClusDocEx_ResGetRegistryCheckpoints | CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS
ClusDocEx_ResGetRequiredDependencies | CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES
ClusDocEx_ResGetResourceType | CLUSCTL_RESOURCE_GET_RESOURCE_TYPE
ClusDocEx_ResGetROCProperties | CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES
ClusDocEx_ResGetROPProperties | CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES
ClusDocEx_ResGetRWCProperties | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES
ClusDocEx_ResGetRWPProperties | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES
ClusDocEx_RtpGetControlCodeOutput | Getting Information with Control Codes
ClusDocEx_SetResourceName | Changing the Cluster Configuration with Control Codes
ClusDocEx_ShowBinary | Creating Control Codes


ClusDocEx.h

This header file loads the necessary libraries and utilities and defines some useful constants, macros, and functions. For any example to compile, the code from ClusDocEx.h must available.

#ifndef _CLUSDOCEX_H
#define _CLUSDOCEX_H
//////////////////////////////////////////////////////////////////////
//
//  ClusDocEx.h
//
//  Defines constants, functions, and macros used by code examples
//  for the Server Cluster API as presented in the
//  Platform SDK documentation.
//
//////////////////////////////////////////////////////////////////////

//  Enable Unicode

    #ifndef UNICODE

        #define UNICODE

    #endif

    #ifndef _UNICODE

        #define _UNICODE

    #endif

//  Windows/WCHAR support

    #include <windows.h>

    #include <tchar.h>

//  Server Cluster API Compiler Directives

    #include <clusapi.h>                   // Cluster API.

    #include <resapi.h>                    // Resource API.

    #pragma comment( lib, "clusapi.lib" )  // Cluster API library.

    #pragma comment( lib, "resutils.lib" ) // Utility Library.

//////////////////////////////////////////////////////////////////////

//  Constants

//  For specifying string and buffer sizes:

    const DWORD ClusDocEx_DEFAULT_CCH = 256;

    const DWORD ClusDocEx_DEFAULT_CB  = 256 * sizeof( WCHAR );

//////////////////////////////////////////////////////////////////////

//  Functions

//--------------------------------------------------------------------
//  ClusDocEx_ListEntrySize
//
//  Calculates the size of a value list entry based on the
//  byte size of the data. This is an overloaded function
//  that can be called in two ways:
//
//  Arguments:
//
//      cbDataLength [in]  Byte size of the data to be added
//                         as a value list entry.
//                 - OR -
//      lpszData     [in]  NULL-terminated Unicode string containing
//                         the data to be added as a value list entry.
//
//  Return Value:
//
//      (DWORD) Total byte size required for a value list entry
//              containing the data.
//
//--------------------------------------------------------------------
DWORD
ClusDocEx_ListEntrySize
(
    DWORD cbDataLength
)
{
    return
    (
        sizeof( CLUSPROP_VALUE ) +     // Syntax and length.
        ALIGN_CLUSPROP( cbDataLength ) // Data and padding.
    );
}

//--------------------------------------------------------------------
//  ClusDocEx_DebugPrint
//
//  Displays debug information.
//
//  Arguments:
//      LPWSTR lpszMessage  [in]  Optional user-defined message.
//      DWORD  dwErrorCode  [in]  Any Win32 error code.
//
//  Return Value:
//      None.
//--------------------------------------------------------------------
void
ClusDocEx_DebugPrint
(
    LPWSTR lpszMessage,
    DWORD dwErrorCode
)
{
    LPVOID lpMsgBuf = NULL;

//  FormatMessage is a Win32 function
    FormatMessage( ( FORMAT_MESSAGE_ALLOCATE_BUFFER |
                     FORMAT_MESSAGE_FROM_SYSTEM ),
                   NULL,
                   dwErrorCode,
                   MAKELANGID( LANG_NEUTRAL, SUBLANG_DEFAULT ),
                   (LPTSTR) &lpMsgBuf,
                   0,
                   NULL );

    wprintf( L"\n(+)\n" );

    if( lpszMessage != NULL )
        wprintf( L"...%ls\n", lpszMessage );

    wprintf( L"...Line %li of %ls\n", __LINE__, __FILE__ );

    wprintf( L"...Result = %li: %ls \n",
             dwErrorCode, (LPWSTR)lpMsgBuf );

    wprintf( L"(-)\n\n" );

//  Free the buffer allocated by FormatMessage
    LocalFree( lpMsgBuf );
}

//--------------------------------------------------------------------
//  ClusDocEx_ShowBuffer
//
//  Displays a block of memory as a sequence of bytes.
//
//  Arguments:
//
//      lpData     [in]  Pointer to the start of the data to read.
//      cbLength   [in]  Number of bytes to read.
//
//  Return Value:
//
//      None.
//--------------------------------------------------------------------
void
ClusDocEx_ShowBuffer
(
    LPVOID lpData,
    DWORD cbLength
)
{
    DWORD dw;
    CLUSPROP_BUFFER_HELPER cbh;

    if( lpData != NULL )
    {
        cbh.pb = (PBYTE) lpData;

        wprintf( L"\n\nBegin...\n\n" );
        wprintf( L"Address   +0  +1  +2  +3  +4  +5  +6  +7  +8  +9  +A  +B  +C  +D  +E  +F\n" );
        wprintf( L"--------  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --  --\n%08lX  ", cbh.pb );

        for( dw = 0 ; dw < cbLength ; dw++ )
        {
            wprintf( L"%02lX  ", cbh.pb[dw] );

            if( ( ( dw + 1 ) % 16 ) == 0 )
                wprintf( L"\n%08lX  ", cbh.pb + dw + 1 );
        }

        wprintf( L"\n\n...end\n\n" );
    }
    else
    {
        wprintf( L"\nNULL buffer.\n\n" );
    }
}

// end ClusDocEx_ShowBuffer

//--------------------------------------------------------------------
//  ClusDocEx_ConvertArg
//
//  Converts single-byte strings to Unicode strings.
//  Used to make command-line arguments and console input
//  ready for use in cluster functions.
//
//  Returns a Win32 error code.
//--------------------------------------------------------------------
DWORD
ConvertArg(
    char *pszArg,       // Single-byte string to convert.
    LPWSTR lpszOut,     // Wide character buffer to return result.
    DWORD cchOutChars   // Size of the buffer as a count of WCHARs.
)
{
    MultiByteToWideChar(
        CP_ACP,                   // Specifies the code page to use.
        ( MB_PRECOMPOSED |
          MB_ERR_INVALID_CHARS ), // Flags governing the conversion.
        pszArg,
        -1,
        lpszOut,
        int( cchOutChars )
    );

    return GetLastError();
}

//////////////////////////////////////////////////////////////////////

//  Forward Declarations

void
ClusDocEx_BasicPropertyValueList();

LPVOID
ClusDocEx_CreateValueListEntry(
    IN DWORD dwSyntax,
    IN DWORD cbLength,
    IN LPVOID lpData,
    OUT LPDWORD lpcbEntrySize
);

DWORD
ClusDocEx_FindSyntax(
    IN LPVOID lpList,
    IN DWORD cbListSize,
    IN DWORD dwSyntax,
    IN DWORD cbStartPos = 0
);

void
ClusDocEx_CreateRequiredDependenciesList();

BOOL
ClusDocEx_NodIsSignatureAvailable(
    IN HCLUSTER hCluster,
    IN HNODE    hNode,
    IN DWORD    dwSignature
);

LPVOID
ClusDocEx_CreatePropertyListEntry(
    IN LPWSTR lpszPropName,
    IN DWORD dwSyntax,
    IN DWORD cbLength,
    IN LPVOID lpData,
    OUT LPDWORD lpcbEntrySize
);

LPVOID
ClusDocEx_GrpCreatePropertyList(
    LPDWORD lpcbPropListSize,
    DWORD dwAutoFailbackType,
    LPWSTR lpszDescription,
    DWORD dwFailbackWindowEnd,
    DWORD dwFailbackWindowStart,
    DWORD dwFailoverPeriod,
    DWORD dwFailoverThreshold,
    DWORD dwPersistentState
);

DWORD
GrpGetRWCDwPropValue(
    IN HGROUP hGroup,
    IN LPCWSTR lpszPropName,
    OUT LPDWORD lpdwPropValue
);

HCLUSTER ClusDocEx_OpenLocalClusterWithName();

DWORD
ClusDocEx_ResAddPossibleOwner(
    LPWSTR lpszResourceName,
    LPWSTR lpszNodeName,
    LPWSTR lpszClusterName
);

LPVOID
ClusDocEx_GrpGetControlCodeOutput(
    IN HGROUP hGroup,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
);

LPVOID
ClusDocEx_NetGetControlCodeOutput(
    IN HNETWORK hNetwork,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
);

LPVOID
ClusDocEx_NICGetControlCodeOutput(
    IN HNETINTERFACE hNetInterface,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
);

LPVOID
ClusDocEx_NodGetControlCodeOutput(
    IN HNODE hNode,
    IN HNODE hHostNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
);

LPVOID
ClusDocEx_ResGetControlCodeOutput(
    IN HRESOURCE hResource,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
);

LPVOID
ClusDocEx_RtpGetControlCodeOutput(
    IN LPWSTR lpszType,
    IN HCLUSTER hCluster,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
);

DWORD
ClusDocEx_SetResourceName(
    HRESOURCE hResource,
    LPWSTR lpszResName
);

void
ClusDocEx_ShowBinary(
    DWORD dwNum
);

void
ClusDocEx_ParseCode(
    char* pName,
    DWORD dwCode
);

DWORD ClusDocEx_ParseDword(
    DWORD dwNumber,
    int iHighBit,
    int iLowBit
);

void
ClusDocEx_EventPort(
    void *dummy
);

void
ClusDocEx_EventMessage(
    HCLUSTER hCluster,
    DWORD    dwNotifyKey,
    DWORD    dwFilterType,
    LPWSTR   lpszObjectName
);

DWORD
ClusDocEx_GrpEnumResources(
    IN HGROUP hGroup,
    IN OUT LPVOID lpOutBuffer,
    IN DWORD  cbOutBufferSize,
    OUT LPDWORD lpcbResultSize
);

LPWSTR
ClusDocEx_ResDescribeState(
    HRESOURCE hRdsource
);

DWORD
ClusDocEx_ResGetRWCDwordProperty(
    IN LPWSTR lpszResName,
    IN LPWSTR lpszPropName,
    OUT LPDWORD lpdwPropvalue
);

DWORD
ClusDocEx_GrpResetPropertyDefaults(
    IN HGROUP hGroup
);

HGROUP
ClusDocEx_GrpCreateVirtualServer(
    IN HCLUSTER hCluster,
    IN LPWSTR   lpszGroupName,
    IN LPWSTR   lpszIPResName,
    IN LPWSTR   lpszNetResName,
    IN LPWSTR   lpszIPAddress,
    IN LPWSTR   lpszNetworkName,
    IN LPWSTR   lpszSubnetMask
);

HRESOURCE
ClusDocEx_ResCreateDisk(
    IN HCLUSTER hCluster,
    IN HGROUP   hGroup,
    IN LPWSTR   lpszDriveLtr
);

HRESOURCE
ClusDocEx_ResCreateIPAddress(
    IN HGROUP hGroup,
    IN LPWSTR lpszResName,
    IN LPWSTR lpszAddress,
    IN LPWSTR lpszNetwork,
    IN LPWSTR lpszSubnetMask
);

HRESOURCE
ClusDocEx_ResCreateNetworkName(
    IN HGROUP    hGroup,
    IN HRESOURCE hIPDependency,
    IN LPWSTR    lpszResName,
    IN LPWSTR    lpszNetName
);

int
ClusDocEx_IsGroupProperty
(
    IN HGROUP hGroup,
    IN LPWSTR lpszPropName
);

LPVOID
ClusDocEx_ResGetRWCProperties(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
);

LPWSTR
ClusDocEx_ResGetName(
    IN HRESOURCE hRes,
    IN HNODE     hNode
);

LPVOID
ClusDocEx_ResGetRWPProperties(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
);

LPVOID
ClusDocEx_ResGetRegistryCheckpoints(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
);

LPVOID
ClusDocEx_ResGetRequiredDependencies(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
);

LPWSTR
ClusDocEx_ResGetResourceType(
    IN HRESOURCE hRes,
    IN HNODE     hNode
);

LPVOID
ClusDocEx_ResGetROCProperties(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
);

LPVOID
ClusDocEx_ResGetROPProperties(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
);

//////////////////////////////////////////////////////////////////////

#endif

// end ClusDocEx.h


Using Lists and Tables

The following sections describe the tools and techniques used to create and parse value lists, property lists, and property tables.

  • Using CLUSPROP_BUFFER_HELPER
  • Using Value Lists
  • Using Parameter Blocks
  • Building Property Tables
  • Using Property Lists
  • Using Object Handles

For a sample class that dynamically manages property and value lists, see the CClusPropList class sample (proplist.h and proplist.cpp) included with the Platform SDK. You can also generate this sample by running the Cluster Resource Type Wizard (see Using the Cluster Resource Wizard).


Using CLUSPROP_BUFFER_HELPER

CLUSPROP_BUFFER_HELPER is a fundamental tool for building and parsing property and value lists, and can be used for arrays as well. CLUSPROP_BUFFER_HELPER is a union of pointers that lets you step through the bytes of a buffer, reading or writing values of various types.

The following sections present procedures and example code.

Topic | Description
Building with CLUSPROP_BUFFER_HELPER | How to create value and property lists with CLUSPROP_BUFFER_HELPER.
Parsing with CLUSPROP_BUFFER_HELPER | How to read value and property lists with CLUSPROP_BUFFER_HELPER.


Building with CLUSPROP_BUFFER_HELPER

To create a value or property list with CLUSPROP_BUFFER_HELPER, or to create any other kind of structure in a buffer, use the following procedure.

To create a value or property list

  1. Allocate a buffer of sufficient size to hold the data.
  2. Set the pb member of CLUSPROP_BUFFER_HELPER to the start of the buffer.
  3. Use one of CLUSPROP_BUFFER_HELPER's member pointers to write one or more values from the present position. You must know the byte size of this value.
  4. Optional. Verify that there is room in the buffer to advance CLUSPROP_BUFFER_HELPER to the next write position.
  5. Use the pb member to advance to the next write position.
  6. Repeat steps 3-5 until the buffer is full or all the data is written

When using this procedure, you must be familiar with the architecture of value lists and property lists.

Example

The following examples use CLUSPROP_BUFFER_HELPER to generate a value list entry. A value list would consist of "stacks" of these entries terminated by CLUSPROP_SYNTAX_ENDMARK. A property list would consist of "stacks" of value lists (one value list per property) prefixed by the count of properties in the list.

In the first example (ClusDocEx_BasicPropertyValueList) the numbers in parentheses correspond to the steps in the procedure presented above. The second example (ClusDocEx_CreateValueListEntry) is used by several other example functions.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_BASICPROPERTYVALUELIST_CPP
#define _CLUSDOCEX_BASICPROPERTYVALUELIST_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_BasicPropertyValueList
//
//  A tutorial example that describes the process of using
//  CLUSPROP_BUFFER_HELPER to create property and value lists.
//
//  This example creates a single-property list that consists
//  of the following:
//
//  Property List:
//  ---------  ------------------------   ---
//  count      DWORD                       N ( = 1 )
//  ---------  -------------------------  ---
//  Syntax  \                              .
//  Length  -> CLUSPROP_PROPERTY_NAME      .     A single property
//  Name    /                              .     typically consists
//  -------                                .     of a value list that
//  Syntax  \                            Value   describes the
//  Length  -> CLUSPROP_PROPERTY_VALUE    List   name and value of
//  Value   /                              .     the property
//  ---------                              .
//  Endmark -> CLUSPROP_ENDMARK            .
//  ------- -  -------------------------  ---
//
//  A longer property list would continue with 1 additional value
//  list per property.
//
//--------------------------------------------------------------------
void
ClusDocEx_BasicPropertyValueList(
    void
)
{

//  Name and intended value of the Role common property for Networks.

    LPCWSTR lpszRoleName = L"Role";
    DWORD   dwRoleValue = ClusterNetworkRoleInternalUse;

    LPVOID lpList;
    CLUSPROP_BUFFER_HELPER cbh;

    DWORD cbSzSize;
    DWORD cbNameEntrySize;
    DWORD cbDwordEntrySize;
    DWORD cbListSize;

//  Calculate byte size of the Name.  MUST include terminating NULL.

    cbSzSize = ( lstrlenW( lpszRoleName ) + 1 ) * sizeof( WCHAR );

//  Byte size of the value list entry for the name.

    cbNameEntrySize =
        sizeof( DWORD )            +  // Syntax member
        sizeof( DWORD )            +  // Length member
        ALIGN_CLUSPROP( cbSzSize );   // Data + padding for correct alignment

//  Byte size of the value list entry for the DWORD data.

    cbDwordEntrySize =
        sizeof( DWORD )            +  // Syntax member
        sizeof( DWORD )            +  // Length member
        sizeof( DWORD );              // Data (already aligned)

//  ClusDocEx_ListEntrySize automates the above calculations
//  -----------------------included in ClusDocEx.h)

//  Byte size required for the entire property list.

    cbListSize =  sizeof( DWORD ) +     // prop count
                  cbNameEntrySize +     // name
                  cbDwordEntrySize +    // value
                  sizeof( DWORD );      // endmark

//  Allocate property list buffer.

    lpList = LocalAlloc(
                    LPTR,          // zeros the memory
                    cbListSize );

    if( lpList == NULL )
    {
    //  Handle the error
    }

//  Position cbh.

    cbh.pb = (PBYTE) lpList;

//  Write the property count using cbh's CLUSPROP_LIST pointer.

    cbh.pList->nPropertyCount = 1;

//  Position cbh.

    cbh.pb += sizeof( DWORD );

//  Write the property name

    cbh.pName->Syntax.dw = CLUSPROP_SYNTAX_NAME;

    cbh.pName->cbLength = cbSzSize;

    lstrcpyW(  cbh.pName->sz, lpszRoleName );

/*
----------------------------------------------------------------------
Note that the following alternatives would have the same result:

(1)     *cbh.pdw = 1 ;                      // property count
        cbh.pb += sizeof( DWORD );          // Advance pb
        *cbh.pdw = CLUSPROP_PROPERTY_NAME ; // Set the Syntax
        cbh.pb += sizeof( DWORD );          // Advance pb
        *cbh.pdw = cbSzSize;                // Set the Length
        cbh.pb += sizeof( DWORD );          // Advance pb
        lstrcpyW( cbh.psz, lpszRoleName );  // Set the Data

(2)     *cbh.pdw = 1 ;
        cbh.pb += sizeof( DWORD );
        cbh.pValue->Syntax.dw = CLUSPROP_PROPERTY_NAME;
        cbh.pValue->cbLength = sizeof( DWORD );
        cbh.pb += sizeof( CLUSPROP_VALUE );
        CLUSPROP_BUFFER_HELPER cbhRead;
        cbhRead.pb = (PBYTE) lpszRoleName;
        for( int i = 0 ; i < cbSzSize ; i++ )
            cbh.pb[i] = cbhRead.pb[i];
----------------------------------------------------------------------
*/

//  Advance cbh

    cbh.pb += cbNameEntrySize;

//  Add the property value.

    cbh.pDwordValue->Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;

    cbh.pDwordValue->cbLength = sizeof( DWORD );

    cbh.pDwordValue->dw = dwRoleValue;

//  Advance CBH.pb

    cbh.pb += cbDwordEntrySize;

//  End the value list for this property.

    cbh.pSyntax->dw = CLUSPROP_SYNTAX_ENDMARK;

    cbh.pb = NULL;

//  Use the list. For example, to set the new property
//  in the cluster database:
//
//    (open a network handle)
//
//    dwResult = ClusterNetworkControl(
//                   hNetwork,
//                   NULL,
//                   CLUSCTL_NODE_SET_COMMON_PROPERTIES
//                   lpList,
//                   cbListSize,
//                   NULL,
//                   0,
//                   NULL
//               );

    if( lpList != NULL )
    {

    //  Display lpList as raw bytes

        ClusDocEx_ShowBuffer( lpList, cbListSize );   //  see "ClusDocEx.h"

        LocalFree( lpList );
    }
}
//
//  end ClusDocEx_BasicPropertyValueList
//--------------------------------------------------------------------
#endif

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_CREATEVALUELISTENTRY_CPP
#define _CLUSDOCEX_CREATEVALUELISTENTRY_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_CreateValueListEntry
//
//  Returns a buffer containing a properly formatted entry for
//  a value list.
//
//  Callers must call LocalFree on the returned pointer.
//
//  Arguments:
//      IN DWORD dwSyntax          Data syntax (see CLUSPROP_SYNTAX).
//      IN DWORD cbLength          Data length (see CLUSPROP_VALUE).
//      IN LPVOID lpData           Pointer to the data.
//      OUT LPDWORD lpcbEntrySize  Byte size of the resulting entry.
//
//  Return Value:
//      Pointer to a buffer containing a value list entry.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_CreateValueListEntry(
    IN DWORD dwSyntax,
    IN DWORD cbLength,
    IN LPVOID lpData,
    OUT LPDWORD lpcbEntrySize
)
{
    CLUSPROP_BUFFER_HELPER cbh;
    LPVOID lpEntry = NULL;

//  TBD:  Code that checks for bad parameters.

//  Calculate the size of the entry and allocate space.

    *lpcbEntrySize = ClusDocEx_ListEntrySize( cbLength );

//  lpcbEntrySize now describes the size of the entire value list
//  entry, including the alignment padding.

    lpEntry = LocalAlloc( LPTR, *lpcbEntrySize );

    if( lpEntry != NULL )
    {

    //  Position cbh.

        cbh.pb = (LPBYTE) lpEntry;

    //  Write syntax and length.

        cbh.pValue->Syntax.dw = dwSyntax;

        cbh.pValue->cbLength = cbLength;

    //  Position cbh.

        cbh.pb += sizeof( CLUSPROP_VALUE );

    //  Bytewise copy the data (should use memcpy).

        memcpy( cbh.pb, lpEntry, cbLength );

    //  The initial allocation allowed for alignment padding.

    }

    cbh.pb = NULL;

    return lpEntry;

}
//  end ClusDocEx_CreateValueListEntry
//--------------------------------------------------------------------
#endif

//--------------------------------------------------------------------
//  TODO
//
//  ClusDocEx_CreateValueListEntry creates single entries.
//  A class or series of functions could be created to dynamically
//  allocate and "stack" entries.  Remember that the data
//  has to be contiguous, so a linked list solution would have
//  to be able to combine its nodes into a single buffer.
//
//  For an example of a dynamic property list,
//  refer to the CClusPropList class.
//--------------------------------------------------------------------


Parsing with CLUSPROP_BUFFER_HELPER

To read data from a value or property list with CLUSPROP_BUFFER_HELPER, use the following procedure.

To read data from a value or property list

  1. Obtain a buffer containing data.
  2. Set the pb member of CLUSPROP_BUFFER_HELPER to the start of the buffer.
  3. Use one of CLUSPROP_BUFFER_HELPER's member pointers to read the Syntax member of the next data structure.
  4. If the Syntax matches what you are looking for, use other member pointers to get the data.
  5. Otherwise, use the Length member to get the byte size of the current entry.
  6. Verify that there is room in the buffer to advance CLUSPROP_BUFFER_HELPER to the next read position.
  7. Use the pb member to advance to the next read position.
  8. Repeat steps 3-6 until the item is found

When using this procedure, you must be familiar with the architecture of value lists and property lists.

Example

The following example presents a general-purpose parsing function for locating entries in a value or property list.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_FINDSYNTAX
#define _CLUSDOCEX_FINDSYNTAX
//--------------------------------------------------------------------
//
//  ClusDocEx_FindSyntax
//
//  Returns the position of the first entry that matches a specified
//  syntax in a property or value list, starting from a specified
//  position within the list.
//
//  Arguments:
//
//  lpList       Pointer to the value or property list buffer.
//  cbListSize   Size of the value or property list.
//  dwSyntax     The syntax to search for (see CLUSPROP_SYNTAX).
//  bPropList    The list is a property list.
//
//  If successful, returns the byte position of the first match found,
//                 OR zero if no match was found.
//
//  If an error occurred, returns -1 (0xFFFFFFFF).
//
//--------------------------------------------------------------------
DWORD
ClusDocEx_FindSyntax(
    IN LPVOID lpList,
    IN DWORD cbListSize,
    IN DWORD dwSyntax,
    IN BOOL bPropList
)
{
    DWORD cbPosition = 0;
    DWORD cbNextPos = 0;
    DWORD cbEntrySize = 0;

    CLUSPROP_BUFFER_HELPER cbh;

    if( ( lpList == NULL ) ||
        ( cbListSize == 0 ) )
    {
        cbPosition = -1;
        goto endf;
    }

    cbh.pb = (LPBYTE) lpList;

//  If this is a property list, advance past the count of properties.

    if( bPropList )
        cbh.pb += sizeof( DWORD );

    do
    {

    //  Check the syntax of the current entry.

        if( cbh.pSyntax->dw == dwSyntax )
        {
        //  Specified syntax found.
            cbPosition = cbh.pb - (LPBYTE) lpList;
            break;
        }
        else if( cbh.pSyntax->dw != CLUSPROP_SYNTAX_ENDMARK )
        {
        //  Specified syntax not found and end of list not found.
        //  Get the size of the current entry.
            cbEntrySize = ClusDocEx_ListEntrySize( cbh.pValue->cbLength );
        }
        else if( bPropList )
        {
        //  Endmark found in a property list.
        //  Advance past the endmark.
            cbEntrySize = sizeof( CLUSPROP_SYNTAX );
        }
        else
        {
        //  Endmark found in a value list.
        //  Specified syntax was not found.
            cbPosition = 0;
            break;
        }

    //  Calculate the next position in the list.

        cbNextPos = cbh.pb
                    - (LPBYTE) lpList
                    + cbEntrySize;

    //  Verify remaining buffer size.
    //  The sizeof(CLUSPROP_SYNTAX) value accounts for the top-of-loop
    //  read operation (cbh.pSyntax->dw).

        if( cbNextPos + sizeof( CLUSPROP_SYNTAX ) > cbListSize )
        {
            cbPosition = 0;
            break;
        }
        else
        {
            cbh.pb += cbEntrySize;
        }

    } while( TRUE );

endf:

    return cbPosition;
}
//
//  End ClusDocEx_FindSyntax.
//--------------------------------------------------------------------
#endif


Using Value Lists

Value lists are used in some control code operations and as the building blocks of property lists. The following topics describe how to create and parse value lists.

Topic | Task
Creating Value Lists | How to format a value list.
Parsing a Value List | How to extract data from a value list.


Creating Value Lists

This section assumes you are familiar with the architecture described in Value Lists. Creating a value list means creating a sequence of bytes that conforms to the architectural conventions for value lists. As long as the result is correct, any technique that properly sequences and aligns the data is fine.

For example, the easiest way to create a value list is to create a structure:

typedef struct DWORD_VALUE_LIST
{
    CLUSPROP_DWORD First;
    CLUSPROP_DWORD Second;
    CLUSPROP_DWORD Third;
    CLUSPROP_SYNTAX Endmark;
} DWORD_VALUE_LIST;

However, this method gets complicated when variable-length data is introduced.

Another way to create a value list is to use CLUSPROP_BUFFER_HELPER. (See Building with CLUSPROP_BUFFER_HELPER.)

Example

The following example creates a required dependencies list for a resource using structures to define the value list. A resource DLL might build a value list like this in response to the CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_CREATEREQUIREDDEPENDENCIESLIST_CPP
#define _CLUSDOCEX_CREATEREQUIREDDEPENDENCIESLIST_CPP

//  Global buffer that will store the required dependencies value list.

    LPVOID g_CLUSDOCEX_REQDEPS = NULL;

    #define RESOURCE_TYPE_NETWORK_NAME L"Network Name"

//--------------------------------------------------------------------
//
//  ClusDocEx_CreateRequiredDependenciesList
//
//  Creates a value list specifying the required dependencies
//  of a resource. For this example, the dependencies are a Network
//  Name resource and a storage class resource.
//
//--------------------------------------------------------------------
void
ClusDocEx_CreateRequiredDependenciesList()
{

//  Define a structure for the value list.
//  Note the use of the CLUSPROP_SZ_DECLARE macro.

    struct DEP_DATA
    {
        CLUSPROP_RESOURCE_CLASS rcStorage;
        CLUSPROP_SZ_DECLARE( netnameEntry,
                             sizeof( RESOURCE_TYPE_NETWORK_NAME ) /
                                     sizeof( WCHAR ) );
        CLUSPROP_SYNTAX         endmark;
    };
    DEP_DATA* pdepdata;

    pdepdata = (DEP_DATA*) LocalAlloc( LPTR, sizeof( DEP_DATA ) );

    if( pdepdata != NULL )
    {

    //  Add the Storage class entry.
        pdepdata->rcStorage.Syntax.dw = CLUSPROP_SYNTAX_RESCLASS;
        pdepdata->rcStorage.cbLength = sizeof( pdepdata->rcStorage.rc );
        pdepdata->rcStorage.rc = CLUS_RESCLASS_STORAGE;

    //  Add the Network Name entry.
        pdepdata->netnameEntry.Syntax.dw = CLUSPROP_SYNTAX_NAME;
        pdepdata->netnameEntry.cbLength = sizeof( RESOURCE_TYPE_NETWORK_NAME );
        lstrcpyW( pdepdata->netnameEntry.sz, RESOURCE_TYPE_NETWORK_NAME );

    //  Add the endmark.
        pdepdata->endmark.dw = CLUSPROP_SYNTAX_ENDMARK;
    }

    g_CLUSDOCEX_REQDEPS = (LPVOID) pdepdata;
}
//  End ClusDocEx_CreateRequiredDependenciesList.
//--------------------------------------------------------------------
#endif


Parsing a Value List

The following example parses a value list returned from the CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_NODISSIGNATUREAVAILABLE_CPP
#define _CLUSDOCEX_NODISSIGNATUREAVAILABLE_CPP

//--------------------------------------------------------------------
//  ClusDocEx_NodIsSignatureAvailable
//
//  Tests whether a node can access a disk with a specified signature.
//
//  Arguments:
//    IN HCLUSTER hCluster       Cluster handle.
//    IN HNODE    hNode          Handle to the node to query.
//    IN DWORD    dwSignature    Signature to query for.
//
//  Return Value:
//    TRUE if the signature is available to the node
//    FALSE if not (or if an error occurs)
//
//--------------------------------------------------------------------
BOOL
ClusDocEx_NodIsSignatureAvailable
(
    IN HCLUSTER hCluster,
    IN HNODE    hNode,
    IN DWORD    dwSignature
)
{
    DWORD dwResult = ERROR_SUCCESS;

    DWORD cbPosition = 0;
    DWORD cbListSize = 0;
    BOOL  bDiskFound = FALSE;

    LPVOID lpValueList = NULL;

    CLUSPROP_BUFFER_HELPER cbh;

    if( ( hCluster == NULL ) ||
        ( hNode == NULL ) )
    {
        dwResult = ERROR_BAD_ARGUMENTS;
        goto endf;
    }

//  Get all disks available to the specified node.

    lpValueList = ClusDocEx_RtpGetControlCodeOutput(
                             L"Physical Disk",
                             hCluster,
                             hNode,
                             CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS,
                             &cbListSize );

    if( lpValueList == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Parse the buffer. The control code returns a value list.
//  The entry for each disk begins with a CLUSPROP_DISK_SIGNATURE structure.

    cbh.pb = (PBYTE) lpValueList;

    while( 1 )
    {
        if( ( cbh.pDiskSignatureValue->Syntax.dw == CLUSPROP_SYNTAX_DISK_SIGNATURE ) &&
            ( cbh.pDiskSignatureValue->dw == dwSignature ) )
        {
        //  Syntax indicates a CLUSPROP_DISK_SIGNATURE structure.
        //  The signature found matches the specified signature.
            bDiskFound = TRUE;
            break;
        }
        else if( cbh.pSyntax->dw == CLUSPROP_SYNTAX_ENDMARK )
        //  Reached the end of the list.
            break;

    //  Add the size of the current entry to the position indicator
        cbPosition += ClusDocEx_ListEntrySize( cbh.pValue->cbLength );

    //  Compare position indicator to the size of the list.
    //  Adding sizeof( DWORD ) allows for the read operation at the
    //  top of the loop.
        if( ( cbPosition + sizeof( DWORD ) ) > cbListSize )
            break;

    //  Advance cbh
        cbh.pb += ClusDocEx_ListEntrySize( cbh.pValue->cbLength );

    }
    //  End while.

endf:

    if( lpValueList != NULL )
        LocalFree( lpValueList );

    SetLastError( dwResult );

    return bDiskFound;
}
//  end ClusDocEx_NodIsSignatureAvailable
//--------------------------------------------------------------------
#endif


Using Parameter Blocks

A parameter block provides data storage for a property table. A parameter block is a user-defined structure that includes:

  • One member for each property. The structure may store properties as actual data values or as pointers to the data.
  • Additional members, as needed, for storing miscellaneous non-property information.

Example

The following example shows two parameter blocks for a Generic Application resource:

//
// Parameter block for a Generic Application resource.
// This example contains only property data (see below)
//
typedef struct CLUSDOCEX_GENAPP_PARAMS {

    LPWSTR CommandLine;         // CommandLine property

    LPWSTR CurrentDirectory;    // CurrentDirectory property

    DWORD  UseNetworkName;      // UseNetworkName property

    DWORD  InteractWithDesktop; // InteractWithDesktop property

}
CLUSDOCEX_GENAPP_PARAMS, *PCLUSDOCEX_GENAPP_PARAMS;

//
// Another parameter block for a Generic Application resource.
// This example contains both property and non-property data.
//
typedef struct CLUSDOCEX_GENAPP_PARAMS2
{
    LPWSTR ApplicationName;          // non-property data.

    LPWSTR CommandLineName;          // non-property data (stores the name of the property).
    LPWSTR CommandLineValue;         // property data.

    LPWSTR CurrentDirectoryName;     // non-property data.
    LPWSTR CurrentDirectoryValue;    // property data.

    LPWSTR UseNetworkNameName;       // non-property data.
    DWORD  UseNetworkNameValue;      // property data.

    LPWSTR InteractWithDesktopName;  // non-property data.
    DWORD  InteractWithDesktopValue; // property data.

}
CLUSDOCEX_GENAPP_PARAMS2, *PCLUSDOCEX_GENAPP_PARAMS2;


Building Property Tables

The following procedure describes how to build a property table:

To build a property table for an object

  1. Construct a parameter block (see Using Parameter Blocks).
  2. Construct an array of RESUTIL_PROPERTY_ITEM structures (one structure for each object property). Each RESUTIL_PROPERTY_ITEM structure includes:
    • Property name.
    • Name of the cluster database subkey storing the property.
    • Property format.
    • Property default, minimum, and maximum values.
    • Flags to define the property as read-only and/or required.
    • An offset to the appropriate property member of the parameter block.
  3. As the final array element, add a RESUTIL_PROPERTY_ITEM structure with a NULL property name.

The entire array of RESUTIL_PROPERTY_ITEM structures is what is referred to as a property table.

Example

In the following example, a resource DLL defines a parameter block and a property table as global data which are used as the basis for property operations. For more information on initializing data in a resource DLL, see Defining Structures and Constants.

//////////////////////////////////////////////////////////////////////

//  Excerpt from the sample SmbSmp.c.

//  Private property names
#define PROP_NAME__STRINGPROP  L"StringProp"
#define PROP_NAME__DWORDPROP   L"DwordProp"
#define PROP_NAME__BINARYPROP  L"BinaryProp"
#define PROP_NAME__BOOLPROP    L"BoolProp"
#define PROP_NAME__MULTISZPROP L"MultiSzProp"
#define PROP_NAME__LONGPROP    L"LongProp"

//  Min, max, default values
#define PROP_MIN__DWORDPROP     (1)
#define PROP_MAX__DWORDPROP     (256)
#define PROP_DEFAULT__DWORDPROP (32)
#define PROP_MIN__BOOLPROP      (0)
#define PROP_MAX__BOOLPROP      (1)
#define PROP_DEFAULT__BOOLPROP  (0)
#define PROP_MIN__LONGPROP      (-1)
#define PROP_MAX__LONGPROP      (15)
#define PROP_DEFAULT__LONGPROP  (-1)

//  Parameter block for the private properties.
typedef struct CLUSDOCEX_PROPS
{
    PWSTR  pszStringProp;
    DWORD  nDwordProp;
    LPBYTE pbBinaryProp;
    DWORD  nBinaryPropSize;
    BOOL   bBoolProp;
    PWSTR  pszMultiSzProp;
    DWORD  nMultiSzPropSize;
    LONG   nLongProp;
}
CLUSDOCEX_PROPS, * PCLUSDOCEX_PROPS;

//  Property table.
RESUTIL_PROPERTY_ITEM
ClusDocExResourcePrivateProperties[] =
{
    {
        PROP_NAME__STRINGPROP, /* property name             */
        NULL,                  /* subkey                    */
        CLUSPROP_FORMAT_SZ,    /* format                    */
        0, 0, 0,               /* default, min, max value   */
        RESUTIL_PROPITEM,      /* flags                     */
        FIELD_OFFSET(          /* offset to parameter block */
            CLUSDOCEX_PROPS,
            pszStringProp )

    },
    {
        PROP_NAME__DWORDPROP,
        NULL,
        CLUSPROP_FORMAT_DWORD,
        PROP_DEFAULT__DWORDPROP,
        PROP_MIN__DWORDPROP,
        PROP_MAX__DWORDPROP,
        RESUTIL_PROPITEM,
        FIELD_OFFSET(
            CLUSDOCEX_PROPS,
            nDwordProp )
    },
    {
        PROP_NAME__BINARYPROP,
        NULL,
        CLUSPROP_FORMAT_BINARY,
        0, 0, 0,
        RESUTIL_PROPITEM,
        FIELD_OFFSET(
            CLUSDOCEX_PROPS,
           pbBinaryProp )
    },
    {
        PROP_NAME__BOOLPROP,
        NULL,
        CLUSPROP_FORMAT_DWORD,
        PROP_DEFAULT__BOOLPROP,
        PROP_MIN__BOOLPROP,
        PROP_MAX__BOOLPROP,
        RESUTIL_PROPITEM_SIGNED,
        FIELD_OFFSET(
            CLUSDOCEX_PROPS,
            bBoolProp )
    },
    {
        PROP_NAME__MULTISZPROP,
        NULL,
        CLUSPROP_FORMAT_MULTI_SZ,
        0, 0, 0,
        0,
        FIELD_OFFSET(
            CLUSDOCEX_PROPS,
            pszMultiSzProp )
    },
    {
        PROP_NAME__LONGPROP,
        NULL,
        CLUSPROP_FORMAT_LONG,
        (DWORD) PROP_DEFAULT__LONGPROP,
        (DWORD) PROP_MIN__LONGPROP,
        (DWORD) PROP_MAX__LONGPROP,
        0,
        FIELD_OFFSET(
            CLUSDOCEX_PROPS,
            nLongProp )
    },
    { 0 }
};


Using Property Lists

Both resource DLLs and cluster-aware applications need to create and parse property lists. Refer to

  • Creating Property Lists
  • Parsing Property Lists


Creating Property Lists

There are two recommended ways of creating a property list:

  • Cluster-aware applications should use CLUSPROP_BUFFER_HELPER to build the property list as a series of value lists. For procedures and examples, see Building with CLUSPROP_BUFFER_HELPER.
  • Resource DLLs should store local copies of property data in parameter blocks and property tables, and use the property structure construction functions to generate property lists. For procedures and examples, see Using Parameter Blocks and Using Lists and Tables.

This distinction is based on the fact that many property table operations require direct access to the cluster database. Resource DLLs are expected to have such access. However, cluster-aware applications should avoid direct cluster database manipulation. See the standard order of preference.

As a third option, the SmbSmp sample resource type (located in the samples directory of the SDK) includes the complete implementation of CClusPropList, a sample property list management class. If you can't find CClusPropList.h and CClusPropList.cpp in the samples directory, you can create the source code by running the Cluster Resource Type Wizard (see Using the Cluster Resource Wizard). The resulting project files will include the CClusPropList source code.

Example

The following example contains the functions ClusDocEx_CreatePropertyListEntry and ClusDocEx_GrpCreatePropertyList. The first function returns a buffer containing a single property list entry. The second function uses the first function to create multiple entries and "stacks" them into a property list.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_CREATEPROPERTYLISTENTRY_CPP
#define _CLUSDOCEX_CREATEPROPERTYLISTENTRY_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_CreatePropertyListEntry.
//
//  Returns a buffer containing an entry for a property list,
//  formatted as a value list containing the following entries:
//      Property Name  (syntax, length, data, padding)
//      Property Value (syntax, length, data, padding)
//      CLUSPROP_SYNTAX_ENDMARK
//
//  Callers must call LocalFree on the returned pointer.
//
//  Arguments:
//      IN LPWSTR lpszPropName     Name of the property.
//      IN DWORD dwSyntax          Data syntax (see CLUSPROP_SYNTAX).
//      IN DWORD cbLength          Data length (see CLUSPROP_VALUE).
//      IN LPVOID lpData           Pointer to the data.
//      OUT LPDWORD lpcbEntrySize  Byte size of the resulting entry.
//
//  Return Value:
//      Pointer to a buffer containing a property list entry.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_CreatePropertyListEntry(
    IN LPWSTR lpszPropName,
    IN DWORD dwSyntax,
    IN DWORD cbLength,
    IN LPVOID lpData,
    OUT LPDWORD lpcbEntrySize
)
{
    DWORD cbPropNameSize = ( lstrlenW( lpszPropName ) + 1 ) *
                           sizeof( WCHAR );
    DWORD cbNameEntrySize;
    DWORD cbValueEntrySize;

    CLUSPROP_BUFFER_HELPER cbh;
    LPVOID lpEntry = NULL;

//  TBD:  Code that checks for bad parameters.

//  Calculate sizes.
//  ClusDocEx_ListEntrySize is defined in ClusDocEx.h.

    cbNameEntrySize = ClusDocEx_ListEntrySize( cbPropNameSize );

    cbValueEntrySize = ClusDocEx_ListEntrySize( cbLength );

    *lpcbEntrySize = cbNameEntrySize +
                     cbValueEntrySize +
                     sizeof( DWORD );

    lpEntry = LocalAlloc( LPTR, *lpcbEntrySize );

    if( lpEntry != NULL )
    {

    //  Position cbh.

        cbh.pb = (LPBYTE) lpEntry;

    //  Write the property name.

        cbh.pName->Syntax.dw = CLUSPROP_SYNTAX_NAME;

        cbh.pName->cbLength = cbPropNameSize;

        lstrcpy( cbh.pName->sz, lpszPropName );

    //  Advance cbh.

        cbh.pb += cbNameEntrySize;

    //  Write syntax and length

        cbh.pValue->Syntax.dw = dwSyntax;

        cbh.pValue->cbLength = cbLength;

    //  Position cbh.

        cbh.pb += sizeof( CLUSPROP_VALUE );

    //  Copy the data.

        memcpy( cbh.pb, lpData, cbLength );

    //  Position cbh.

        cbh.pb = (PBYTE) lpEntry + cbNameEntrySize + cbValueEntrySize;

    //  Set the endmark.

        *cbh.pdw = CLUSPROP_SYNTAX_ENDMARK;
    }

    cbh.pb = NULL;

    return lpEntry;

}
//  end ClusDocEx_CreatePropertyListEntry
//--------------------------------------------------------------------
#endif

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_GRPCREATEPROPERTYLIST_CPP
#define _CLUSDOCEX_GRPCREATEPROPERTYLIST_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_GrpCreatePropertyList(
//
//  Returns a property list containing all of the read/write common
//  properties for a group.
//
//  Callers must call LocalFree on the returned pointer.
//
//  Arguments:
//      LPDWORD lpcbPropListSize    Byte size of the resulting
//                                  property list.
//      Use the remaining arguments to assign new values to the
//      read/write group common properties.
//
//  Return Value:
//      Pointer to a buffer containing a property list.
//--------------------------------------------------------------------
LPVOID
ClusDocEx_GrpCreatePropertyList(
    LPDWORD lpcbPropListSize,
    DWORD dwAutoFailbackType,
    LPWSTR lpszDescription,
    DWORD dwFailbackWindowEnd,
    DWORD dwFailbackWindowStart,
    DWORD dwFailoverPeriod,
    DWORD dwFailoverThreshold,
    DWORD dwPersistentState
)
{
    LPVOID lpPropList;
    LPVOID lpAutoFailbackType;
    LPVOID lpDescription;
    LPVOID lpFailbackWindowEnd;
    LPVOID lpFailbackWindowStart;
    LPVOID lpFailoverPeriod;
    LPVOID lpFailoverThreshold;
    LPVOID lpPersistentState;

    DWORD dwPropCount = 7;
    DWORD cbPropEntrySize[7];
    DWORD cbPosition = 0;
    DWORD cb, dw;

    CLUSPROP_BUFFER_HELPER cbh_write, cbh_read;

//  Create the property list entries for each property.

    lpAutoFailbackType    = ClusDocEx_CreatePropertyListEntry(
                                L"AutoFailbackType",
                                CLUSPROP_SYNTAX_LIST_VALUE_DWORD,
                                sizeof( DWORD ),
                                (LPVOID) &dwAutoFailbackType,
                                &cbPropEntrySize[0] );

    lpDescription         = ClusDocEx_CreatePropertyListEntry(
                                L"Description",
                                CLUSPROP_SYNTAX_LIST_VALUE_SZ,
                                ( lstrlenW( lpszDescription)  + 1 ) * sizeof( WCHAR ),
                                (LPVOID) lpszDescription,
                                &cbPropEntrySize[1] );

    lpFailbackWindowEnd   = ClusDocEx_CreatePropertyListEntry(
                                L"FailbackWindowEnd",
                                CLUSPROP_SYNTAX_LIST_VALUE_DWORD,
                                sizeof( DWORD ),
                                (LPVOID) &dwFailbackWindowEnd   ,
                                &cbPropEntrySize[2] );

    lpFailbackWindowStart = ClusDocEx_CreatePropertyListEntry(
                                L"FailbackWindowStart",
                                CLUSPROP_SYNTAX_LIST_VALUE_DWORD,
                                sizeof( DWORD ),
                                (LPVOID) &dwFailbackWindowStart,
                                &cbPropEntrySize[3] );

    lpFailoverPeriod      = ClusDocEx_CreatePropertyListEntry(
                                L"FailoverPeriod",
                                CLUSPROP_SYNTAX_LIST_VALUE_DWORD,
                                sizeof( DWORD ),
                                (LPVOID) &dwFailoverPeriod,
                                &cbPropEntrySize[4] );

    lpFailoverThreshold   = ClusDocEx_CreatePropertyListEntry(
                                L"FailoverThreshold",
                                CLUSPROP_SYNTAX_LIST_VALUE_DWORD,
                                sizeof( DWORD ),
                                (LPVOID) &dwFailoverThreshold,
                                &cbPropEntrySize[5] );

    lpPersistentState     = ClusDocEx_CreatePropertyListEntry(
                                L"PersistentState",
                                CLUSPROP_SYNTAX_LIST_VALUE_DWORD,
                                sizeof( DWORD ),
                                (LPVOID) &dwPersistentState,
                                &cbPropEntrySize[6] );

//  Calculate the required size, which should be the sum of each entry
//  plus the size of the property count.

    *lpcbPropListSize = sizeof( DWORD );  // property count.

    for( cb = 0 ; cb < dwPropCount ; cb++ )
        *lpcbPropListSize += cbPropEntrySize[cb];

    lpPropList = LocalAlloc( LPTR, *lpcbPropListSize );

//  Position cbh and write the property count.

    cbh_write.pb = (PBYTE) lpPropList;

    *cbh_write.pdw = dwPropCount;

    cbPosition = sizeof( DWORD );

//  Iterate through the property list entries and copy each entry
//  to the property list buffer.

    for( dw = 0 ; dw < dwPropCount ; dw++ )
    {
        switch( dw )
        {
        case 0:  cbh_read.pb = (PBYTE) lpAutoFailbackType;    break;
        case 1:  cbh_read.pb = (PBYTE) lpDescription;         break;
        case 2:  cbh_read.pb = (PBYTE) lpFailbackWindowEnd;   break;
        case 3:  cbh_read.pb = (PBYTE) lpFailbackWindowStart; break;
        case 4:  cbh_read.pb = (PBYTE) lpFailoverPeriod;      break;
        case 5:  cbh_read.pb = (PBYTE) lpFailoverThreshold;   break;
        case 6:  cbh_read.pb = (PBYTE) lpPersistentState;     break;
        default: break;
        }

    //  cbPosition is the index into the property list buffer.
    //  cb is the index into the current entry buffer.
    //  dw iterates the entries.

        for( cb = 0 ; cb < cbPropEntrySize[dw] ; cb++, cbPosition++ )
            cbh_write.pb[cbPosition] = cbh_read.pb[cb];
    }

//  Free the memory allocated by ClusDocEx_CreatePropertyListEntry

    LocalFree( lpAutoFailbackType );
    LocalFree( lpDescription );
    LocalFree( lpFailbackWindowEnd );
    LocalFree( lpFailbackWindowStart );
    LocalFree( lpFailoverPeriod );
    LocalFree( lpFailoverThreshold );
    LocalFree( lpPersistentState );

    return lpPropList;

}
//  end ClusDocEx_GrpCreatePropertyList
//--------------------------------------------------------------------
#endif


Parsing Property Lists

The recommended way to parse a property list is to use one of the property list parsing functions to locate a specific type of value. Both cluster-aware applications and resource DLLs can use these functions.

If no parsing function exists for the type of data you are seeking, you can parse the property list with CLUSPROP_BUFFER_HELPER (see Using CLUSPROP_BUFFER_HELPER).

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_GRPGETRWCDWPROPVALUE_CPP
#define _CLUSDOCEX_GRPGETRWCDWPROPVALUE_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_GrpGetRWCDwPropValue
//
//  Retrieves a read-write common (RWC) group property value
//  of type DWORD.
//
//  Arguments:
//      IN HGROUP hGroup            Handle to the group.
//      IN LPWSTR lpszPropName      Name of property to find.
//      OUT LPDWORD lpdwPropValue   Returns the value of property.
//
// Return Value:
//      Win32 code
//
//--------------------------------------------------------------------
DWORD
GrpGetRWCDwPropValue(
    IN HGROUP hGroup,
    IN LPCWSTR lpszPropName,
    OUT LPDWORD lpdwPropValue
)
{
    DWORD dwResult = ERROR_SUCCESS;
    DWORD cbPropListSize = 0;

//  Retrieve a property list

    LPVOID lpPropList = ClusDocEx_GrpGetControlCodeOutput(
                            hGroup,
                            NULL,
                            CLUSCTL_GROUP_GET_COMMON_PROPERTIES,
                            &cbPropListSize );

    if( lpPropList != NULL )
    {

    //  Parse the property list for the property specified
    //  by lpszPropName.

        dwResult = ResUtilFindDwordProperty(
                       lpPropList,
                       cbPropListSize,
                       lpszPropName,
                       lpdwPropValue );

        if ( dwResult != ERROR_SUCCESS )
        {
        //  Add error handling if necessary.
        }

        LocalFree( lpPropList );

    }
    else
    {
        dwResult = GetLastError();
    }

    return dwResult;

}
//
//  end GrpGetRWCDwProp()
//--------------------------------------------------------------------
#endif


Using Object Handles

Most of the Cluster Object Management Functions require an object handle as an input parameter. Therefore, one of the first steps in any object management routine is to obtain a handle to the object, and one of the last steps is to close the handle.

The following table lists cluster object handles and the functions used to obtain the handles (note that the Server Cluster API does not define handles for resource types).

Handle | Function
Cluster handle | OpenCluster CloseCluster
Node handle | OpenClusterNode CloseClusterNode
Network handle | OpenClusterNetwork CloseClusterNetwork
Network interface handle | OpenClusterNetInterface CloseClusterNetInterface
Group handle | OpenClusterGroup CloseClusterGroup
Resource handle | OpenClusterResource CloseClusterResource

The following generalized procedure applies to opening a handle to any object. Substitute the name of the object (that is, node, network, network interface, group, or resource) for <Object>.

To Open an <Object> handle

  1. Review the recommentations and cautions related to object handles. See LPC and RPC Handles.
  2. Open a cluster handle by calling OpenCluster
  3. Open the <Object> handle by calling OpenCluster<Object>. Pass the cluster handle obtained from step 1 as well as the name of the object.
  4. Be sure to close any handles you no longer need. However, never close a cluster handle while object handles obtained from it are still in use.

Example

The following example provides two functions: ClusDocEx_OpenLocalClusterWithName and ClusDocEx_ResAddPossibleOwner. The first function returns an RPC cluster handle by using GetComputerName to supply a name for OpenCluster. The second function illustrates a call to AddClusterResourceNode, which requires a resource handle and a node handle.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_OPENLOCALCLUSTERWITHNAME
#define _CLUSDOCEX_OPENLOCALCLUSTERWITHNAME
//--------------------------------------------------------------------
//
//  ClusDocEx_OpenLocalClusterWithName
//
//  Gets the name of the local node, then
//  uses this name to open a cluster handle.
//
//  Returns an RPC cluster handle or NULL if unsuccessful.
//
//--------------------------------------------------------------------
HCLUSTER
ClusDocEx_OpenLocalClusterWithName()
{

    HCLUSTER hCluster        = NULL;
    DWORD    dwResult        = ERROR_SUCCESS;
    DWORD    cchNameSize     = MAX_COMPUTERNAME_LENGTH + 1;
    LPWSTR   lpszClusterName = (LPWSTR) LocalAlloc(
                                           LPTR,
                                           cchNameSize * sizeof( WCHAR ) );

    if( lpszClusterName != NULL )
    {

    //  Get the name of the local node.
    //  Using a name instead of NULL in OpenCluster
    //  creates an RPC handle.

        if( GetComputerName( lpszClusterName, &cchNameSize ) )
            hCluster = OpenCluster( lpszClusterName );

        dwResult = GetLastError();

        LocalFree( lpszClusterName );
    }

    SetLastError( dwResult );

    return hCluster;
}
//  end ClusDocEx_OpenLocalClusterWithName
//--------------------------------------------------------------------
#endif

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESADDPOSSIBLEOWNER_CPP
#define _CLUSDOCEX_RESADDPOSSIBLEOWNER_CPP
//--------------------------------------------------------------------
//  ClusDocEx_ResAddPossibleOwner()
//
//  Adds a node to a resource's list of possible owner nodes.
//
//  Arguments:
//      IN LPWSTR lpszResourceName  Name of the resource.
//      IN LPWSTR lpszNodeName      Name of the new possible owner.
//      IN LPWSTR lpszClusterName   Specifies the cluster name
//                                  Can be NULL.
//
//  Return Value:
//      Returns ERROR_SUCCESS if successful,
//      otherwise returns a Win32 error.
//--------------------------------------------------------------------
DWORD
ClusDocEx_ResAddPossibleOwner(
    IN LPWSTR lpszResourceName,
    IN LPWSTR lpszNodeName,
    IN LPWSTR lpszClusterName
)
{

    HCLUSTER  hCluster  = NULL;
    HNODE     hNode     = NULL;
    HRESOURCE hResource = NULL;
    DWORD     dwResult  = ERROR_SUCCESS;

//  Using a name produces an RPC handle.

    if( lpszClusterName == NULL )
        hCluster = ClusDocEx_OpenLocalClusterWithName();
    else
        hCluster = OpenCluster( lpszClusterName );

//  Verify handle before proceeding.

    if( hCluster == NULL )
    {
    //  Handle error.
        dwResult = GetLastError();
        goto endf;
    }

    hResource = OpenClusterResource( hCluster, lpszResourceName );

    if( hResource == NULL )
    {
    //  Handle error.
        dwResult = GetLastError();
        goto endf;
    }

    hNode = OpenClusterNode( hCluster, lpszNodeName );

    if( hNode == NULL )
    {
    //  Handle error.
        dwResult = GetLastError();
        goto endf;
    }

//  Add the node to the resource's possible owners list.

    dwResult = AddClusterResourceNode( hResource, hNode );

//  Note that hResource and hNode were obtained from the
//  same cluster handle. Thus they are both guaranteed
//  to be LPC or RPC handles. The cluster handle in this
//  implementation will always be an RPC handle.

endf:

//  Close all handles. Close the cluster handle last.

    if( hNode!= NULL )     CloseClusterNode( hNode );
    if( hResource!= NULL ) CloseClusterResource( hResource );
    if( hCluster!= NULL )  CloseCluster( hCluster );

    return dwResult;

}
//  end ClusDocEx_ResAddPossibleOwner
#endif


Using Control Codes

The following sections describe the tasks related to using control codes:

Topic | Tasks
Using Control Codes in Control Code Functions | Using control codes to get cluster information and change the cluster configuration through control codes.
Creating Control Codes | Describes the process of creating your own control codes.


Using Control Codes in Control Code Functions

To perform control code operations you need to call a control code function and specify a control code as one of the parameters. The control code determines the values of the other parameters and the general algorithm to use for the function call. There are two general algorithms for calling control code functions based on the type of operation the control code performs. The type of operation, in turn, is determined by the operation code that is part of each control code. For more information on the operations associated with control codes, see Control Code Architecture.

The following sections describe these algorithms.

Section | Control code operation
Getting Information with Control Codes | ENUM_COMMON_PROPERTIES ENUM_PRIVATE_PROPERTIES GET_CHARACTERISTICS GET_COMMON_PROPERTIES GET_CRYPTO_CHECKPOINTS GET_FLAGS GET_ID GET_NAME GET_NETWORK_NAME GET_PRIVATE_PROPERTIES GET_REGISTRY_CHECKPOINTS GET_REQUIRED_DEPENDENCIES GET_RESOURCE_TYPE GET_RO_COMMON_PROPERTIES GET_RO_PRIVATE_PROPERTIES STORAGE_GET_AVAILABLE_DISKS STORAGE_GET_DISK_INFO
Changing the Cluster Configuration with Control Codes | ADD_CRYPTO_CHECKPOINTS ADD_REGISTRY_CHECKPOINTS DELETE_CRYPTO_CHECKPOINTS DELETE_REGISTRY_CHECKPOINTS SET_COMMON_PROPERTIES SET_NAME SET_PRIVATE_PROPERTIES VALIDATE_COMMON_PROPERTIES VALIDATE_PRIVATE_PROPERTIES


Getting Information with Control Codes

Control codes that get information from the cluster use the control code function's output buffer in which to return data. Although the nature of the returned data can vary, the same set of procedures apply.

To get information with a control code

  1. Allocate an output buffer.
  2. Call the control code function.
  3. Test the return value. If the function returns ERROR_MORE_DATA, use the lpcbBytesReturned parameter to reallocate the buffer and call the function again.
  4. If successful, you now have data in the output buffer. The lpcbBytesReturned parameter indicates the size of the data in bytes.

The returned buffer may contain a DWORD, a string, or a value or property list, as specified by the control code.

Example

The following example is a collection of functions that encapsulate the above procedure for various object types.

//////////////////////////////////////////////////////////////////////
//
//  ClusDocEx_GetControlCodeOutput.cpp
//
//  Functions that encapsulate the algorithm for using control
//  codes that return data in an output buffer.
//
//  Contains the following functions
//      ClusDocEx_CluGetControlCodeOutput
//      ClusDocEx_GrpGetControlCodeOutput
//      ClusDocEx_NetGetControlCodeOutput
//      ClusDocEx_NICGetControlCodeOutput
//      ClusDocEx_NodGetControlCodeOutput
//      ClusDocEx_ResGetControlCodeOutput
//      ClusDocEx_RtpGetControlCodeOutput
//
//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_GRPGETCONTROLCODEOUTPUT
#define _CLUSDOCEX_GRPGETCONTROLCODEOUTPUT
//--------------------------------------------------------------------
//
//  ClusDocEx_GrpGetControlCodeOutput
//
//  Encapsulates group control code operations that retrieve
//  data into an output buffer.
//
//  Call LocalFree to free the memory allocated by this function.
//
//  Arguments:
//      hGroup         [in]  Handle to the group to affect.
//      hNode          [in]  Optional node handle.
//      dwControlCode  [in]  Specifies the control code operation.
//      lpcbResultSize [out] Byte size of the resulting data.
//
//
//  Return Value:
//      If successful, returns a pointer to a buffer containing the
//      results of the control code operation. The nature of the data
//      returned depends on the control code.
//      If unsuccessful, returns NULL. Call GetLastError for more information.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_GrpGetControlCodeOutput
(
    IN HGROUP hGroup,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
)
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = sizeof( DWORD );
    LPVOID lpOutBuffer  = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Call the control code function:

    dwResult = ClusterGroupControl(
                   hGroup,          // Handle to the affected group.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );

//  Reallocate if necessary.

    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbResultSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
                ClusterGroupControl(
                   hGroup,          // Handle to the affected group.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );
    }

//  Handle errors.

    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbResultSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;
}
//  end ClusDocEx_GrpGetControlCodeOutput
//--------------------------------------------------------------------
#endif

#ifndef _CLUSDOCEX_NETGETCONTROLCODEOUTPUT
#define _CLUSDOCEX_NETGETCONTROLCODEOUTPUT
//--------------------------------------------------------------------
//
//  ClusDocEx_NetGetControlCodeOutput
//
//  Encapsulates network control code operations that retrieve
//  data into an output buffer.
//
//  Call LocalFree to free the memory allocated by this function.
//
//  Arguments:
//      hNetwork       [in]  Handle to the network to affect.
//      hNode          [in]  Optional node handle.
//      dwControlCode  [in]  Specifies the control code operation.
//      lpcbResultSize [out] Byte size of the resulting data.
//
//
//  Return Value:
//      If successful, returns a pointer to a buffer containing the
//      results of the control code operation. The nature of the data
//      returned depends on the control code.
//      If unsuccessful, returns NULL. Call GetLastError for more information.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_NetGetControlCodeOutput
(
    IN HNETWORK hNetwork,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
)
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = sizeof( DWORD );
    LPVOID lpOutBuffer  = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Call the control code function:

    dwResult = ClusterNetworkControl(
                   hNetwork,        // Handle to the affected network.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );

//  Reallocate if necessary.

    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbResultSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
                ClusterNetworkControl(
                   hNetwork,        // Handle to the affected network.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );
    }

//  Handle errors.

    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbResultSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;
}
//  end ClusDocEx_NetGetControlCodeOutput
//--------------------------------------------------------------------
#endif

#ifndef _CLUSDOCEX_NICGETCONTROLCODEOUTPUT
#define _CLUSDOCEX_NICGETCONTROLCODEOUTPUT
//--------------------------------------------------------------------
//
//  ClusDocEx_NICGetControlCodeOutput
//
//  Encapsulates network interface control code operations that
//  retrieve data into an output buffer.
//
//  Call LocalFree to free the memory allocated by this function.
//
//  Arguments:
//      hNetInterface  [in]  Handle to the network interface.
//      hNode          [in]  Optional node handle.
//      dwControlCode  [in]  Specifies the control code operation.
//      lpcbResultSize [out] Byte size of the resulting data.
//
//
//  Return Value:
//      If successful, returns a pointer to a buffer containing the
//      results of the control code operation. The nature of the data
//      returned depends on the control code.
//      If unsuccessful, returns NULL. Call GetLastError for more info.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_NICGetControlCodeOutput
(
    IN HNETINTERFACE hNetInterface,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
)
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = sizeof( DWORD );
    LPVOID lpOutBuffer  = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Call the control code function:

    dwResult = ClusterNetInterfaceControl(
                   hNetInterface,   // Handle to the affected NIC.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );

//  Reallocate if necessary.

    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbResultSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
                ClusterNetInterfaceControl(
                   hNetInterface,   // Handle to the affected NIC.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );
    }

//  Handle errors.

    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbResultSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;
}
//  end ClusDocEx_NICGetControlCodeOutput
//--------------------------------------------------------------------
#endif

#ifndef _CLUSDOCEX_NODGETCONTROLCODEOUTPUT
#define _CLUSDOCEX_NODGETCONTROLCODEOUTPUT
//--------------------------------------------------------------------
//
//  ClusDocEx_NodGetControlCodeOutput
//
//  Encapsulates node control code operations that retrieve
//  data into an output buffer.
//
//  Call LocalFree to free the memory allocated by this function.
//
//  Arguments:
//      hNode          [in]  Handle to the node to affect.
//      hHostNode      [in]  Optional node handle.
//      dwControlCode  [in]  Specifies the control code operation.
//      lpcbResultSize [out] Byte size of the resulting data.
//
//
//  Return Value:
//      If successful, returns a pointer to a buffer containing the
//      results of the control code operation. The nature of the data
//      returned depends on the control code.
//      If unsuccessful, returns NULL. Call GetLastError for more info.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_NodGetControlCodeOutput
(
    IN HNODE hNode,
    IN HNODE hHostNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
)
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = sizeof( DWORD );
    LPVOID lpOutBuffer  = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Call the control code function:

    dwResult = ClusterNodeControl(
                   hNode,           // Handle to the affected node.
                   hHostNode,       // Optional node handle.
                   dwControlCode,   // Control code
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );

//  Reallocate if necessary.

    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbResultSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
                ClusterNodeControl(
                   hNode,           // Handle to the affected node.
                   hHostNode,       // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );
    }

//  Handle errors.

    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbResultSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;
}
//  end ClusDocEx_NodGetControlCodeOutput
//--------------------------------------------------------------------
#endif

#ifndef _CLUSDOCEX_RESGETCONTROLCODEOUTPUT
#define _CLUSDOCEX_RESGETCONTROLCODEOUTPUT
//--------------------------------------------------------------------
//
//  ClusDocEx_ResGetControlCodeOutput
//
//  Encapsulates resource control code operations that retrieve
//  data into an output buffer.
//
//  Call LocalFree to free the memory allocated by this function.
//
//  Arguments:
//      hResource      [in]  Handle to the resource to affect.
//      hNode          [in]  Optional node handle.
//      dwControlCode  [in]  Specifies the control code operation.
//      lpcbResultSize [out] Byte size of the resulting data.
//
//
//  Return Value:
//      If successful, returns a pointer to a buffer containing the
//      results of the control code operation. The nature of the data
//      returned depends on the control code.
//      If unsuccessful, returns NULL. Call GetLastError for more info.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_ResGetControlCodeOutput
(
    IN HRESOURCE hResource,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
)
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = sizeof( DWORD );
    LPVOID lpOutBuffer  = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Call the control code function:

    dwResult = ClusterResourceControl(
                   hResource,       // Handle to the affected resource.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );

//  Reallocate if necessary.

    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbResultSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
                ClusterResourceControl(
                   hResource,       // Handle to the affected resource.
                   hNode,           // Optional node handle
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );
    }

//  Handle errors.

    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbResultSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;
}
//  end ClusDocEx_ResGetControlCodeOutput
//--------------------------------------------------------------------
#endif

#ifndef _CLUSDOCEX_RTPGETCONTROLCODEOUTPUT
#define _CLUSDOCEX_RTPGETCONTROLCODEOUTPUT
//--------------------------------------------------------------------
//
//  ClusDocEx_RtpGetControlCodeOutput
//
//  Encapsulates resource type control code operations that retrieve
//  data into an output buffer.
//
//  Call LocalFree to free the memory allocated by this function.
//
//  Arguments:
//      lpszType       [in]  Name of the resource type.
//      hCluster       [in]  Cluster handle.
//      hNode          [in]  Optional node handle.
//      dwControlCode  [in]  Specifies the control code operation.
//      lpcbResultSize [out] Byte size of the resulting data.
//
//
//  Return Value:
//      If successful, returns a pointer to a buffer containing the
//      results of the control code operation. The nature of the data
//      returned depends on the control code.
//      If unsuccessful, returns NULL. Call GetLastError for more info.
//
//--------------------------------------------------------------------
LPVOID
ClusDocEx_RtpGetControlCodeOutput
(
    IN LPWSTR lpszType,
    IN HCLUSTER hCluster,
    IN HNODE hNode,
    IN DWORD dwControlCode,
    OUT LPDWORD lpcbResultSize
)
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = sizeof( DWORD );

    LPVOID lpOutBuffer  = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Call the control code function:

    dwResult = ClusterResourceTypeControl(
                   hCluster,        // Cluster handle.
                   lpszType,        // name of the resource type.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );

//  Reallocate if necessary.

    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbResultSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
                ClusterResourceTypeControl(
                   hCluster,        // Cluster handle.
                   lpszType,        // name of the resource type.
                   hNode,           // Optional node handle.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer. Not used.
                   0,               // Byte size of input buffer.
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of output buffer.
                   lpcbResultSize   // Byte size of resulting data.
                );
    }

//  Handle errors.

    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbResultSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;
}
//  end ClusDocEx_RtpGetControlCodeOutput
//--------------------------------------------------------------------
#endif

//////////////////////////////////////////////////////////////////////

//  end ClusDocEx_GetControlCodeOutput.cpp


Changing the Cluster Configuration with Control Codes

Control codes that send data to the cluster in the control code function's input buffer use the following procedure:

To use an "input" control code

  1. Refer to the control code reference to determine what data must be passed in the input buffer and what the format should be. You may need to construct a value list or property list and pass that as the input buffer. See Creating Property Lists and Creating Value Lists for more information.
  2. Allocate and populate the input buffer.
  3. Call the function.
  4. Test the return value and take appropriate action based on success/failure.

Example

The following example demonstrates the use of the "input" control code CLUSCTL_RESOURCE_SET_NAME.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESSETNAME_CPP
#define _CLUSDOCEX_RESSETNAME_CPP

//--------------------------------------------------------------------
//
//  ClusDocEx_SetResourceName
//
//      Changes the name of a resource.
//
//  Arguments:
//
//      HRESOURCE hResource       Handle to the resource.
//
//      LPWSTR    lpszResName     New resource name.
//
//  Return Value:
//
//      If successful, ERROR_SUCCESS, otherwise a Win32 error code.
//
//--------------------------------------------------------------------
DWORD
ClusDocEx_SetResourceName
(
    HRESOURCE hResource,
    LPWSTR    lpszResName
)
{
    DWORD dwResult = ERROR_SUCCESS;

    if( ( hResource != NULL ) || ( lpszResName != NULL ) )
    {
        DWORD cbNameSize = ( lstrlenW( lpszResName ) + 1 ) *
                           sizeof( WCHAR );

        dwResult = ClusterResourceControl( hResource,
                                           NULL,
                                           CLUSCTL_RESOURCE_SET_NAME,
                                           lpszResName,
                                           cbNameSize,
                                           NULL,
                                           0,
                                           NULL );

    }
    else
    {
        dwResult = ERROR_BAD_ARGUMENTS;
    }

    return dwResult;
}
#endif


Creating Control Codes

If you are creating a resource type, you may need to create one or more control codes to expose specialized operations to other developers. By supporting these custom control codes in your resource DLL, you allow programmers to initiate the operations with ClusterResourceControl or ClusterResourceTypeControl.

For example, suppose you create a resource type for an application that generates a log file. You want other programmers to be able to read and change the location of the log file in their applications. To accomplish this, you could define control codes such as:

MYAPPNAME_GET_LOG_FILE_LOCATION

MYAPPNAME_SET_LOG_FILE_LOCATION

Programmers would use the control codes as ClusterResourceControl or ClusterResourceTypeControl parameters. The Cluster service would pass the control code to your resource DLL, which would handle the operation (the Resource Monitor, or course, would not know how to handle it).

To create a user-defined control code

  1. Review control code architecture.
  2. Use the CLUSCTL_USER_CODE macro to create the control code.
  3. Implement the control code in the ResourceControl and ResourceTypeControl entry points of your resource DLL.
  4. Document the procedures for using the control code, especially what the contents of the ClusterResourceControl and ClusterResourceTypeControl input and output buffers should be.

Example

The following code creates three control codes for a fictional resource type called "ServiceX".

//////////////////////////////////////////////////////////////////////
//  DEFINE CONTROL CODES
//////////////////////////////////////////////////////////////////////

//  Object code

    #define SERVICEX_OBJECT_CODE 221

//  Function codes

    typedef enum SERVICEX_FUNCTION_CODES
    {
        SVCX_GET_LOGFILE_LOCATION = 22101,
        SVCX_SET_LOGFILE_LOCATION = 22102
    }
    SERVICEX_FUNCTION_CODES;

//  Create the control codes.

    typedef enum SERVICEX_CONTROL_CODES
    {
        SERVICEX_GET_LOGFILE_LOCATION =
            CLUSCTL_USER_CODE(
                SERVICEX_OBJECT_CODE,
                SVCX_GET_LOGFILE_LOCATION ) | CLUS_ACCESS_READ,

        SERVICEX_SET_LOGFILE_LOCATION =
            CLUSCTL_USER_CODE(
                SERVICEX_OBJECT_CODE,
                SVCX_SET_LOGFILE_LOCATION ) | CLUS_ACCESS_ANY

    }
    SERVICEX_CONTROL_CODES;

//--------------------------------------------------------------------
//  TODO:  Support these control codes in the ResourceControl and
//         ResourceTypeControl entry points of the "ServiceX"
//         resource DLL.  Document how the codes should be used.
//--------------------------------------------------------------------

//////////////////////////////////////////////////////////////////////


Creating Cluster-Aware Applications

The following sections attempt to reduce the general task of creating a cluster-aware application to smaller tasks that lead to specific API elements, procedures, and examples. The goal is to help you identify and implement sets of procedures that create the level of cluster interaction your application requires.

Task | Description
Receiving Cluster Events | Tasks related to creating a notification port to receive notifications of cluster events such as property changes or the creation and deletion of objects.
Getting Cluster Information | "Read-only" tasks related to discovering information about the state and configuration of the cluster: enumerating objects, retrieving properties, checking object states, and getting object-specific data such as required dependencies, available disks, and preferred owner nodes.
Changing the Cluster Configuration | Tasks concerned with making changes to the cluster such as changing properties, changing object states, creating resources, and configuring groups.

Many of the tasks presented above depend on familiarity with certain features of the API such as value lists, property lists, and property tables.


Receiving Cluster Events

An application or resource DLL can monitor events occurring within the cluster by creating a notification port. A notification port stores information about events as a queue of notifications (messages). Once a notification port has been created, an application typically spawns a thread to monitor the port, periodically retrieving event data and taking appropriate action in response to the events.

An application can create multiple notification ports, but this is usually unnecessary. One notification port per application per cluster is sufficient in most cases to monitor any events of interest, and it requires only one thread.

Note that the Cluster Automation Server does not support event monitoring at this time.

For information on how to use notification ports, see the following sections:

Creating a Notification Port

Adding Events to a Notification Port

Retrieving Events from a Notification Port

Closing a Notification Port

Notification Port Example


Creating a Notification Port

Applications perform the following steps to create a notification port:

  1. Spawn a separate thread to create and monitor the port.
  2. Call CreateClusterNotifyPort. For the initial call, set hChange to INVALID_HANDLE_VALUE so that a new handle will be created. Subsequent calls can specify hChange to add more events to the port.
  3. Set the dwFilter parameter to one or more events of interest, using the OR operator ( | ) to specify multiple events. For example, if an application should be informed when there is any change to the cluster's resource types, it would set dwFilter as follows:
    dwFilter = CLUSTER_CHANGE_RESOURCE_TYPE_ADDED |
           CLUSTER_CHANGE_RESOURCE_TYPE_DELETED
  4. Set the dwNotifyKey parameter to a value that identifies the events specified by dwFilter. When you retrieve events from the port, all events of type <dwFilter> will be "flagged" with a value of <dwNotifyKey>. You can use dwNotifyKey like an index to differentiate different event types in the same port. For example, the following code fragment creates a notification port for monitoring resource and cluster database events such that any resource-related event will return a dwNotifyKey value of ResourceEvents, and any cluster database event will return a dwNotifyKey value of DatabaseEvents:
    DWORD ResourceEvents = CLUSTER_CHANGE_RESOURCE_ADDED    |
                       CLUSTER_CHANGE_RESOURCE_DELETED  |
                       CLUSTER_CHANGE_RESOURCE_PROPERTY |
                       CLUSTER_CHANGE_RESOURCE_STATE;

DWORD DatabaseEvents = CLUSTER_CHANGE_REGISTRY_ATTRIBUTES |
                       CLUSTER_CHANGE_REGISTRY_NAME       |
                       CLUSTER_CHANGE_REGISTRY_SUBTREE    |
                       CLUSTER_CHANGE_REGISTRY_VALUE;

hChange = CreateClusterNotifyPort( (HCHANGE)INVALID_HANDLE_VALUE,
                                   hCluster,
                                   ResourceEvents,   // dwFilter
                                   ResourceEvents ); // dwNotifyKey

hChange = CreateClusterNotifyPort( hChange,
                                   hCluster,
                                   DatabaseEvents,
                                   DatabaseEvents );


Adding Events to a Notification Port

After the port has been created (see Creating a Notification Port), applications can add other event types to the port by calling RegisterClusterNotify. Like CreateClusterNotifyPort, RegisterClusterNotify allows you to specify the type of events (dwFilter) and associate those events with a key (dwNotifyKey). RegisterClusterNotify also allows you to specify an object handle in the hObject parameter, enabling you to receive event notifications on a per-handle basis.

The following code fragment adds resource-specific events to an existing notification port. Any events of a type defined by ResourceEvents that involve hMyResource will generate notifications identified by a dwNotifyKey of dwMyResource:

hMyResource = OpenClusterResource( hCluster, L"MyResource" );
dwMyResource = (DWORD)hMyResource;
dwResult = RegisterClusterNotify( hChange,
                                  ResourceEvents,
                                  hMyResource,
                                  dwMyResource );


Retrieving Events from a Notification Port

To retrieve event notifications, set up a program loop that calls GetClusterNotify. This function will return the type of event (dwFilterType), the event key or index (dwNotifyKey), and the name of the object affected (lpszName). Use this information to take appropriate action.

Note the potential for a race condition if multiple threads access the same notification port. For example, one thread could be calling CloseClusterNotifyPort to close the notification port while another thread, which has called GetClusterNotify, is waiting to retrieve information from the same port. Prevent this problem by having the thread that is calling GetClusterNotify check for a CLUSTER_CHANGE_HANDLE_CLOSE event.

The following code fragment detects when a resource is added to the cluster and takes action if the new resource is a Physical Disk.

// code fragment; all error handling omitted
while( 1 )
{
dwStatus = GetClusterNotify( hChange,
                             &dwNotifyKey,
                             &dwFilterType,
                             lpszObjName,
                             &cchObjNameSize
                             500 );
if( dwStatus == ERROR_SUCCESS )
{
    switch( dwNotifyKey )
    {
    case ResourceEvents:
        if( dwFilterType == CLUSTER_CHANGE_RESOURCE_ADDED )
        {
            // Use the object name to get a resource handle and check the resource type.
            hResource = OpenClusterResource( hCluster, lpszObjName );
            dwResult = ClusterResourceControl( hResource,
                                               NULL,
                                               CLUSCTL_RESOURCE_GET_RESOURCE_TYPE,
                                               NULL,
                                               0,
                                               lpszResType,
                                               cbAllocated,
                                               cbReturned );
            if( lstrcmpi( lpszResType, L"Physical Disk" ) == 0 )
            {
                // perform some action
            }
        }
        break;

    case 2:
    default:
        break;

    } // end switch
} // end if
} // end while


Closing a Notification Port

Applications close a notification port by calling CloseClusterNotifyPort.

Note the potential for a race condition if multiple threads access the same notification port. For example, one thread could be calling CloseClusterNotifyPort to close the notification port while another thread, which has called GetClusterNotify, is waiting to retrieve information from the same port.

Prevent this problem by having the thread that is calling GetClusterNotify check for a CLUSTER_CHANGE_HANDLE_CLOSE event.


Notification Port Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

//  Constants and global data

    const DWORD MYAPP_EVENTS = ( CLUSTER_CHANGE_GROUP_ADDED      |
                                 CLUSTER_CHANGE_GROUP_DELETED    |
                                 CLUSTER_CHANGE_GROUP_STATE      |
                                 CLUSTER_CHANGE_RESOURCE_ADDED   |
                                 CLUSTER_CHANGE_RESOURCE_DELETED |
                                 CLUSTER_CHANGE_RESOURCE_STATE   |
                                 CLUSTER_CHANGE_HANDLE_CLOSE );

int main()
{
    HCLUSTER  hCluster        = NULL;
    HGROUP    hGroup          = NULL;
    HRESOURCE hRes            = NULL;
    DWORD     dwEventThreadID = 0;
    DWORD     dwExitCode      = 0;
    HANDLE    hEventThread    = NULL;
    BOOL      bExit           = FALSE;

    hCluster = ClusDocEx_OpenLocalClusterWithName();

    if ( hCluster )
    {
        hEventThread = CreateThread(
                            NULL, 0, ClusDocEx_EventPort,
                            (LPVOID) hCluster, 0, &dwEventThreadID );

        hGroup = CreateClusterGroup( hCluster, L"EventDemoGroup" );

        if( hGroup )
        {
            hRes = CreateClusterResource(
                       hGroup, L"EventDemoShare", L"File Share", 0 );

            if( hRes )
            {
                OnlineClusterGroup( hGroup, NULL );
                OfflineClusterGroup( hGroup );
                DeleteClusterResource( hRes );
                CloseClusterResource( hRes );
            }

            DeleteClusterGroup( hGroup );
            CloseClusterGroup( hGroup );
        }

        CloseCluster( hCluster );
    }

    for( ; ; )
    {
        bExit = GetExitCodeThread( hEventThread, &dwExitCode );
        if( bExit && ( dwExitCode != STILL_ACTIVE ) )
            break;
    }

    if( hEventThread )
        CloseHandle( hEventThread );

    return 0;
}

DWORD WINAPI ClusDocEx_EventPort( LPVOID hCluster )
{
    HCHANGE hChange       = (HCHANGE)INVALID_HANDLE_VALUE ;
    DWORD   dwFilterType;
    DWORD   dwNotifyKey;
    DWORD   dwStatus;
    DWORD   cbNameSize    = ClusDocEx_DEFAULT_CCH;
    LPWSTR  pszObjectName = new WCHAR[cbNameSize];
    bool    bExit = false;

    if( hCluster != NULL )
    {
        hChange = CreateClusterNotifyPort( hChange,
                                           (HCLUSTER) hCluster,
                                           MYAPP_EVENTS,   //  dwFilter
                                           MYAPP_EVENTS ); //  dwNotifyKey

        while( hChange && !bExit )
        {
        //  Reset name size

            cbNameSize = ClusDocEx_DEFAULT_CB;

            dwStatus = GetClusterNotify( hChange,
                                         &dwNotifyKey,
                                         &dwFilterType,
                                         pszObjectName,
                                         &cbNameSize,
                                         2500);

            if( dwStatus == ERROR_SUCCESS )
            {
                switch( dwFilterType )
                {
                case CLUSTER_CHANGE_RESOURCE_STATE:
                    wprintf( L"Thread: Receiving resource state change event.\n" );
                    break;

                case CLUSTER_CHANGE_GROUP_STATE:
                    wprintf( L"Thread: Receiving group state change event.\n" );
                    break;

                case CLUSTER_CHANGE_RESOURCE_ADDED:
                    wprintf( L"Thread: Receiving add resource event.\n" );
                    break;

                case CLUSTER_CHANGE_GROUP_ADDED:
                    wprintf( L"Thread: Receiving add group event.\n" );
                    break;

                case CLUSTER_CHANGE_RESOURCE_DELETED:
                    wprintf( L"Thread: Receiving delete resource event.\n" );
                    break;

                case CLUSTER_CHANGE_GROUP_DELETED:
                   wprintf( L"Thread: Receiving delete group event.\n" );
                    break;
                case CLUSTER_CHANGE_HANDLE_CLOSE:
                    wprintf( L"Thread: Receiving cluster handle close event.\n" );
                    bExit = true;
                    break;
                }
            }
            else if( dwStatus == WAIT_TIMEOUT )
            {
            //  If any call to GetClusterNotify times out
            //  (exceeds dwMilliseconds, which is 2500 in this case)
            //  any code here will be executed.
            }

        }

        if( hChange )
            CloseClusterNotifyPort( hChange );
    }

    LocalFree( pszObjectName );
    return dwStatus;
}


Getting Information From the Cluster

Each cluster object, including the cluster itself, is associated with several pieces of information that describe the object's identity, configuration, and relationships to other objects. Accessing this information can be broken down into tasks which are presented in the following topics.

Topic | Description
Enumerating Objects | Describes the process of listing objects that are related to another object in some way. For example, listing the nodes in a cluster, the resources in a group, or the dependents of a resource.
Getting Object States | Describes how to obtain the current state of an object. An object's state indicates its operational status and availability with respect to the cluster.
Getting Object Properties | Describes how to retrieve the properties of an object.
Getting Object Information | Lists the most common information-retrieval tasks and the API elements that support them.


Enumerating Objects

Enumeration is the process of listing all objects of a given type that are contained by, or that relate to, another object. For example, typical enumeration routines list all of the resources in a group, all of the dependencies of a resource, or all of the nodes in a cluster. Enumeration allows you to search for objects with specific attributes or create and display object inventories.

The following table lists the kinds of information available through enumeration and the API element(s) used to perform the enumeration.

Objects to enumerate | Function
dependencies of a resource | ClusterResourceEnum
dependents of a resource | ClusterResourceEnum
groups in the cluster | ClusterEnum
network interfaces available to a network | ClusterNetworkEnum
network interfaces in a node | ClusterNodeEnum
networks in the cluster | ClusterEnum
nodes in a cluster | ClusterEnum
possible owner nodes of a resource | ClusterResourceEnum
possible owner nodes of a resource type | ClusterResourceTypeEnum
preferred owner nodes of a group | ClusterGroupEnum
resource types in a cluster | ClusterEnum
resources in a group | ClusterGroupEnum
resources in a cluster | ClusterEnum
network interfaces in a cluster | ClusterEnum

The following generalized procedure applies to the enumeration functions of any object. Substitute the name of the object (that is, node, network, group, or resource) for <Object>.

To enumerate objects associated with <Object>

  1. Allocate an output buffer to receive the names of the objects to be enumerated. Note that the size of the buffer, passed as an input parameter, must be expressed as a count of characters and not a count of bytes.
  2. Open an enumeration handle by calling Cluster<Object>OpenEnum, specifying the objects to be enumerated in the dwType parameter.
  3. Execute a loop, performing the following steps with each iteration:
    1. Call Cluster<Object>Enum to retrieve the name of the next object into the lpszName output buffer.
    2. If Cluster<Object>Enum returns ERROR_MORE_DATA, reallocate the output buffer based on the count of characters returned in the lpcchName parameter. Note that the terminating NULL is not included in the count.
    3. If Cluster<Object>Enum returns ERROR_NO_MORE_ITEMS, terminate the loop.
    4. Use the lpszName parameter according to the needs of the application. For example, lpszName could be used to open a handle to the object, which could then be used to retrieve the object's properties.
    5. Increment the dwIndex parameter.
  4. Close the enumeration handle by calling Cluster<Object>CloseEnum.
  5. Deallocate the output buffer.

Example Code

The following example enumerates the resources in a group and returns the results in a value list. This example calls other example functions presented elsewhere in this documentation. To locate these example functions, see the Index of Examples. Among these example functions is ClusDocEx_ListEntrySize, which is defined in ClusDocEx.h.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_GRPENUMRESOURCES
#define _CLUSDOCEX_GRPENUMRESOURCES
//--------------------------------------------------------------------
//
//  ClusDocEx_GrpEnumResources
//
//  Enumerates the resources in a group and returns the names
//  in a value list.
//
//    IN HGROUP hGroup            Group handle.
//    IN OUT LPVOID lpOutBuffer   Allocated buffer for value list.
//    IN DWORD  cbOutBufferSize   Byte size of out buffer.
//    OUT LPDWORD lpcbResultSize  Byte size of resulting data.
//
//  Return Value.....lpOutBuffer...lpcbResultSize
//  ERROR_SUCCESS    value list    byte size of list
//  ERROR_MORE_DATA  undefined     byte size of list
//  Other            undefined     undefined
//
//--------------------------------------------------------------------
DWORD
ClusDocEx_GrpEnumResources(
    IN HGROUP hGroup,
    IN OUT LPVOID lpOutBuffer,
    IN DWORD  cbOutBufferSize,
    OUT LPDWORD lpcbResultSize
)
{

//  hGroup       Group handle
//  hGroupEnum   Enumeration handle
//  dwResult     Captures return values
//  dwIndex      Enumeration index
//  dwType       Type of object to enumerate
//  cbNameAlloc  Allocated size of the name buffer
//  cchNameSize  Size of the resulting name as a count of wchars
//  cbNameSize   Size of the resulting name buffer in bytes
//  cbEntrySize  Size of the value list entry containing lpszName
//  lpszName     Buffer to hold enumerated names
//  cbh          Value list builder

    HGROUPENUM hGroupEnum = NULL;

    DWORD dwResult = ERROR_SUCCESS;
    DWORD dwIndex  = 0;
    DWORD dwType   = CLUSTER_GROUP_ENUM_CONTAINS;

    DWORD cbNameAlloc = ClusDocEx_DEFAULT_CB;
    DWORD cchNameSize = 0;
    DWORD cbNameSize  = 0;
    DWORD cbEntrySize = 0;

    CLUSPROP_BUFFER_HELPER cbh;

    *lpcbResultSize = 0;

    LPWSTR lpszName = (LPWSTR) LocalAlloc( LPTR,
                                           cbNameAlloc );
    if ( lpszName == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Open enumeration handle.

    hGroupEnum = ClusterGroupOpenEnum( hGroup, dwType );

    if ( hGroupEnum == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Prepare to build value list.  See "Using CLUSPROP_BUFFER_HELPER"

    cbh.pb = (LPBYTE) lpOutBuffer;

//  Enumeration loop.

    while( dwResult == ERROR_SUCCESS )
    {

    //  Make sure cchNameSize correctly reports the allocated size.

        cchNameSize = cbNameAlloc / sizeof( WCHAR );

        dwResult = ClusterGroupEnum( hGroupEnum,
                                     dwIndex,
                                     &dwType,
                                     lpszName,
                                     &cchNameSize );

    //  Reallocation routine

       if ( dwResult == ERROR_MORE_DATA )
        {
            cchNameSize++;  // terminating NULL

            cbNameAlloc = cchNameSize / sizeof( WCHAR );

            LocalFree( lpszName );

            lpszName = (LPWSTR) LocalAlloc( LPTR,
                                            cbNameAlloc );

            if ( lpszName == NULL )
            {
                dwResult = GetLastError();
                goto endf;
            }

            dwResult = ClusterGroupEnum( hGroupEnum,
                                         dwIndex,
                                         &dwType,
                                         lpszName,
                                         &cchNameSize );
        }

        if( dwResult == ERROR_SUCCESS )
        {

        //  Calculate sizes

            cchNameSize++;  // terminating NULL

            cbNameSize = cchNameSize * sizeof( WCHAR );

        //  ClusDocEx_ListEntrySize is defined in ClusDocEx.h

            cbEntrySize = ClusDocEx_ListEntrySize( cbNameSize );

        //  Update required size

            *lpcbResultSize += cbEntrySize;

            if( *lpcbResultSize < cbOutBufferSize )
            {

            //  Add value list entry

                cbh.pStringValue->Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;

                cbh.pStringValue->cbLength = cbNameSize;

                lstrcpyW( cbh.pStringValue->sz, lpszName );

                cbh.pb += cbEntrySize;

            }

        }
        else if( dwResult == ERROR_NO_MORE_ITEMS )
        {

        //  Add the endmark

            *lpcbResultSize += sizeof( DWORD );

            if( *lpcbResultSize <= cbOutBufferSize )
                *cbh.pdw = CLUSPROP_SYNTAX_ENDMARK;

        }
        else // enum failed for another reason
        {

        //  We don't have a reliable size

            *lpcbResultSize = 0;
        }

        dwIndex++;
    }
    //  end while

endf:

    cbh.pb = NULL;

    LocalFree( lpszName );

    if ( hGroupEnum != NULL )
        ClusterGroupCloseEnum( hGroupEnum );

    if( *lpcbResultSize > cbOutBufferSize )
        dwResult = ERROR_MORE_DATA;

    return dwResult;

}
//  end ClusDocEx_GrpEnumResources
//--------------------------------------------------------------------
#endif


Getting Object States

The state of a cluster object indicates the operational status and availability of the object with respect to the cluster. Applications can check an object's state to verify that a requested state change has taken place, to determine whether an object is available for use, or simply to display the information to a user.

To check an object's state

  1. Use one of the following API elements to obtain state information about an object.
    Cluster object | Function
    Cluster | GetNodeClusterState
    Group GetClusterGroupState
    Network GetClusterNetworkState
    Network Interface GetClusterNetInterfaceState
    Resource GetClusterResourceState

  2. The function will return an enumerated constant describing the object's state. If your routine will display the information to users, translate the numeric value into a meaningful message.

Example Code

The following example calls GetClusterResourceState and returns a string describing the state of a resource.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESDESCRIBESTATE_CPP
#define _CLUSDOCEX_RESDESCRIBESTATE_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_ResDescribeState
//
//  Returns a description of the current state of a resource.
//  Callers must call LocalFree on the returned pointer.
//
//  Arguments:
//      IN HRESOURCE hResource    Handle to the resource to poll.
//
//  Return Value
//      String describing the state of the resource.  Call LocalFree
//      on the returned pointer.
//
//--------------------------------------------------------------------
LPWSTR
ClusDocEx_ResDescribeState( HRESOURCE hResource )
{
    DWORD dwState;

    LPWSTR lpszStatus = (LPWSTR) LocalAlloc( LPTR, ClusDocEx_DEFAULT_CB );

    dwState = GetClusterResourceState(
                  hResource,
                  NULL,
                  NULL,
                  NULL,
                  NULL );

    if( lpszStatus != NULL )
    {
        switch( dwState )
        {
        case ClusterResourceInitializing:
            lpszStatus = L"Initializing: The resource is performing initialization.";
            break;

        case ClusterResourceOnline:
            lpszStatus = L"Online: The resource is operational and functioning normally.";
            break;

        case ClusterResourceOffline:
            lpszStatus = L"Offline: The resource is not operational.";
            break;

        case ClusterResourceFailed:
            lpszStatus = L"Failed: The resource not operational.";
            break;

        case ClusterResourcePending:
            lpszStatus = L"Pending: The resource is in the process of coming online or going offline.";
            break;

        case ClusterResourceOnlinePending:
            lpszStatus = L"Online Pending: The resource is in the process of coming online.";
            break;

        case ClusterResourceOfflinePending:
            lpszStatus = L"Offline Pending: The resource is in the process of going offline.";
            break;

        default:
            lpszStatus = L"Unknown state";
            break;
        }
    }

    return lpszStatus;
}
//  end ClusDocEx_ResDescribeState
//--------------------------------------------------------------------
#endif


Getting Object Properties

An cluster object's properties determine its identity and behavior in the cluster. Applications typically retrieve an object's properties to discover how the object is currently configured.

The Server Cluster API provides many ways to get the properties of an object. The standard order of preference for cluster-aware applications recommends using control codes if possible. Therefore, the procedures described below use control codes exclusively. If you are writing a resource DLL, you should use the cluster database access functions and the cluster utility functions to work with properties.

The following generalized procedure describes how to use control codes to retrieve the properties for any object. Substitute the name of the object (node, network, netinterface, group, resource, or restype ) for <Object>.

To retrieve <Object> properties:

  1. Allocate an output buffer to receive the property list.
  2. Call the control code function for the object, Cluster<Object>Control, specifying one of the following control codes as the dwControlCode parameter:
    Properties to Retrieve | Control Code to Use
    Common read/write properties | CLUSCTL_<OBJECT>_GET_COMMON_PROPERTIES
    Common read-only properties | CLUSCTL_<OBJECT>_GET_RO_COMMON_PROPERTIES
    Private read/write properties | CLUSCTL_<OBJECT>_GET_PRIVATE_PROPERTIES
    Private read-only properties | CLUSCTL_<OBJECT>_GET_RO_PRIVATE_PROPERTIES

    For more information on using control codes see Getting Information with Control Codes.

  3. If Cluster<Object>Control returns ERROR_MORE_DATA, reallocate the output buffer according to the size returned by the lpcbBytesReturned parameter.
  4. If Cluster<Object>Control returns ERROR_SUCCESS, the output buffer contains a property list for the object. Parse the property list to retrieve individual property names and values - see Parsing Property Lists.

To obtain a list of the read/write common or private properties of an object, use the CLUSCTL_<OBJECT>_ENUM_COMMON_PROPERTIES and CLUSCTL_<OBJECT>_ENUM_PRIVATE_PROPERTIES control codes.

Example Code

The following example retrieves the read/write common properties of a resource and returns the value of a specified property. This example calls other example functions presented elsewhere in this documentation. To locate these example functions, see the Index of Examples.

//////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETRWCDWORDPROPERTY_CPP
#define _CLUSDOCEX_RESGETRWCDWORDPROPERTY_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_ResGetRWCDwordProperty
//
//  Retrieves the value of a specified read-write common resource
//  property of type DWORD.
//
//  Arguments:
//
//      IN  LPWSTR  lpszResName    Name of the resource.
//
//      IN  LPWSTR  lpszPropName   Name of the read-write common
//                                 DWORD property to get.
//
//      OUT LPDWORD lpdwPropValue  Returns the property value.
//
//  Return Value:
//      Win32 error
//
//--------------------------------------------------------------------
DWORD
ClusDocEx_ResGetRWCDwordProperty(
    IN LPWSTR lpszResName,
    IN LPWSTR lpszPropName,
    OUT LPDWORD lpdwPropValue
)
{
    HCLUSTER hCluster = NULL;
    HRESOURCE hResource = NULL;
    LPVOID lpPropList = NULL;
    DWORD dwResult = ERROR_SUCCESS;
    DWORD cbPropListSize = 0;

//  For the ClusDocEx_OpenLocalClusterWithName function,
//  see "Using Object Handles".

    hCluster = ClusDocEx_OpenLocalClusterWithName();

    if( hCluster == NULL )
    {
        goto endf;
    }

    hResource = OpenClusterResource( hCluster, lpszResName );

    if( hResource == NULL )
    {
        goto endf;
    }

//  For the ClusDocEx_ResGetControlCodeOutput function,
//  see "Getting Information with "Control Codes".

    lpPropList = ClusDocEx_ResGetControlCodeOutput(
                     hResource,
                     NULL,
                     CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES,
                     &cbPropListSize );

    if( dwResult != ERROR_SUCCESS )
    {
        goto endf;
    }

//  ResUtilFindDwordProperty is one of the cluster utility functions.

    dwResult = ResUtilFindDwordProperty(
                   lpPropList,
                   cbPropListSize,
                   lpszPropName,
                   lpdwPropValue );

endf:

    if( dwResult != ERROR_SUCCESS )
    {
        ClusDocEx_DebugPrint( L"ClusDocEx_ResGetRWCDwordProperty", dwResult );
    }

//  Free the buffer allocated by ClusDocEx_ResGetControlCodeOutput.

    LocalFree( lpPropList );

    if( hResource ) CloseClusterResource( hResource );

    if( hCluster ) CloseCluster( hCluster );

    return dwResult;
}
//  end ClusDocEx_ResGetRWCDwordProperty
//--------------------------------------------------------------------
#endif


Getting Object Information

Each cluster object is associated with several sets of information that describe the object's identity, configuration, and relationships to other objects. These include the cluster object's common and private properties, its name and Cluster-aware applications. Refer to the following sections

Getting Cluster Information

Getting Group Information

Getting Network Information

Getting Network Interface Information

Getting Node Information

Getting Resource Information

Getting Resource Type Information


Getting Cluster Information

Cluster information is data that pertains to the state or configuration of the cluster as a whole.

Information to get. | API
Name of the cluster | GetClusterInformation
Properties of the cluster | CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES, CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES, CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES, CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES
Property names | CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES, CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES
Quorum resource information | GetClusterQuorumResource
Version of the cluster | GetClusterInformation

For additional cluster-related API elements, see Cluster Management Functions and Cluster Control Codes .


Getting Group Information

The following table lists group-related information and objects and the recommended API elements for obtaining them. If the specified API element does not have an example, look in the Index of Examples for a similar API element.

Information or object to get | API element to use
Cluster that contains the group | GetClusterFromGroup
GUID identifying the group | CLUSCTL_GROUP_GET_ID
Name of the group | CLUSCTL_GROUP_GET_NAME
Properties of the group | CLUSCTL_GROUP_GET_COMMON_PROPERTIES, CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES, CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES, CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES,
Property names | CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES, CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES
Preferred owner nodes | ClusterGroupOpenEnum, ClusterGroupEnum, ClusterGroupCloseEnum
Resources in the group | ClusterGroupOpenEnum, ClusterGroupEnum, ClusterGroupCloseEnum
State of the group | GetClusterGroupState

For additional group-related API elements, see Group Management Functions and Group Control Codes.


Getting Network Information

The following table lists network-related information and objects and the recommended API elements for obtaining them. If the specified API element does not have an example, look in the Index of Examples for a similar API element.

Information or object to get | API element to use
Cluster that contains the network | GetClusterFromNetwork
GUID identifying the network | CLUSCTL_NETWORK_GET_ID
Name of the network | CLUSCTL_NETWORK_GET_NAME
Network interfaces on the network | ClusterNetworkOpenEnum, ClusterNetworkEnum, ClusterNetworkCloseEnum
Properties of the network | CLUSCTL_NETWORK_GET_COMMON_PROPERTIES, CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES, CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES, CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES,
Property names | CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES, CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES
State of the network | GetClusterNetworkState

For additional network-related API elements, see Network Management Functions and Network Control Codes.


Getting Network Interface Information

The following table lists network interface–related information and objects and the recommended API elements for obtaining them. If the specified API element does not have an example, look in the Index of Examples for a similar API element.

Information or Object to Get | API element to Use
Cluster that contains the network interface | GetClusterFromNetInterface
GUID identifying the network interface | CLUSCTL_NETINTERFACE_GET_ID
Name of the network interface | CLUSCTL_NETINTERFACE_GET_NAME
Network to which the network interface is attached | CLUSCTL_NETINTERFACE_GET_NETWORK
Node to which the network interface is attached | CLUSCTL_NETINTERFACE_GET_NODE
Properties of the network interface | CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES, CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES, CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES, CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES,
Property names | CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES, CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES
State of the network interface | GetClusterNetInterfaceState

For additional network interface-related APIs elements, see Network Interface Management Functions and Network Interface Control Codes.


Getting Node Information

The following table lists node-related information and objects and the recommended API elements for obtaining them. If the specified API element does not have an example, look in the Index of Examples for a similar API element.

Information or object to get | API element to use
Cluster that contains the node | GetClusterFromNode
GUID identifying the node | CLUSCTL_NODE_GET_ID
Name of the node | CLUSCTL_NODE_GET_NAME
Network interfaces in the node | ClusterNodeOpenEnum, ClusterNodeEnum, ClusterNodeCloseEnum
Properties of the node | CLUSCTL_NODE_GET_COMMON_PROPERTIES, CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES, CLUSCTL_NODE_GET_PRIVATE_PROPERTIES, CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES,
Property names | CLUSCTL_NODE_ENUM_COMMON_PROPERTIES, CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES
State of the Cluster service on the node | GetNodeClusterState
State of the node | GetClusterNodeState
Version of the Cluster service on the node | GetClusterInformation

For additional node-related APIs, see Node Management Functions and Node Control Codes.


Getting Resource Information

The following table lists resource-related information and the API elements that obtain the information. If the specified API element does not have an example, look in the Index of Examples for a similar API element.

Information to get | API
Characteristics of the resource | CLUSCTL_RESOURCE_GET_CHARACTERISTICS
Checkpoints defined for the resource | CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS, CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS
Cluster that contains the resource. | GetClusterFromResource
Dependencies | ClusterResourceEnum, ResUtilGetResourceDependency, ResUtilGetResourceDependencyByClass, ResUtilGetResourceDependencyByName, ResUtilGetResourceNameDependency
Dependents | ClusterResourceEnum
Disk information | CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO
Equality | ResUtilResourcesEqual
Flags | CLUSCTL_RESOURCE_GET_FLAGS
Group that contains the resource | GetClusterResourceState
GUID | CLUSCTL_RESOURCE_GET_ID
Name | CLUSCTL_RESOURCE_GET_NAME
Network name dependency | CLUSCTL_RESOURCE_GET_NETWORK_NAME
Node that currently owns the resource | GetClusterResourceState
Possible owner nodes | ClusterResourceEnum
Properties | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES, CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES, CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES, CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES
Property names | CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES, CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES
Required dependencies | CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES
Resource class | CLUSCTL_RESOURCE_GET_CLASS_INFO
Resource type | CLUSCTL_RESOURCE_GET_RESOURCE_TYPE
State | GetClusterResourceState

For additional resource-related API elements, see Resource Management Functions and Resource Control Codes.


Getting Resource Type Information

The following table lists resource type–related information and objects and the recommended API elements for obtaining them. If the specified API element does not have an example, look in the Index of Examples for a similar element.

Information to get | API element to use
Available disks | CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS
Characteristics of the resource type | CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS
Checkpoints defined for the resource type | CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS, CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS
Name | CLUSCTL_RESOURCE_GET_NAME
Possible owner nodes | ClusterResourceTypeEnum
Properties | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES, CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES, CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES, CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES
Property names | CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES, CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES
Required dependencies | CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES

For additional resource type–related API elements, see Resource Type Management Functions and Resource Type Control Codes.


Changing The Cluster Configuration

Changing the cluster configuration includes changing properties, changing states, moving cluster objects, and creating and deleting cluster objects.

Task | Description
Backing Up and Restoring the Cluster Configuration | How to make a backup of the cluster database
Setting Properties | How to set the properties of an object.
Changing Object Names | How to change the name of an object.
Changing Object States | How to initiating changes in the object's state.
Creating Groups | How to create a group, add and configure the individual resources in the group, and adjust the group's properties.
Creating Resources | How to create resources.


Backing Up and Restoring the Cluster Configuration

Before changing the cluster configuration, you can create a backup of the cluster database using the Cluster API function BackupClusterDatabase. This creates a snapshot of the cluster configuration which can later be restored with the RestoreClusterDatabase function.

The following example is a command-line tool that performs basic backup and restore operations:

//////////////////////////////////////////////////////////////////////
/*

CLUBAR.CPP

Cluster database backup and restore example demonstrating the
BackupClusterDatabase and RestoreClusterDatabase functions.

To use this example, compile with the ClusDocEx.h header file, then run it using the following command-line syntax:
    To back up:    clubar b[ackup] {cluster name} {backup path}
    To restore**:  clubar r[estore] {backup path} {[no]force} [{drive letter}]

** USE WITH CAUTION. This operation will replace the existing cluster
   database with the specified backup.

*/
//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

//--------------------------------------------------------------------
//  ShowHelp
//  Displays command-line syntax.
//--------------------------------------------------------------------
void ShowHelp()
{
    wprintf( L"\n\nCLUBAR\n" );
    wprintf( L"===========\n" );
    wprintf( L"Demonstration of the BackupClusterDatabase and RestoreClusterDatabase routines.\n\n" );
    wprintf( L"Command-line syntax:\n\n" );
    wprintf( L"     argv[0]  argv[1]    argv[2]         argv[3]          arg[4] \n" );
    wprintf( L"     clubar   b[ackup]   {cluster name}  {backup path}                    \n" );
    wprintf( L"     clubar   r[estore]  {backup path}   {[no]force}  [{drive letter}]\n\n" );
    wprintf( L"     [] denotes optional syntax\n" );
    wprintf( L"     {} denotes user-supplied value\n\n" );
    wprintf( L"Examples:\n" );
    wprintf( L"     clubar b MY_CLUSTER_NAME d:\\backups\\19990415  \n" );
    wprintf( L"     clubar r d:\\backups\\19990415 force k:         \n" );
    wprintf( L"     clubar restore a:\\ noforce         \n" );
}
//  end ShowHelp
//--------------------------------------------------------------------

int main( int argc, char *argv[] )
{
    HCLUSTER hCluster = NULL;

    WCHAR szClusterName[ClusDocEx_DEFAULT_CB];
    WCHAR szPath[ClusDocEx_DEFAULT_CB];
    WCHAR szOperation[ClusDocEx_DEFAULT_CB];

    WCHAR szDriveLetter[ClusDocEx_DEFAULT_CB];
    BOOL  bForce = FALSE;

    DWORD dwResult = ERROR_SUCCESS;

    if( argc < 4 )
        goto error_end;

    if( toupper( *argv[1] ) == 'R' )
    {

    //  RESTORE

    //  Argument 2 should be path.

        if( ( dwResult = ConvertArg( argv[2], szPath, ClusDocEx_DEFAULT_CB ) ) != ERROR_SUCCESS )
            goto error_end;

    //  Argument 3 is the force option.

        if( strcmpi( argv[3], "force" ) == 0 )
            bForce = TRUE;

        if( argc > 4 )
        {
            if( ( dwResult = ConvertArg( argv[4], szDriveLetter, ClusDocEx_DEFAULT_CB ) ) != ERROR_SUCCESS )
                goto error_end;

        //  Use only the first two characters.
        //  Optionally add syntax check here to make sure
        //  first character is alphabetic and second character is a colon.
            szDriveLetter[2] = L'\0';
        }

        // Validate path.
        if( !ResUtilIsPathValid( szPath ) )
        {
            wprintf( L"The specified target path is invalid." );
            goto error_end;
        }

        wprintf( L"\n\n**** WARNING!!! ****\n\nThe existing cluster database will be replaced by the backup stored in %s. If you are sure you want to proceed, enter 'y'. Enter any other key to cancel.\nProceed (y/n):  ", szPath );
        if( towupper( getwc() ) != L'Y' )
            goto error_end;

    //  Restore

        if( argc < 4 )
            dwResult = RestoreClusterDatabase( szPath, bForce, NULL );
        else
            dwResult = RestoreClusterDatabase( szPath, bForce, szDriveLetter );

        switch( dwResult )
        {
        case ERROR_CLUSTER_NODE_UP:
            wprintf( L"\n\nERROR: ACTIVE CLUSTER NODES\n" );
            wprintf( L"Other cluster nodes are currently active. " );
            wprintf( L"Only the node used perform the restore can be running the Cluster service.\n" );
            wprintf( L"\nOptions:\n" );
            wprintf( L"(1) Manually shut down the Cluster service on all the other nodes.\n" );
            wprintf( L"(2) Run the program again using the FORCE command-line argument. \n" );
            wprintf( L"The restore routine will attempt to shut down the Cluster service on all other nodes.\n" );
            break;

        case ERROR_QUORUM_DISK_NOT_FOUND:
            wprintf( L"\n\nERROR: QUORUM DISK NOT FOUND\n" );
            wprintf( L"The restore routine cannot find a quorum disk with the same partition layout as the quorum disk described in the backup. " );
            wprintf( L"The existing quorum disk must have a layout (number of partitions and offsets to each partition) identical to the layout stored in the backup.\n" );
            wprintf( L"\nOptions.\n" );
            wprintf( L"(1) Manually reconfigure the quorum disk to match the layout described in the backup.\n" );
            wprintf( L"(2) Run the program again using the FORCE command-line argument. The restore routine will attempt to reconfigure the quorum disk to match the disk described in the backup.\n" );
            break;
        case ERROR_SUCCESS:
            wprintf( L"\n\nSUCCESS\n" );
            wprintf( L"The restore routine succeeded.  Start the Cluster service on the other cluster nodes to complete the restore operation.  As nodes join the cluster, they will update their cluster databases to match the restored configuration." );
            break;
        default:
            ClusDocEx_DebugPrint( L"RestoreClusterDatabase failed", dwResult );
            break;
        }
    }   //  end RESTORE

    else if( toupper( *argv[1] ) == 'B' )
    {
    //  BACKUP

    //  Argument 2 should be cluster name.

        if( ( dwResult = ConvertArg( argv[2], szClusterName, ClusDocEx_DEFAULT_CB ) ) != ERROR_SUCCESS )
            goto error_end;

    //  Argument 3 should be path.

        if( ( dwResult = ConvertArg( argv[3], szPath, ClusDocEx_DEFAULT_CB ) ) != ERROR_SUCCESS )
            goto error_end;

    //  Validate path.

        if( !ResUtilIsPathValid( szPath ) )
        {
            ClusDocEx_DebugPrint( L"The specified target path is invalid.", 0 );
            goto error_end;
        }

    //  Get cluster handle.

        hCluster = OpenCluster( szClusterName );
        if( hCluster == NULL )
        {
            ClusDocEx_DebugPrint( L"Unable to open a handle to the specified cluster", GetLastError() );
            goto error_end;
        }

    //  Perform backup.

        dwResult = BackupClusterDatabase( hCluster, szPath );

        if( dwResult != ERROR_SUCCESS )
        {
            ClusDocEx_DebugPrint( L"BackupClusterDatabase call failed", GetLastError() );
            goto error_end;
        }

        wprintf( L"\nDone. The cluster database has been backed up to %s. The backup consists of the following files:\n    chk????.tmp\n    quolog.log\n    *.cpt\n    *.cpr\n\n", szPath );

    }       //  end BACKUP

    else
    {
    //  Bad syntax

        ShowHelp();
        goto error_end;
    }

error_end:

    if( hCluster != NULL )
        CloseCluster( hCluster );

    if( dwResult )
        return 1;
    else
        return 0;

}


Setting Properties

Setting properties is the process of writing new property values to the cluster database. Applications and resource DLLs set properties to change the cluster environment according to their needs.

The Server Cluster API provides many ways to set the properties of a cluster object. The standard order of preference for cluster-aware applications recommends using control codes if possible. Therefore, the procedures described below use control codes exclusively. If you are writing a resource DLL, you should use the cluster database access functions and the cluster utility functions to work with properties.

The following generalized procedure describes how to set the properties for any object. Substitute the name of the object (that is, node, network, network interface, group, resource, or resource type ) for <Object>.

To set <Object> properties

  1. Create a property list for the object. (See Creating Property Lists.)
  2. Validate the property list to ensure that the formatting is correct and the values are appropriate. Call the control code function for the object, Cluster<Object>Control, specifying one of the following control codes as the dwControlCode parameter:
    Properties to set | Control code to use
    Common properties | CLUSCTL_<OBJECT>_VALIDATE_COMMON_PROPERTIES
    Private properties | CLUSCTL_<OBJECT>_VALIDATE_PRIVATE_PROPERTIES

  3. If validation succeeds, set the properties by calling Cluster<Object>Control using one of the following control codes as the dwControlCode parameter:
    Properties to set | Control code to use
    Common properties | CLUSCTL_<OBJECT>_SET_COMMON_PROPERTIES
    Private properties | CLUSCTL_<OBJECT>_SET_PRIVATE_PROPERTIES

  4. If Cluster<Object>Control returns ERROR_SUCCESS, the properties have been written to the cluster database.
  5. If Cluster<Object>Control returns ERROR_RESOURCE_PROPERTIES_STORED, the properties have been written to the cluster database, but some or all of the new settings do not take effect until the next time the resource is brought online.

Example Code

The following example function sets group properties. It obtains a property list by calling the ClusDocEx_GrpCreatePropList example function from Creating Property Lists.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_GRPRESETPROPERTYDEFAULTS_CPP
#define _CLUSDOCEX_GRPRESETPROPERTYDEFAULTS_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_GrpResetPropertyDefaults
//
//  Sets all read/write common group properties to their default
//  values.
//
//  Arguments:
//       hGroup     Handle to group whose properties are to be set.
//
//  Return Value:
//       Error code
//
//--------------------------------------------------------------------
DWORD
ClusDocEx_GrpResetPropertyDefaults(
    IN HGROUP hGroup
)
{
    DWORD dwResult = ERROR_SUCCESS;
    DWORD cbSize = 0;

//  Obtain a property list with all values set to defaults.
//  For the ClusDocEx_GrpCreatePropertyList function see
//  "Creating Property Lists".

    LPVOID lpPropList = ClusDocEx_GrpCreatePropertyList(
                            &cbSize,
                            ClusterGroupPreventFailback,
                            L" ",
                            -1,
                            -1,
                            6,
                            10,
                            FALSE );

//  Validate the property list.

    dwResult =
        ClusterGroupControl(
            hGroup,
            NULL,
            CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES,
            lpPropList,
            cbSize,
            NULL,
            0,
            NULL );

    if ( dwResult == ERROR_SUCCESS )
    {

    //  Set the properties.

        dwResult =
            ClusterGroupControl(
                hGroup,
                NULL,
                CLUSCTL_GROUP_SET_COMMON_PROPERTIES,
                lpPropList,
                cbSize,
                NULL,
                0,
                NULL );
    }

    if ( dwResult != ERROR_SUCCESS )
    {
        ClusDocEx_DebugPrint( L"ClusDocEx_GrpResetPropertyDefaults",
                                dwResult );
    }

//  Free the buffer returned by ClusDocEx_GrpCreatePropList

    LocalFree( lpPropList );

    return dwResult;

}
//  end ClusDocEx_GrpResetPropertyDefaults
//--------------------------------------------------------------------
#endif


Changing Object Names

Cluster-aware applications typically allow administrators to control changes to existing cluster object names. As an analogy, most applications allow users to control path and file name changes. In both cases, the user is in the best position to assess the impact of the name change on other applications and to choose a name that is consistent with other names.

The following API elements can be used to safely change object names.

Name to change | Function to use
cluster name | SetClusterName
group name | SetClusterGroupName
network name | SetClusterNetworkName
resource name | SetClusterResourceName

Notes

  • Resource DLLs are notified of cluster and resource name changes with the CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED and CLUSCTL_RESOURCE_SET_NAME control codes.
  • Object names are stored as read-only common properties. Thus it is possible to change object names using the cluster database access functions, but it is dangerous to do so. The cluster database access functions may not generate all of the required notifications, resulting in unusable objects or an unusable cluster.


Changing Object States

Initiating state changes allows you to test failover performance and to perform rolling upgrades. The following functions initiate state changes in various objects.

Object | Function
bring a group online | OnlineClusterGroup
bring a resource online | OnlineClusterResource
fail a resource | FailClusterResource
pause a node | PauseClusterNode
resume a node | ResumeClusterNode
take a group offline | OfflineClusterGroup
take a resource offline | OfflineClusterResource


Creating Groups

Creating a group involves adding and configuring the individual resources in the group and adjusting the group's properties so that the group is ready to be brought online.

Administrators can create groups manually through cluster management applications such as Cluster Administrator, but cluster-aware applications can ease the burden on administrators by automating group creation as much as possible.

The following sections describe the tasks associated with creating groups:

To create a group

  1. Obtain a cluster handle. (See Using Object Handles.)
  2. Obtain a unique group name. To list the names of groups currently defined in the cluster, see Enumerating Objects.
  3. Create the group by calling CreateClusterGroup.
  4. Add resources to the group. To move existing resources into the group, call ChangeClusterResourceGroup. To create new resources in the group, see Creating Resources.
  5. Set properties, checkpoints, possible owners, and dependencies for the resources. (See Configuring Resources.)
  6. Adjust the group's failover policies. (For the properties that affect failover, see Failover and Failback. For information on changing properties, see Setting Properties.)
  7. If necessary, modify the group's preferred owner nodes list by calling SetClusterGroupNodeList.

Example Code

See Creating Virtual Servers.


Creating Virtual Servers

To implement high availability for a server application or any other resource normally accessed by a computer name, you should configure the resource to run in the context of a virtual server. This task can be left to administrators, or you can write code to create a virtual server specific to the needs of your application.

To create a virtual server

  1. Create a group (see Creating Groups) that contains an IP Address resource, a Network Name resource, your resource, and any other resources that must be in the same group.
  2. Call AddClusterResourceDependency to establish the following dependencies:
    1. Add the IP Address resource as a dependency of the Network Name resource.
    2. Add either the IP Address resource or the Network Name resource as a dependency of your resource.
    3. Add other dependencies based on the requirements of your resource.
  3. Configure all required and other properties. See Configuring Resources.

Example Code

The following code demonstrates the creation of a "bare bones" virtual server—a group with an IP Address resource and a Network Name resource. This example calls other example functions presented elsewhere in this documentation. To locate these example functions, see the Index of Examples.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef CLUSDOCEX_GRPCREATEVIRTUALSERVER_CPP
#define CLUSDOCEX_GRPCREATEVIRTUALSERVER_CPP
//--------------------------------------------------------------------
//  ClusDocEx_GrpCreateVirtualServer
//
//  Configures a group as a virtual server.
//
//  Arguments:
//    IN HCLUSTER hCluster         Cluster handle.
//    IN LPWSTR   lpszGroupName    Name of the new virtual server.
//    IN LPWSTR   lpszIPResName    Name of the IP Address resource
//    IN LPWSTR   lpszNetResName   Name of the Network Name resource
//    IN LPWSTR   lpszAddress      IP address of the virtual server.
//    IN LPWSTR   lpszNetworkName  Network name of the virtual server.
//    IN LPWSTR   lpszSubnetMask   Subnet mask for the virtual server.
//
//  Return Value:
//     Group handle (if successful) or NULL (if unsuccessful)
//--------------------------------------------------------------------
HGROUP
ClusDocEx_GrpCreateVirtualServer
(
    IN HCLUSTER hCluster,
    IN LPWSTR   lpszGroupName,
    IN LPWSTR   lpszIPResName,
    IN LPWSTR   lpszNetResName,
    IN LPWSTR   lpszIPAddress,
    IN LPWSTR   lpszNetworkName,
    IN LPWSTR   lpszSubnetMask
)
{
    HGROUP    hGroup       = NULL;
    HRESOURCE hIPAddress   = NULL;
    HRESOURCE hNetworkName = NULL;
    DWORD     dwResult     = ERROR_SUCCESS;

//  Create the group.

    hGroup = CreateClusterGroup( hCluster, lpszGroupName );

    if( hGroup == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

    if( hGroup != NULL )
    {

    //  Create the IP Address resource.

        hIPAddress = ClusDocEx_ResCreateIPAddress(
                         hGroup,
                         lpszIPResName,
                         lpszIPAddress,
                         lpszNetworkName,
                         lpszSubnetMask );

        if( hIPAddress == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

    //  Create the Network Name resource.

        hNetworkName = ClusDocEx_ResCreateNetworkName(
                           hGroup,
                           hIPAddress,
                           lpszNetResName,
                           lpszNetworkName );

        if( hNetworkName == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }
    }

endf:

    if( dwResult != ERROR_SUCCESS )
    {
        if( hNetworkName != NULL )
        {
            DeleteClusterResource( hNetworkName );

        //  Must always close handles after deletion.

            CloseClusterResource( hNetworkName );
            hNetworkName = NULL;
        }

        if( hIPAddress != NULL )
        {
            DeleteClusterResource( hIPAddress);
            CloseClusterResource( hIPAddress);
            hIPAddress = NULL;
        }

        if( hGroup != NULL )
        {
            DeleteClusterGroup( hGroup );
            CloseClusterGroup( hGroup );
            hGroup = NULL;
        }
    }

//  Close resource handles.

    if( hNetworkName != NULL )
    {
        CloseClusterResource( hNetworkName );
    }
    if( hIPAddress != NULL )
    {
        CloseClusterResource( hIPAddress);
    }

    SetLastError( dwResult );

    return hGroup;
}
//  end ClusDocEx_GrpCreateVirtualServer
//--------------------------------------------------------------------
#endif


Creating Resources

The following procedure describes the general process of creating a resource:

To Create a Resource

  1. Obtain a handle to a new or existing group in which to create the resource. See CreateClusterGroup and OpenClusterGroup.
  2. Determine the name of the new resource. The name must be unique in the cluster.
  3. Determine whether the new resource should have its own Resource Monitor. This should be done only for volatile or unstable resources or for debugging.
  4. Call CreateClusterResource to create a new resource in the specified group.

The resource may need to be configured before it can be brought online. For configuration procedures see Configuring Resources and Copying Resource Configurations.

Example Code

The following sections contain examples of resource configuration:

Creating Physical Disk Resources

Creating IP Address Resources

Creating Network Name Resources


Configuring Resources

Configuring a resource is the process of adjusting its properties, establishing its required dependencies, and making other changes so that it is ready to be brought online.

  1. Assign values to all of the resource's required private properties. (See Setting Properties.)
  2. Assign values to any of the resource's other private or common properties as necessary. For example, set any special failure or failover policies for the resource.
  3. If necessary, create registry and crypto checkpoints for the resource by calling ClusterResourceControl with the CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT and CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control codes.
  4. Get the required dependencies of the resource by using the CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code.
  5. If the resource has required dependencies, you must create and configure those resources as well. The dependencies may have required dependencies of their own. Create all the required resources and call AddClusterResourceDependency to establish each required dependency relationship.
  6. Create additional dependencies as desired.
  7. If the resource is a server application being published to clients through a virtual server, use the service utility functions to initialize an appropriate service environment.

Example Code

The following sections contain examples of resource configuration:

Creating Physical Disk Resources

Creating IP Address Resources

Creating Network Name Resources


Copying Resource Configurations

Depending on the resource type of a resource, it may be possible to use an existing resource configuration as a template for a new resource configuration.

To Copy a Resource Configuration

  1. Get a handle to the original resource by calling OpenClusterResource.
  2. Get the resource type of the original resource. Call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code.
  3. Create a resource of that type. (See Creating Resources.) Note that the name of the new resource cannot be the same as the original if it is created in the same cluster.
  4. Duplicate the original resource's read/write properties:
    1. Retrieve the original resource's read/write common properties into a property list by using CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES.
    2. Use the property list obtained in the previous step to set the new resource's read/write common properties with CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES.
    3. Retrieve the original's read/write private properties into a property list using CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES.
    4. Use the property list obtained in the previous step to set the new resource's read/write private properties with CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES.
  5. If the original resource has registry and crypto checkpoints, .
    1. Retrieve the original's crypto checkpoints using CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS.
    2. Use the data obtained in the previous step and the Crypto API to create crypto keys for the new resource.
    3. Checkpoint the crypto keys created in the previous step using CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT.
    4. Retrieve the original's registry checkpoints using CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS.
    5. Use the Win32 registry functions to create retistry keys for the new resource.
    6. Checkpoint the registry keys created in the previous step using CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT.
  6. Enumerate the dependencies of the original resource. See Enumerating Objects.
  7. Repeat steps 2 through 6 for each dependency until the entire dependency tree has been copied.


Creating Physical Disk Resources

Applications may need to obtain access to a disk on a shared bus in order to secure data storage or satisfy dependency requirements for a resource To make a disk usable as a cluster resource, create a Physical Disk resource for it.

New Physical Disk resources should be created only for available cluster-capable disks. That is, disks that are accessible by all cluster nodes and that are not associated with an existing Physical Disk resource.

Note that the Physical Disk resources cannot be created for partitions or logical drives, only entire physical drives. There is currently no way to independently fail over drive partitions on the same disk. A Physical Disk resource can be created for a partitioned drive, but the resource is associated with the entire disk, partitions and all.

To Create a Physical Disk Resource

  1. Determine search criteria for selecting a disk. Refer to CLUSPROP_PARTITION_INFO for the kinds of data that can be searched for.
  2. Create or select a group in which to create the new resource (see CreateClusterGroup and OpenClusterGroup.
  3. Get a list of available disks. Call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code.
  4. Parse the resulting value list for a disk matching the criteria determined in step 1.(See Parsing a Value List.) If a disk is found:
    • Get the signature or drive letter of the disk.
    • Get the drive letters of all partitions of the disk.
  5. Create a resource by calling CreateClusterResource, specifying "Physical Disk" as the resource type.
  6. Set the new resource's Drive or Signature private property to the drive or signature obtained in step 3. You must set one or the other of these properties, but not both. Do not change either property after this assignment is made.

Once created, the Physical Disk resource can be brought online, used as a dependency, or otherwise controlled with the Resource Management Functions. It will appear as a cluster resource in Cluster Administrator and in Cluster.exe.

Example Code

The following example creates a Physical Disk resource for a disk identified by drive letter.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESCREATEDISK_CPP
#define _CLUSDOCEX_RESCREATEDISK_CPP
//--------------------------------------------------------------------
//
// ClusDocEx_ResCreateDisk
//
// Creates an instance of a Physical Disk resource and returns a
// handle to it.
//
// Note:
//   * Do not change the Signature private property of the resource
//     after it has been created.
//   * To remove the disk from the cluster's control, call
//     DeleteClusterResource on the returned handle.
//
// Arguments:
//   IN HCLUSTER hCluster       Cluster handle.
//   IN HGROUP   hGroup         Handle to the group that will contain
//                              the new resource.
//   IN LPWSTR   lpszDriveLtr   Drive letter of the disk
//                              for which to create a resource.
//
// Return Value:
//     Resource handle or NULL for non-success. Call GetLastError()
//     for more info.
//--------------------------------------------------------------------
HRESOURCE
ClusDocEx_ResCreateDisk
(
    IN HCLUSTER hCluster,
    IN HGROUP   hGroup,
    IN LPWSTR   lpszDriveLtr
)
{
    HRESOURCE hResource = NULL;

    DWORD dwResult        = ERROR_SUCCESS;
    DWORD dwTestSignature = 0;
    DWORD dwSignature     = 0;
    DWORD dwSyntax        = 0;
    DWORD cbLength        = 0;
    DWORD cbRequired      = 0;
    DWORD cbPosition      = 0;

    LPWSTR lpszResName = ( LPWSTR )LocalAlloc( LPTR, MAX_PATH );
    LPWSTR lpszDrives  = L"Drives ";
    LPVOID pValueList  = NULL;

    BOOL bDiskFound = FALSE;

    CLUSPROP_BUFFER_HELPER cbh;

//  Begin property list used to set the Signature private property.
//  This example uses a struct to define the property list.

        WCHAR szPropName[] = L"Signature";

        typedef struct _DiskSignatureControl
        {
            DWORD dwPropCount;
            CLUSPROP_PROPERTY_NAME_DECLARE(
                PropName,
                sizeof( szPropName ) / sizeof( WCHAR ) );
            CLUSPROP_DISK_SIGNATURE Signature;
            CLUSPROP_SYNTAX Endmark;
        }
        DiskSignatureControl;

        DiskSignatureControl DSC;

    //  Property Count
        DSC.dwPropCount = 1;

    //  Property Name
        DSC.PropName.Syntax.dw  = CLUSPROP_SYNTAX_NAME;
        DSC.PropName.cbLength   = sizeof( szPropName );
        lstrcpyW( DSC.PropName.sz, szPropName );

    //  Property Value
        DSC.Signature.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
        DSC.Signature.cbLength  = sizeof( DWORD );
        DSC.Signature.dw        = 0; // this will be changed later

    //  Endmark
        DSC.Endmark.dw = CLUSPROP_SYNTAX_ENDMARK;

        DWORD cbSize = sizeof( DiskSignatureControl );

//  End property list creation

    if( lpszResName == NULL ||
        pValueList == NULL ||
        lpszDrives == NULL )
    {
        goto endf;
    }

//  Get all available disks
//  ClusDocEx_RtpGetControlCodeOutput is defined in
//  "Getting Information with Control Codes."

    pValueList = ClusDocEx_RtpGetControlCodeOutput(
                       L"Physical Disk",
                       hCluster,
                       NULL,
                       CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS,
                       &cbRequired );

    if( pValueList == NULL )
    {
        goto endf;
    }

//  Parse the value list.
//  The architecture of this list is described under
//  "Value Lists for Storage Class Resources".
//
//  Two objectives:
//  1) Find the signature of the disk containing the specified drive letter.
//  2) Obtain a list of all drive letters associated with that disk.
//
//  To accomplish both objectives, lpszDrives collects all the drive letters
//  for a given disk.  If the specified drive letter is found, the loop
//  continues until a new signature signals the start of a new disk. Otherwise
//  lpszDrives is reinitialized for each new disk.

    cbh.pb = ( PBYTE )pValueList;

    while( 1 )
    {
        dwSyntax = cbh.pSyntax->dw;

    //  The disk signature structure marks the beginning of a new disk.

        if( dwSyntax == CLUSPROP_SYNTAX_DISK_SIGNATURE )
        {

        //  Save the signature in case it contains the drive letter we're looking for.

            dwTestSignature = cbh.pDwordValue->dw;

            if( bDiskFound )
            {
            //  The previous disk contained the specified drive letter
            //  lpszDrives lists all drive letters for that disk
                break;
            }
            else if( lpszDrives != NULL )
            {
            //  Clear the drive letter list for the new disk
                LocalFree( lpszDrives );
                lpszDrives = ( LPWSTR )LocalAlloc( LPTR, MAX_PATH );
                if( lpszDrives == NULL ) goto endf;
                lstrcpyW( lpszDrives, L"Drives: " );
            }

        }

    //  Will get one partition info structure per disk partition

        else if( dwSyntax == CLUSPROP_SYNTAX_PARTITION_INFO )
        {

        //  Add the drive letter of this partition to lpszDrives

            lstrcat( lpszDrives, cbh.pPartitionInfoValue->szDeviceName );
            lstrcat( lpszDrives, L" " );

            if( lstrcmpi( cbh.pPartitionInfoValue->szDeviceName, lpszDriveLtr ) == 0 )
            {
            //  The current disk contains the partition with the drive letter
            //  we're looking for.  Flag the find and save the signature.
                bDiskFound = TRUE;
                dwSignature = dwTestSignature;
            }
        }

        else if( dwSyntax == CLUSPROP_SYNTAX_ENDMARK )
            break;

        cbLength = cbh.pValue->cbLength;

    //  If next advance is within value list buffer,
    //  advance the structure pointer.

        cbPosition += ClusDocEx_ListEntrySize( cbLength );

        if( ( cbPosition + sizeof( DWORD ) ) >= cbRequired ) break;

        cbh.pb += ClusDocEx_ListEntrySize( cbLength );

    }

    if( bDiskFound == FALSE ) goto endf;

//  Create the resource.  The resource name is "Disk Drives @: @: @: ... "
//  where @ is the drive letter of a disk partition.

    lstrcpyW( lpszResName, L"Disk " );

    lstrcat( lpszResName, lpszDrives );

    hResource = CreateClusterResource( hGroup,
                                       lpszResName,
                                       L"Physical Disk",
                                       0 );

    if( hResource == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Update the property list

    DSC.Signature.dw = dwSignature;

//  Store the signature in the resource's Signature private property

    dwResult = ClusterResourceControl( hResource,
                                       NULL,
                                       CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES,
                                       ( void* ) &DSC,
                                       cbSize,
                                       NULL,
                                       0,
                                       NULL );

    if( dwResult != ERROR_SUCCESS )
    {
        DeleteClusterResource( hResource );
        CloseClusterResource( hResource );
        hResource = NULL;
    }

endf:

    LocalFree( pValueList );
    LocalFree( lpszResName );
    LocalFree( lpszDrives );

    SetLastError( dwResult );

    return hResource;
}
//  end ClusDocEx_ResCreateDisk
//--------------------------------------------------------------------
#endif


Creating IP Address Resources

The following code demonstrates the creation of an IP Address resource.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESCREATEIPADDRESS_CPP
#define _CLUSDOCEX_RESCREATEIPADDRESS_CPP

//--------------------------------------------------------------------
//  ClusDocEx_ResCreateIPAddress
//
//  Creates an IP Address resource and sets its
//  required private properties.
//
//  Arguments:
//   IN HGROUP hGroup          Handle to the group in which to create the resource
//   IN LPWSTR lpszResName     Name of the new IP Address resource
//   IN LPWSTR lpszAddress     IP address supported by the resource
//   IN LPWSTR lpszNetwork     Network supported by the resource
//   IN LPWSTR lpszSubnetMask  Subnet mask supported by the resource
//
//  Return Value:
//     Resource handle (if successful) or NULL (if unsuccessful)
//--------------------------------------------------------------------
HRESOURCE
ClusDocEx_ResCreateIPAddress
(
    IN HGROUP hGroup,
    IN LPWSTR lpszResName,
    IN LPWSTR lpszAddress,
    IN LPWSTR lpszNetwork,
    IN LPWSTR lpszSubnetMask
)
{
    HRESOURCE hIPRes;

    DWORD dwResult    = ERROR_SUCCESS;
    DWORD dwPropCount = 3;

    DWORD cb;
    DWORD cbPosition = 0;
    DWORD cbAddressEntrySize = 0;
    DWORD cbNetworkEntrySize = 0;
    DWORD cbMaskEntrySize = 0;
    DWORD cbPropListSize = 0;

    LPVOID lpAddressEntry;
    LPVOID lpNetworkEntry;
    LPVOID lpMaskEntry;
    LPVOID lpPropList;

    CLUSPROP_BUFFER_HELPER cbh_read, cbh_write;

//  Create the resource.

    hIPRes = CreateClusterResource( hGroup,
                                    lpszResName,
                                    L"IP Address",
                                    0 );

    if( hIPRes == NULL )
    {
        goto endf;
    }

//  Create a property list to set the required private properties.
//  This example uses ClusDocEx_CreatePropertyListEntry, which
//  is listed under "Creating Property Lists."

    lpAddressEntry = ClusDocEx_CreatePropertyListEntry(
                      L"Address",
                      CLUSPROP_SYNTAX_LIST_VALUE_SZ,
                      (lstrlenW( lpszAddress ) + 1 ) * sizeof( WCHAR ),
                      (LPVOID) lpszAddress,
                      &cbAddressEntrySize );

    lpNetworkEntry = ClusDocEx_CreatePropertyListEntry(
                      L"Network",
                      CLUSPROP_SYNTAX_LIST_VALUE_SZ,
                      (lstrlenW( lpszNetwork ) + 1 ) * sizeof( WCHAR ),
                      (LPVOID) lpszNetwork,
                      &cbNetworkEntrySize );

    lpMaskEntry = ClusDocEx_CreatePropertyListEntry(
                      L"SubnetMask",
                      CLUSPROP_SYNTAX_LIST_VALUE_SZ,
                      (lstrlenW( lpszSubnetMask ) + 1 ) * sizeof( WCHAR ),
                      (LPVOID) lpszSubnetMask ,
                      &cbMaskEntrySize );

    cbPropListSize = sizeof( DWORD ) +
                     cbAddressEntrySize +
                     cbNetworkEntrySize +
                     cbMaskEntrySize ;

    lpPropList = LocalAlloc( LPTR, cbPropListSize );

//  Use cbh to write the property count (3) and the entries
//  to the property list buffer.

    cbh_write.pb = (PBYTE) lpPropList;

    *cbh_write.pdw = dwPropCount;

    cbPosition = sizeof( DWORD );

    cbh_read.pb = (PBYTE) lpAddressEntry;

    for( cb = 0 ; cb < cbAddressEntrySize ; cb++, cbPosition++ )
        cbh_write.pb[cbPosition] = cbh_read.pb[cb];

    cbh_read.pb = (PBYTE) lpNetworkEntry;

    for( cb = 0 ; cb < cbNetworkEntrySize ; cb++, cbPosition++ )
        cbh_write.pb[cbPosition] = cbh_read.pb[cb];

    cbh_read.pb = (PBYTE) lpMaskEntry;

    for( cb = 0 ; cb < cbMaskEntrySize ; cb++, cbPosition++ )
        cbh_write.pb[cbPosition] = cbh_read.pb[cb];

    dwResult = ClusterResourceControl(
                   hIPRes,
                   NULL,
                   CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES,
                   lpPropList,
                   cbPropListSize,
                   NULL,
                   0,
                   NULL );

endf:

    if( dwResult != ERROR_SUCCESS )
    {
        if( hIPRes )
        {
            DeleteClusterResource( hIPRes );
            CloseClusterResource( hIPRes );
            hIPRes = NULL;
        }
    }

    LocalFree( lpPropList );
    LocalFree( lpAddressEntry );
    LocalFree( lpNetworkEntry );
    LocalFree( lpMaskEntry );

    SetLastError( dwResult );

    return hIPRes;
}
//  end ClusDocEx_ResCreateIPAddress
//--------------------------------------------------------------------
#endif


Creating Network Name Resources

The following code demonstrates the creation of a Network Name resource.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef CLUSDOCEX_RESCREATENETWORKNAME_CPP
#define CLUSDOCEX_RESCREATENETWORKNAME_CPP
//--------------------------------------------------------------------
//
//  ClusDocEx_ResCreateNetworkName
//
//  Creates a Network Name resource,
//  sets its required private properties,
//  and establishes a dependency on an IP Address resource.
//
//  Arguments:
//     IN HGROUP    hGroup         Group handle.
//     IN HRESOURCE hIPDependency  Handle to the IP Address dependency.
//     IN LPWSTR    lpszResName    Name of the new Network Name
//                                 resource (the resource name).
//     IN LPWSTR    lpszNetName    Specifies the name of the network
//                                 for which the Network Name resource
//                                 is being created. This value will
//                                 be used to set the Name private
//                                 property.
//
//  Return Value:
//     Resource handle (if successful) or NULL (if unsuccessful)
//
//--------------------------------------------------------------------
HRESOURCE
ClusDocEx_ResCreateNetworkName
(
    IN HGROUP    hGroup,
    IN HRESOURCE hIPDependency,
    IN LPWSTR    lpszResName,
    IN LPWSTR    lpszNetName
)
{
    HRESOURCE hNetNameRes = NULL;
    LPVOID lpPropList = NULL;
    LPVOID lpNameEntry = NULL;

    DWORD cb;
    DWORD cbPosition = 0;
    DWORD cbNameEntrySize = 0;
    DWORD cbPropListSize = 0;
    DWORD dwResult = ERROR_SUCCESS;

    CLUSPROP_BUFFER_HELPER cbh_read, cbh_write;

    hNetNameRes = CreateClusterResource(
                      hGroup,
                      lpszResName,
                      L"Network Name",
                      0 );

    if( hNetNameRes == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//  Create a property list to set the Name private property.
//  This example uses ClusDocEx_CreatePropertyListEntry, which
//  is listed under "Creating Property Lists."

    lpNameEntry = ClusDocEx_CreatePropertyListEntry(
                      L"Name",
                      CLUSPROP_SYNTAX_LIST_VALUE_SZ,
                      (lstrlenW( lpszNetName ) + 1 ) * sizeof( WCHAR ),
                      (LPVOID) lpszNetName,
                      &cbNameEntrySize );

//  This is a single-value property list, thus the size is just
//  the size of the entry plus the size of the property count.

    cbPropListSize = sizeof( DWORD ) + cbNameEntrySize;

    lpPropList = LocalAlloc( LPTR, cbPropListSize );

//  Use cbh to write the property count (1) and the single entry
//  to the property list buffer.

    cbh_write.pb = (PBYTE) lpPropList;

    cbh_read.pb = (PBYTE) lpNameEntry;

    *cbh_write.pdw = 1;

    cbPosition = sizeof( DWORD );

    for( cb = 0 ; cb < cbNameEntrySize ; cb++, cbPosition++ )
        cbh_write.pb[cbPosition] = cbh_read.pb[cb];

    dwResult = ClusterResourceControl(
                   hNetNameRes,
                   NULL,
                   CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES,
                   lpPropList,
                   cbPropListSize,
                   NULL,
                   0,
                   NULL );

    if( dwResult != ERROR_SUCCESS )
    {
        goto endf;
    }

//  Establish the IP Address dependency.

    dwResult = AddClusterResourceDependency(
                   hNetNameRes,
                   hIPDependency );

endf:

    if( dwResult != ERROR_SUCCESS )
    {
        if( hNetNameRes != NULL )
        {
            DeleteClusterResource( hNetNameRes );
            CloseClusterResource( hNetNameRes );
            hNetNameRes = NULL;
        }
    }

    if( lpNameEntry != NULL ) LocalFree( lpNameEntry );
    if( lpPropList != NULL ) LocalFree( lpPropList );

    SetLastError( dwResult );

    return hNetNameRes;
}
//  end ClusDocEx_ResCreateNetworkName
//--------------------------------------------------------------------
#endif


Creating Resource Types

One of the most common cluster programming tasks is to create a resource type to support an application, service, or device as a highly available cluster resource.

To create a resource type

  1. Run the Cluster Resource Wizard to generate a basic resource DLL and a Cluster Administrator extension DLL for the resource type. See Using the Cluster Resource Wizard. If your development environment does not support wizards, refer to the Samples directory of the Platform SDK. The ClipSrv and SmbSmp samples were generated by the Cluster Resource Wizard.
  2. Implement the resource DLL to support instances of the resource type as highly available resources. See Implementing Resource DLLs.
  3. Optional: Customize the extension DLL code generated by the Cluster Resource Wizard. Typically the Wizard generates a complete extension DLL which requires no customization.
  4. Debug the resource type. See Debugging Resource Types.
  5. Deploy the resource type. See Deploying Resource Types.


Using the Cluster Resource Wizard

The Platform SDK includes the Cluster Resource Wizard (CResTyp.awx) to guide you through the creation of a new resource type. The Cluster Resource Wizard lets you specify important features of your resource type and then generates a resource DLL and a Cluster Administrator extension DLL.

Although you do not have to use the Cluster Resource Wizard as the basis for your code, there are good reasons for doing so:

  • The Cluster Resource Wizard produces a complete implementation of the extension DLL and an almost complete implementation of the resource DLL. All you have to do is modify the areas of the resource DLL marked as TODO.
  • The code is an excellent reference for learning how to create resource DLLs. By running the Wizard several times, using a different set of options each time, you can identify the code that supports a particular option.
  • The Wizard creates the source code for the CClusPropList class, an MFC class used to dynamically build property lists. You can use this class in your resource DLL or in cluster-aware applications, or as the basis for your own property list class.

The following procedure describes how to use the Cluster Resource Wizard to create a resource type:

To use the Cluster Resource Wizard to create a resource type

  1. Make sure you are using the latest version of the wizard. The Cluster Resource Wizard is implemented in two files, CRESTYP.AWX and CRESTYP.HLP, which are installed by Visual C++. The Platform SDK may provide newer versions of these files, but you must locate them and replace the older versions installed by Visual C++. Because installation paths may vary, it is best to search your system for all instances of CRESTYP.* and make sure the latest files are being used by Visual C++.
  2. Start a new project in Visual C++.
    1. Select Cluster Resource Wizard as the project type.
    2. Provide a path and a project name.
    3. Click Create.
  3. The Cluster Resource Wizard - Step 1 of 2 dialog box appears. The following table lists the controls on the dialog and how to use them to configure your resource type:
Caption | Description of control
Resource type name | Required. Provides the name of the resource type
No service control required | Select this option if resources of this type do not control or depend on any services.
Resource depends on a service | Select this option if resources of this type depend on one or more services.
Resource controls a service | Select this option if resources of this type control one or more services.
Service name | If the resource type controls or depends on a service, provide the name of the service.
Use Network Name for computer name | Check this box if you plan to use a virtual server to publish your resources to clients.
Resource requires dependencies on other resources | Check this box if resources of this type require other types of resources as dependencies.
Only one instance of resource permitted in the cluster | Check this box if only one instance of this type of resource can exist in the same cluster.

  3. When you have adjusted the settings for your resource type, click Next.
  4. The Cluster Resource Wizard - Step 2 of 2 dialog box appears. Use it to define private properties for your resource type. For each private property you want to define:
    1. Click Add
    2. In the Add Property dialog box, specify the name and type of the property and whether it is required. If you specify a numeric type such as DWORD, you can enter a default, minimum, and maximum value.
    3. Click OK. The property and all related information is inserted into the list. The order in which the properties appear dictates their order on the Properties page in your Cluster Administrator extension DLL.
  5. When you have added all of the parameters for the resource type, click Finish.
  6. A screen entitled New Project Information appears providing data about the projects you are about to create. If you are satisfied with the data in the New Project Information screen, click OK.
  7. The Cluster Resource Wizard will create two projects: a <Name> project for the resource DLL and a <Name>Ex project for the extension DLL (<Name> is the name of your resource type). Each project directory has a Readme.txt file that describes the contents.
  8. You must add code to the resource DLL (<Name>.cpp):
    1. Add lines for your resource-specific libraries after the following line:
            #pragma comment(lib, "clusapi.lib")
    2. Add any header files that provide definitions and declarations specific to your resource type after these lines:
            #include <clusapi.h>
        #include <resapi.h>
        #include <stdio.h>
    3. Add code to the areas marked as TODO. It is vital that you customize these areas. Your DLL simply won't function without minimal implementations, and ultimately this will be the code that provides high availability support for your resources.

For more information on how to fill in the TODO code, see Implementing Resource DLLs.


Implementing Resource DLLs

For each resource type supported by your resource DLL, you must provide implementations for all of the entry point functions except for Arbitrate and Release. You need to implement Arbitrate and Release only if your resource type is quorum-capable.

Implementing a resource DLL involves tasks that are qualified as follows:

  • Required: Your implementation must perform these tasks or the resource type or resource DLL will not function.
  • Recommended: Although not strictly required, these tasks are recommended for convenience, optimization, or improved performance.
  • Optional: Identifies tasks you can perform as a matter of preference.

To implement a resource DLL

  1. Recommended: Run the Cluster Resource Type Wizard to generate the source code for each resource type. The Cluster Resource Type Wizard flags required tasks that you must implement with TODO. As a general rule of thumb, the code generated by the Cluster Resource Wizard represents the recommended implementation model. See Using the Cluster Resource Wizard.
  2. Required: Implement DllMain and Startup to initialize the DLL and each supported resource type. See Performing Initialization.
  3. Required: Implement Open and Close to manage the creation and deletion of resource instances. See Managing Instances.
  4. Required: Implement Online, Offline, and Terminate to start and stop resource instances on demand. See Managing State Transitions.
  5. Required: Implement IsAlive and LooksAlive to detect and respond to possible resource failures. See Detecting Resource Failure.
  6. Required: Implement ResourceControl and ResourceTypeControl to handle control codes. See Supporting Control Codes.


Supporting Multiple Resource Types

A single resource DLL can support multiple resource types. For example, many of the resource types defined by the Cluster service are all supported by a single resource DLL. One reason to do this is simply for convenience—it is easier to debug and deploy a single resource DLL than to manage several different DLLs.

Combining multiple resource types into a single resource DLL also allows you to more easily manage shared data or interactions between resources of different types. This is useful for applications that can be divided into functionally discrete modules, with each module supported as a separate resource type.

For example, a single database application might be supported by a Database Engine resource type, a Transaction Engine resource type, and a Connection Manager resource type. Each type has its own set of dependencies, properties, failure detectors, and failover policies. However, the DLL that implements these types enforces the proper relationships between the modules and provides ways to share data. Thus the DLL might allow any number of Database Engine resources in the cluster, but only allow one Transaction Engine resource and one Connection Manager resource per cluster.

To create a resource DLL that supports multiple types

  1. Use the Cluster Resource Wizard to generate the source code for each type separately. See Using the Cluster Resource Wizard.
  2. Keep the source code for each resource type in separate modules. Create a new project for the resource DLL that compiles all of the modules into a single DLL.
  3. Create an initialization module. Implement DllMain and Startup in this module, and handle all global DLL-level data here.
  4. Rename the DllMain and Startup entry points in each resource type module to <Name>DllMain and <Name>Startup, where <Name> is the name of the resource type.
  5. Implement the entry point functions for each resource type. See Implementing Resource DLLs.
  6. Debug and deploy the combined DLL. See Deploying Resource Types and Debugging Resource Types.


Recommended Practices for Resource DLLs

Avoid operations that cause deadlocks in resource DLLs.
See Function Calls to Avoid in Resource DLLs.
For optimal performance of the cluster and maximum availability for your resources, all entry points should return a value in 300 milliseconds or less.
If your implementation needs more time, create a worker thread to handle the operation asynchronously and return a value immediately. A resource DLL is non-reentrant for all entry points except for the Terminate entry point function. Thus, while your DLL is processing an entry point function, your other entry points (except Terminate) are blocked.
The Cluster API will not be unavailable to your DLL until the Cluster service has started.
Your DLL receives notification that the Cluster service has started through the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 control code.


Function Calls to Avoid in Resource DLLs

Function calls involving the following API elements can cause deadlock when made from resource DLLs. The following table lists these functions along with a usage code. A subsequent table describes the usage codes.

API element | Usage code
AddClusterResourceDependency | Do not use.
AddClusterResourceNode | Worker thread only.
CanResourceBeDependent | Worker thread only.
ChangeClusterResourceGroup | Do not use.
CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_GET_CHARACTERISTICS | Worker thread only.
CLUSCTL_GROUP_GET_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_GET_FLAGS | Worker thread only.
CLUSCTL_GROUP_GET_NAME | Worker thread only.
CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_QUERY_DELETE | Worker thread only.
CLUSCTL_GROUP_SET_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_UNKNOWN | Worker thread only.
CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_ADD_DEPENDENCY | Worker thread only.
CLUSCTL_RESOURCE_ADD_OWNER | Worker thread only.
CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED | Worker thread only.
CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED | Worker thread only.
CLUSCTL_RESOURCE_DELETE | Worker thread only.
CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_EVICT_NODE | Worker thread only.
CLUSCTL_RESOURCE_GET_CHARACTERISTICS | Worker thread only.
CLUSCTL_RESOURCE_GET_CLASS_INFO | Worker thread only.
CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_GET_FLAGS | Worker thread only.
CLUSCTL_RESOURCE_GET_NETWORK_NAME | Worker thread only.
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES | Worker thread only.
CLUSCTL_RESOURCE_GET_RESOURCE_TYPE | Worker thread only.
CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_INSTALL_NODE | Worker thread only.
CLUSCTL_RESOURCE_REMOVE_DEPENDENCY | Worker thread only.
CLUSCTL_RESOURCE_REMOVE_OWNER | Worker thread only.
CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_SET_NAME | Worker thread only.
CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO | Worker thread only.
CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID | Worker thread only.
CLUSCTL_RESOURCE_UNKNOWN | Worker thread only.
CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES | Worker thread only.
CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES | Worker thread only.
ClusterGroupEnum | Worker thread only.
ClusterGroupOpenEnum | Worker thread only
ClusterRegCreateKey | Some entry points okay.
ClusterRegDeleteKey | Some entry points okay.
ClusterRegDeleteValue | Some entry points okay.
ClusterRegSetKeySecurity | Some entry points okay.
ClusterRegSetValue | Some entry points okay.
ClusterResourceEnum | Worker thread only.
ClusterResourceOpenEnum | Worker thread only.
CreateClusterGroup | Do not use.
CreateClusterResource | Do not use.
DeleteClusterGroup | Do not use.
DeleteClusterResource | Do not use.
FailClusterResource | Do not use.
GetClusterGroupState | Worker thread only.
GetClusterResourceNetworkName | Worker thread only.
GetClusterResourceState | Worker thread only.
MoveClusterGroup | Do not use.
OfflineClusterGroup | Do not use.
OfflineClusterResource | Do not use.
OnlineClusterGroup | Do not use.
OnlineClusterResource | Do not use.
RemoveClusterResourceDependency | Do not use.
RemoveClusterResourceNode | Worker thread only.
ResUtilFindDependentDiskResourceDriveLetter | Worker thread only.
ResUtilGetResourceDependentIPAddressProps | Worker thread only.
ResUtilGetEnvironmentWithNetName | Worker thread only.
ResUtilGetResourceDependency | Worker thread only.
ResUtilGetResourceDependencyByClass | Worker thread only.
ResUtilGetResourceDependencyByName | Worker thread only.
ResUtilGetResourceNameDependency | Worker thread only.
ResUtilSetBinaryValue | Some entry points okay.
ResUtilSetDwordValue | Some entry points okay.
ResUtilSetExpandSzValue | Some entry points okay.
ResUtilSetMultiSzValue | Some entry points okay.
ResUtilSetPrivatePropertyList | Some entry points okay.
ResUtilSetPropertyParameterBlock | Some entry points okay.
ResUtilSetPropertyParameterBlockEx | Some entry points okay.
ResUtilSetPropertyTable | Some entry points okay.
ResUtilSetPropertyTableEx | Some entry points okay.
ResUtilSetResourceServiceEnvironment | Worker thread only.
ResUtilSetSzValue | Some entry points okay.
ResUtilSetUnknownProperties | Some entry points okay.
SetClusterGroupName | Do not use.
SetClusterGroupNodeList | Worker thread only.
SetClusterName | Do not use.
SetClusterQuorumResource | Do not use.
SetClusterResourceName | Do not use.

The following table describes the usage codes presented in the previous table:

Usage code | Usage notes
Some entry points okay. | Do not call these functions from the following resource DLL entry point functions: Close, Offline, Online, Open, Terminate. These functions can be safely called from any other resource DLL entry point function or from a worker thread.
Worker thread only. | These functions should be called only from a worker thread (see ClusWorkerCreate, ClusWorkerCheckTerminate, and ClusWorkerTerminate).
Do not use. | Do not call any of these fuctions from a resource DLL. Functions in this category modify dependency relationships, add or remove resources from groups, create or delete groups or resources, cause resource or group state changes, or change the node lists of groups or resources.


Performing Initialization

The following sections describe how to initialize the resource DLL and each resource type supported by the DLL:

Defining Structures and Constants

Implementing DllMain

Implementing Startup


Defining Structures and Constants

Some entry point functions require your resource DLL to describe and manage data in very specific ways. The following list describes the structures and constants that your DLL can or should define:

  1. Required. Define a function table for each resource type supported by your resource DLL. See CLRES_V1_FUNCTIONS.
  2. Required. Define global storage for the address of the LogEvent callback function. You need only one LogEvent callback per resource DLL.
  3. Required. Define global storage for the address of the SetResourceStatus callback function. You only need one SetResourceStatus callback per resource DLL.
  4. Required. Define a structure, class, or other object to manage instance data. The recommended way to do this is to define a resource structure. For more information see Implementing Instance Management.
  5. Required: Define the following objects if your resource type defines any private properties:
    • Constants storing each property name.
    • Constants describing minimum, maximum, and default values.
    • A parameter block.
    • A property table.

Any additional objects are optional. For example:

  • Semaphores, mutexes, and critical sections necessary to synchronize instance counts and other shared data.
  • Structures or classes that simplify the process of working with value lists and property lists.
  • Required dependency lists.
  • Constants, structures, classes, or other objects that specify the ideal configuration for the resource type. This would include property settings for the dependencies and dependents of the resource type and of the group in which they reside.

Example

The following example defines data in a resource DLL that supports two resource types, MyTypeAlpha and MyTypeBeta. For additional examples see Resource DLL Examples.

//////////////////////////////////////////////////////////////////////

//  Callback function pointers for the DLL.

    PSET_RESOURCE_STATUS_ROUTINE g_pfnSetResourceStatus = NULL;

    PLOG_EVENT_ROUTINE           g_pfnLogEvent          = NULL;

//////////////////////////////////////////////////////////////////////

//  Resource type name constants

    #define TYPE_NAME_ALPHA L"MyTypeAlpha"

    #define TYPE_NAME_BETA  L"MyTypeBeta"

//////////////////////////////////////////////////////////////////////

//  Function tables.

    CLRES_V1_FUNCTION_TABLE(
        g_FTable_Alpha,
        CLRES_VERSION_V1_00,
        MyTypeAlpha,
        NULL,
        NULL,
        MyTypeAlphaResourceControl,
        MyTypeAlphaResourceTypeControl
    );

    CLRES_V1_FUNCTION_TABLE(
        g_FTable_Beta,
        CLRES_VERSION_V1_00,
        MyTypeBeta,
        NULL,
        NULL,
        MyTypeBetaResourceControl,
        MyTypeBetaResourceTypeControl
    );

//////////////////////////////////////////////////////////////////////

//  Resource structures.

    typedef struct _INSTANCE_ALPHA
    {
        RESID             resid;
        PARAM_BLOCK_ALPHA propsActive;
        PARAM_BLOCK_ALPHA props;
        HCLUSTER          hCluster;
        HRESOURCE         hResource;
        SC_HANDLE         hService;
        DWORD             dwServicePid;
        HKEY              hkeyParameters;
        RESOURCE_HANDLE   hResourceHandle;
        LPWSTR            pszResourceName;
        CLUS_WORKER       cwWorkerThread;
        CLUSTER_RESOURCE_STATE state;
    }
    INSTANCE_ALPHA, * PINSTANCE_ALPHA;

    typedef struct _INSTANCE_BETA
    {
        RESID                   resid;
        HCLUSTER                hCluster;
        HRESOURCE               hResource;
        HKEY                    hkeyParameters;
        RESOURCE_HANDLE         hResourceHandle;
        LPWSTR                  pszResourceName;
        CLUS_WORKER             cwWorkerThread;
        CLUSTER_RESOURCE_STATE  state;
    }
    INSTANCE_BETA, * PINSTANCE_BETA;

//////////////////////////////////////////////////////////////////////

//  Private property data.
//  Only MyTypeAlpha defines private properties.

    #define PROP_NAME__MAXUSERS L"MaxUsers"
    #define PROP_MIN__MAXUSERS        (-1)
    #define PROP_MAX__MAXUSERS        (256)
    #define PROP_DEFAULT__MAXUSERS    (8)

    typedef struct _PARAM_BLOCK_ALPHA
    {
        LONG nMaxUsers;
    }
    PARAM_BLOCK_ALPHA, * PPARAM_BLOCK_ALPHA;

    RESUTIL_PROPERTY_ITEM PROP_TABLE_ALPHA[] =
    {
        {
            PROP_NAME__MAXUSERS,
            NULL,
            CLUSPROP_FORMAT_LONG,
            (DWORD) PROP_DEFAULT__MAXUSERS,
            (DWORD) PROP_MIN__MAXUSERS,
            (DWORD) PROP_MAX__MAXUSERS,
            RESUTIL_PROPITEM_REQUIRED,
            FIELD_OFFSET( PARAM_BLOCK_ALPHA,
                          nMaxUsers )
        },

        { 0 }
    };

//////////////////////////////////////////////////////////////////////

//  Define a semaphore to limit MyTypeAlpha instances to
//  one per cluster.  SIS = "single instance semaphore"

    #define SIS_ALPHA L"SISAlpha"
    static HANDLE g_hSIS = NULL;
    static PINSTANCE_ALPHA g_pInstance_Alpha = NULL;

//////////////////////////////////////////////////////////////////////


Implementing DllMain

To work with an instance of a resource type, a Resource Monitor needs to have the resource DLL that supports the type loaded into its process. If the DLL is already loaded, the Resource Monitor calls the appropriate entry point function. If not, the Resource Monitor calls LoadLibrary and triggers the DllMain entry point.

To implement DllMain

  1. Recommended: Call the Win32 function DisableThreadLibraryCalls in response to DLL_PROCESS_ATTACH. Refer to the description of the function for the performance benefits.
  2. Optional: Initialize semaphores, mutexes, critical sections, classes, COM objects, or any other objects used by the DLL.
  3. Recommended. For optimal performance, take no more than 300 milliseconds to return a value.

Resource DLLs that support multiple resource types typically define a single DllMain entry point for the entire DLL, and define a <Name>DllMain entry point for each <Name> resource type supported by the DLL. This is illustrated in the following example.

Example

The following example demonstrates a DllMain implementation in a resource DLL that supports two resource types, MyTypeAlpha and MyTypeBeta. For additional examples see Resource DLL Examples.

//////////////////////////////////////////////////////////////////////

BOOLEAN
WINAPI
DllMain(
    IN HINSTANCE hDllHandle,
    IN DWORD     nReason,
    IN LPVOID    Reserved
)
{
    BOOLEAN bSuccess = TRUE;

//  Perform global initialization.

    switch ( nReason )
    {
        case DLL_PROCESS_ATTACH:

        //  For optimization.

            DisableThreadLibraryCalls( hDllHandle );

            break;

        case DLL_PROCESS_DETACH:

            break;
    }

//  Perform type-specific initialization.

    if(    MyTypeAlphaDllMain( hDllHandle, nReason, Reserved )
        && MyTypeBetaDllMain(  hDllHandle, nReason, Reserved ) )
    {
         bSuccess = TRUE;
    }
    else
    {
         bSuccess = FALSE;
    }

    return bSuccess;

}
//  end DllMain

//////////////////////////////////////////////////////////////////////

BOOLEAN
WINAPI
MyTypeAlphaDllMain(
    IN HINSTANCE hDllHandle,
    IN DWORD nReason,
    IN LPVOID Reserved
)
{
    switch ( nReason )
    {
        case DLL_PROCESS_ATTACH:

            g_hSIS = CreateSemaphoreW(
                         NULL,
                         0,
                         1,
                         SIS_ALPHA );

            if( g_hSIS == NULL ) return FALSE;

        //  Set initial count to 1.

            if( GetLastError() != ERROR_ALREADY_EXISTS )
                ReleaseSemaphore( g_hSIS, 1, NULL );

            break;

        case DLL_PROCESS_DETACH:

            if ( g_hSIS != NULL )
            {
                CloseHandle( g_hSIS );
                g_hSIS = NULL;
            }

            break;

    }

    return TRUE;

}
//  end MyTypeAlphaDllMain

//////////////////////////////////////////////////////////////////////

BOOLEAN WINAPI MyTypeBetaDllMain(
    IN HINSTANCE hDllHandle,
    IN DWORD nReason,
    IN LPVOID Reserved
)
{

//  MyTypeBeta needs no processing at this time.

    switch ( nReason )
    {
        case DLL_PROCESS_ATTACH:

            break;

        case DLL_PROCESS_DETACH:

            break;

    }

    return TRUE;

}
//  end MyTypeBetaDllMain

//////////////////////////////////////////////////////////////////////


Implementing Startup

The first time a Resource Monitor creates an instance of a resource type, it calls the Startup entry point function in the appropriate resource DLL. The purpose of Startup is to allow the resource DLL and the Resource Monitor to exchange two important pieces of information:

  • The Resource Monitor needs the addresses of the entry point functions for the resource type.
  • The resource DLL needs addresses for the LogEvent and SetResourceStatus callback functions.

In addition, Startup indicates the version of the Resource API in use on the local node.

To implement Startup

  1. Recommended: Verify that the local version of the Resource API is compatible with your implementation.
  2. Required. Store the addresses of LogEvent and SetResourceStatus callback functions.
  3. Required. Return a function table for the specified resource type.
  4. Recommended. Take no more than 300 milliseconds to return a value.

Once a Resource Monitor has a function table for a resource type, it does not call Startup to create additional instances. A Resource Monitor will retain the function table for a resource type until all instances of the type assigned to the Resource Monitor have been deleted.

Resource DLLs that support multiple resource types typically define a single Startup entry point function for the entire DLL and take appropriate action based on the name of the resource type passed in by the Resource Monitor. However, you could instead create <Name>Startup functions for each <Name> resource type supported by your DLL, as described in Implementing DllMain.

Example

The following example illustrates a Startup routine in a resource DLL that supports two types, MyTypeAlpha and MyTypeBeta. For additional examples see Resource DLL Examples.

////////////////////////////////////////////////////////////////

DWORD WINAPI Startup(
    IN LPCWSTR                       pszResourceType,
    IN DWORD                         nMinVersionSupported,
    IN DWORD                         nMaxVersionSupported,
    IN PSET_RESOURCE_STATUS_ROUTINE  pfnSetResourceStatus,
    IN PLOG_EVENT_ROUTINE            pfnLogEvent,
    OUT PCLRES_FUNCTION_TABLE       *pFunctionTable
)
{
    DWORD nStatus;

    if (   (nMinVersionSupported > CLRES_VERSION_V1_00)
        || (nMaxVersionSupported < CLRES_VERSION_V1_00) )
    {
        nStatus = ERROR_REVISION_MISMATCH;
    }
    else if( lstrcmpiW( pszResourceType, TYPE_NAME_ALPHA ) == 0 )
    {
        *pFunctionTable              = &g_FTable_Alpha;
        nStatus                      = ERROR_SUCCESS;
    }
    else if( lstrcmpiW( pszResourceType, TYPE_NAME_BETA ) == 0 )
    {
        *pFunctionTable              = &g_FTable_Beta;
        nStatus                      = ERROR_SUCCESS;
    }
    else
    {
        nStatus = ERROR_CLUSTER_RESNAME_NOT_FOUND;
    }

    if( nStatus == ERROR_SUCCESS )
    {
        g_pfnSetResourceStatus = pfnSetResourceStatus;
        g_pfnLogEvent          = pfnLogEvent;
    }

    return nStatus;

}


Managing Instances

The following sections describe how to manage the creation and deletion of resources in your resource DLL:

  • Implementing Open
  • Implementing Close
  • Implementing Instance Management
  • Resource Identifiers
  • Resource Structures
  • Instance Data


Implementing Open

The Cluster service calls the Open entry point function (through a Resource Monitor) to create a new instance of a resource type. Your resource DLL should initialize an actual instance of the physical or logical entity to be supported as the resource and associate it with a set of instance data. Open can also lay groundwork for the Online entry point.

To implement Open

  1. Optional: Enforce limits on the number of concurrent instances allowed. It is recommended that you use a synchronization object such as a semaphore to synchronize instance counts.
  2. Required: Generate and save the required instance data for the new instance. See Implementing Instance Management.
  3. Required: Create or initialize an actual instance of the physical or logical entity to be supported as a resource. Make sure it is in an offline state.
  4. Optional: Perform configuration tasks such as establishing registry and crypto key checkpoints. See Checkpointing.
  5. Recommended: For optimal performance, return a value within 300 milliseconds.

Example

See Resource DLL Examples.


Implementing Close

The purpose of Close is to remove a resource instance from the cluster. The Cluster service prompts the Resource Monitor to invoke the Close entry point function to remove a resource instance from the cluster; for example, in response to DeleteClusterResource.

To implement Close

  1. Required: Make sure the resource is offline. If it is not offline, call Terminate to forcibly take the resource offline.
  2. Required: Deallocate all structures related to the resource instance.
  3. Optional: Decrement instance counters if necessary.
  4. Recommended: For optimal performance, return a value within 300 milliseconds.

Example

See Resource DLL Examples.


Implementing Instance Management

You can create any system for managing instances in your resource DLL as long as you meet the following requirements:

  • Each instance is assigned a unique resource identifier.
  • The resource identifier is associated with the required instance data.
  • When the Cluster service passes a resource identifier to an entry point function, the resource DLL can use the identifier to locate the correct instance and its associated data.

The Cluster Resource Wizard automatically generates code that meets these requirements. In the implementation of Open created by the Cluster Resource Wizard, a new resource structure is allocated for each new instance. The address of this structure becomes the resource identifier. The resource identifier is stored as the first member of the resource structure. This is used for validation as well as for identification. The address of the structure points to the first member of the structure, whose value is also the address of the structure. Thus the resource identifier acts as an index into the "table" of resource structures maintained by the DLL.

Example

See Resource DLL Examples.


Resource Identifiers

Each instance of a resource must be assigned a unique resource identifier, or RESID, which is passed back to the Cluster service from the Open entry point function. The RESID (defined as a PVOID by Resutils.h) allows the Cluster service to refer to specific instances in subsequent calls to the resource DLL. Thus the RESID must behave like an index, allowing your resource DLL to locate the correct instance and its associated data.

For more information, see Implementing Instance Management.


Resource Structures

A resource structure is a user-defined structure for storing instance data. The Cluster Resource Wizard automatically defines a resource structure based on the name of the resource type and the options selected in the Wizard dialogs (see Using the Cluster Resource Wizard). The following code illustrates a resource structure:

typedef struct _MYTYPE_RESOURCE
{
  RESID                  resid;
  MYTYPE_PROPS           propsActive;
  MYTYPE_PROPS           props;
  HCLUSTER               hCluster;
  HRESOURCE              hResource;
  SC_HANDLE              hService;
  DWORD                  dwServicePid;
  HKEY                   hkeyParameters;
  RESOURCE_HANDLE        hResourceHandle;
  LPWSTR                 pszResourceName;
  CLUS_WORKER            cwWorkerThread;
  CLUSTER_RESOURCE_STATE state;
}
MYTYPE_RESOURCE, *PMYTYPE_RESOURCE;
resid
Stores the resource identifier (RESID) of the resource instance. The RESID is the address of the structure that is allocated for a resource instance.
propsActive
A parameter block that stores the most current in-memory values of the instance's private properties. If a resource is online, changes to its private properties are stored here until the resource can be taken offline and brought back online. The Cluster Resource Wizard generates this member only if private properties are defined for the resource type.
props
A parameter block that stores a the most current cluster database values of the instance's private properties. These are the values under which the instance is currently operating. The Cluster Resource Wizard generates this member only if private properties are defined for the resource type.
hCluster
Stores a cluster handle.
hResource
Stores a resource handle.
hService
Handle to the service controlled by the resource. The Cluster Resource Wizard generates this member only if the Resource controls service option is used.
dwServicePid
Stores the service process identifier of the service controlled by the resource. The Cluster Resource Wizard generates this member only if the Resource controls service option is used.
hkeyParameters
Stores the name of the cluster database key under which the resource's private properties are stored.
hResourceHandle
Stores the Resource Monitor's handle to the instance, which is used to identify the instance in the LogEvent and SetResourceStatus callback functions.
pszResourceName
Stores the name of the resource.
cwWorkerThread
A CLUS_WORKER thread used to handle pending operations.
state
Stores the state of the resource.

For more information on instance management, see Implementing Instance Mangagement.


Instance Data

Your resource DLL must maintain a set of data for each instance that identifies and describes the instance and its current configuration, and that associates the instance with handles and other objects. At minimum, your resource DLL must maintain the following data items for each instance:

  1. Resource identifier.
  2. Resource name.
  3. The Resource Monitor's handle to the instance, which is used to identify the instance in the LogEvent and SetResourceStatus callback functions.
  4. The cluster database subkey defined for the resource.
  5. The current state of the resource.

The Cluster Resource Wizard generates a resource structure to meet these requirements. It is recommended that you maintain a similar set of data for each instance.

For more information on instance management, see Implementing Instance Mangagement.


Managing State Transitions

Resource DLLs are responsible for bringing resources online and taking them offline.

  • Implementing Online
  • Implementing Offline
  • Implementing Pending Operations
  • Implementing Terminate


Implementing Online

A resource is not available until it is online. The Cluster service calls your Online entry point to request that a resource instance be brought from an offline (unavailable) state to an online (available) state. Your implementation of Online is thus the first opportunity you have to ensure high availability.

Typically, the tasks required to bring a resource online take a long time to complete (hundreds to thousands of milliseconds). Most Online implementations a create worker thread to perform these tasks asynchronously.

Whether you implement Online synchronously or asynchronously, your online code should perform the following tasks:

To bring a resource online

  1. Recommended: Retrieve the current values of the resource's private properties by calling ResUtilGetPropertiesToParameterBlock.
  2. Required: If the resource is a service
    1. Call ResUtilStopResourceService (if necessary) to stop the service before changing the service options.
    2. Call ResUtilSetResourceServiceEnvironment.
    3. Call ResUtilSetResourceServiceStartParameters to make the service controllable by the cluster.
  3. Required: Bring the resource to an operational state. For applications, this might be as simple as calling CreateProcess.

To implement Online

  1. Recommended: For optimal performance, return a value within 300 milliseconds. If you need more time to perform all of the necessary tasks, have Online start a worker thread and return ERROR_IO_PENDING immediately. See Implementing Pending Operations.
  2. Optional: If you want to implement asynchronous failure detection, return a handle to an object that can be signaled—such as a semaphore—as the EventHandle parameter. For more information see Detecting Resource Failure.

Example

See Resource DLL Examples.


Implementing Offline

The Offline entry point function should perform cleanup tasks and gracefully shut down the resource. Keep in mind that the Cluster service invokes Offline during failover as well as during normal resource shutdown. (For more information, see Failover.) Your implementation of Offline should handle both situations while saving state and configuration information and taking any steps necessary to enable the resource to be brought online on another node if necessary.

To implement Offline

  1. Recommended: For optimal performance, return a value within 300 milliseconds. If you need more time to perform all of the necessary cleanup tasks, have Offline start a worker thread and return ERROR_IO_PENDING immediately. See Implementing Pending Operations.


Implementing Pending Operations

If your Online or Offline entry point functions require more than 300 milliseconds, it is recommended that you use a worker thread to perform the operation asynchronously.

The following steps are all required:

To Implement a Pending Operation

  1. In your Online or Offline entry point function, call ClusWorkerCreate to start a worker thread and return ERROR_IO_PENDING immediately.
  2. Have the thread perform the necessary online or offline tasks.
  3. Periodically call ClusWorkerCheckTerminate to see if the Terminate entry point function has been called.
  4. Use the SetResourceStatus function pointer obtained from the Startup entry point function to report status information to the Resource Monitor.

If the resource does not transition within the time specified by the resource's PendingTimeout property, the Resource Monitor calls the Terminate entry point function.

Example

See Resource DLL Examples.


Implementing Terminate

The Terminate entry point function is used to immediately end a process that does not shut down gracefully when the Offline function is called.

Make your implementation of Terminate finish in less than 300 milliseconds if possible. However, the Cluster service handles the situation properly if this time limit is exceeded.

Example

See Resource DLL Examples.


Detecting Resource Failure

The cluster monitors the environment for node, network, and Cluster service failures. Your resource DLL must implement a failure detection system that detects and responds to potential problems in the resources it supports.

A good failure detection system detects potential problems as they occur, accurately assesses their severity, and responds in a way that maximizes availability.

For information on the various aspects of detecting resource failure, see the following topics:

  • Implementing Asynchronous Failure Detection
  • Implementing LooksAlive
  • Implementing IsAlive


Implementing Asynchronous Failure Detection

When Online is called for a resource instance, you have the option of returning a handle to a synchronization object (an "event handle"). This has the following effects:

  • The Resource Monitor will not call the LooksAlive entry point function for that instance, regardless of the LooksAlivePollInterval setting.
  • You can signal the handle at any time to indicate a possible failure in a resource instance. Signaling the handle causes the Resource Monitor to call IsAlive immediately. The event handle allows you to report failure asynchronously from anywhere in your resource DLL.

To implement asynchronous failure detection

  • Recommended: If you support multiple resource instances, devise a system so that one synchronization object serves several (if not all) resource instances. The routine that signals the handle should identify the instance that has failed for your IsAlive routine.


Implementing LooksAlive

If you do not implement asynchronous failure detection for a resource type, the Resource Monitor calls the LooksAlive entry point function for each instance of that type. The LooksAlivePollInterval property controls the frequency of these calls. If LooksAlive returns false, IsAlive will be called immediately.

To implement LooksAlive

  1. Recommended: Perform one or more very fast, cursory checks of the specified instance with the emphasis on detecting potential problems rather than verifying operational status. IsAlive will determine whether the instance is really operational.
  2. Recommended: Adjust the LooksAlivePollInterval property to an appropriate value.
  3. Recommended. Take no more than 300 milliseconds to return a value.

Example

See Resource DLL Examples.


Implementing IsAlive

Once the resource is online, the Resource Monitor polls the resource periodically to determine its status. The Resource Monitor uses the LooksAlive and IsAlive entry point functions to accomplish this.

The IsAlive entry point function is used for more thorough resource status evaluation and is regularly polled by the Resource Monitor at a rate governed by the IsAlivePollInterval property. Unlike LooksAlive polling, IsAlive polling cannot be turned off.

To implement IsAlive

  1. Required: Perform a complete check of the resource to see if it is functioning properly. The set of procedures you need to use depends on your resource. For example, a database resource should check to see that the database can write to the disk, perform queries and updates to the disk, and so forth.
  2. Required: If the resource has definitely failed, return FALSE. The Resource Monitor immediately sets the status of the resource to ClusterResourceFailed and calls the Terminate entry point function.
  3. Recommended: Take no more than 300 milliseconds to complete; ideally, it should finish in less than 50 milliseconds. However, if your implementation must take longer than 300 milliseconds, perform the following steps:
    1. Have a separate thread dedicated to perform the polling operation.
    2. Return the result of the last poll performed by the separate thread.

When using separate threads to check the health of resources, take steps to ensure synchronization. For example, you might maintain a monitor thread that is independent of the IsAlive thread. The two threads could share a common data block, synchronized through a critical section, that contains the last reported status. If the monitor thread detects a failure, it tries to correct it. If that fails, it updates the status in the block. The next time IsAlive runs, it sees an error status and takes appropriate action.

Example

See Resource DLL Examples.


Supporting Control Codes

The following sections describe how to implement control code support in a resource DLL:

  • Implementing Resource Control
  • Implementing ResourceTypeControl


Implementing ResourceControl

The Cluster service (through a Resource Monitor) invokes the ResourceControl entry point function when:

  • An application calls ClusterResourceControl to initiate a control code operation.
  • The resource DLL needs to be notified of a cluster event such as an upgrade.

In both cases, a control code is passed to the resource DLL as an input parameter. The DLL can implement the control code operation, instruct the Resource Monitor to handle the operation, or both.

Some control codes should be handled by the Resource Monitor; others require or benefit from customized implementation in the DLL. To determine how and why to support a particular control code, refer to the individual control code descriptions in Control Codes.

To request that the Resource Monitor process a control code, return ERROR_INVALID_FUNCTION. You can return this value for a control code even if you include support for the code in ResourceControl, allowing you to augment the default functionality of the Resource Monitor.

As with all entry point functions, follow the Resource DLL best Practices.

Example

See Resource DLL Examples.


Implementing ResourceTypeControl

The Cluster service (through a Resource Monitor) invokes the ResourceTypeControl entry point function when:

  • An application calls ClusterResourceTypeControl to initiate a control code operation.
  • The resource DLL needs to be notified of a cluster event such as an upgrade.

In both cases, a control code is passed to the resource DLL as an input parameter. The DLL can implement the control code operation, instruct the Resource Monitor to handle the operation, or both.

Some control codes should be handled by the Resource Monitor; others require or benefit from customized implementation in the DLL. Support for any of the other control codes is optional. To determine how and why to support a particular control code, see Control Codes.

To request that the Resource Monitor process a control code, return ERROR_INVALID_FUNCTION. You can return this value for a control code even if you include support for the code in ResourceTypeControl, allowing you to augment the default functionality of the Resource Monitor.

Example

See Resource DLL Examples.


Resource DLL Examples

For a working example, refer to the ClipSrv sample included with the Platform SDK. The Cluster Resource Type Wizard is also an excellent source for example code (see Using the Cluster Resource Wizard).


Implementing Extension DLLs

If you are creating a new resource type, the Cluster Resource Type Wizard automatically generates the code necessary to compile a fully functional extension DLL. You do not have to modify the generated code in any way to produce an extension DLL that allows administrators to manage your resource type through Cluster Administrator.

You would only want to change the code produced by the Cluster Resource Type Wizard under the following circumstances:

  • You want to add functionality to the default extension DLL generated for a resource type.
  • You are extending an object other than a resource type.

In both cases, you will be modifying the generated code to add context menus, property sheet pages, and wizard pages to the Cluster Administrator user interface. The following sections describe how to use the Cluster Administrator extension functions to perform these tasks:

  • Adding Context Menu Items
  • Adding Property Sheet Pages
  • Adding Wizard and Wizard97 Pages
  • Using the Information Interfaces


Adding Context Menu Items

When an administrator pulls up a context menu for the object you are extending, Cluster Administrator calls your implementation of the IWEExtendContextMenu::AddContextMenuItems method. Your implementation should:

  1. Create the context menu items to be added to the context menu.
  2. Call the Cluster Administrator information interfaces as needed. See Using the Information Interfaces.
  3. Call IWCContextMenuCallback::AddExtensionMenuItem for each item to be added. This causes the item to appear in the context menu seen by the administrator.

When an administrator selects a context menu item created by your extension, Cluster Administrator calls your implementation of IWEInvokeCommand::InvokeCommand. Your implementation should perform the action you want to associate with the context menu item.


Adding Property Sheet Pages

When an administrator pulls up a property sheet for the object you are extending, Cluster Administrator calls your implementation of IWEExtendPropertySheet::CreatePropertySheetPages. Your implementation should:

  1. Create the property sheet pages to be added to the property sheet.
  2. Call the Cluster Administrator information interfaces as needed. See Using the Information Interfaces.
  3. Call IWCPropertySheetCallback::AddPropertySheetPage for each page to be added.


Adding Wizard and Wizard97 Pages

Cluster Administrator calls your implementation of IWEExtendWizard::CreateWizardPages when an administrator runs the Cluster Resource Wizard for a resource type that you are extending. Cluster Administrator calls your implementations of IWEExtendWizard::CreateWizardPages and IWEExtendWizard97::CreateWizard97Pages when an administrator runs the Cluster Application Wizard for a resource type that you are extending. Your implementations of these two methods should:

  1. Create the wizard pages to be added to the wizard.
  2. Call the Cluster Administrator information interfaces as needed. See Using the Information Interfaces.
  3. For each page to be added:
    • Call IWCWizardCallback::AddWizardPage or IWCWizard97Callback::AddWizard97Page to add the page.
    • Call IWCWizardCallback::EnableNext or IWCWizard97Callback::EnableNext to specify whether another page follows the current page.


Using the Information Interfaces

Your implementations of the Cluster Administrator extension interfaces can use the Cluster Administrator information interfaces to gather information. Note the following restrictions:

  • IGetClusterUIInfo, IGetClusterObjectInfo, and IGetClusterDataInfo can be called by any extension DLL.
  • IGetClusterGroupInfo should be called only by extension DLLs that are extending groups.
  • IGetClusterNetworkInfo should be called only by extension DLLs that are extending networks.
  • IGetClusterNetInterfaceInfo should be called only by extension DLLs that are extending network interfaces.
  • IGetClusterNodeInfo should be called only by extension DLLs that are extending nodes.
  • IGetClusterResourceInfo should be called only by extension DLLs that are extending resources.


Deploying Resource Types

Once you have created a resource DLL and a Cluster Administrator extension DLL, the next step is to deploy the new resource types. Typically, you deploy manually when designing and testing the resource type and create a cluster-aware setup application to deploy the finished product. No matter how you accomplish the deployment, the following list describes the end result:

  • Each cluster node has a local installation of the application, service, or device to be managed as a highly available resource. This includes the application binaries, COM and ActiveX components, registry and crypto keys, and other files necessary to run the application.
  • Each cluster node has a local copy of your resource DLL under the same path and filename.
  • Each cluster node and each remote non-clustered system that will be used to administer the cluster must have local copies of your extention DLL under the same path and filename.
  • Your resource DLL and extension DLL are registered with the cluster.
  • Your extension DLL is registered with COM on every system containing a copy of the DLL.

The following procedure describes how to deploy resource types manually. For information on deploying resource types through setup applications, see Creating Cluster-Aware Setup Applications.

To deploy resource types manually

  1. Install the application files on each node. For more information on this process see Installing Files.
  2. Copy your resource DLL to each cluster node, using the same path and filename on each node.
  3. Copy the extension DLL to each cluster node and to each remote system that will be using Cluster Administrator to administer the cluster. Use the same path and filename on each system.
  4. From any cluster node, enter the following Cluster.exe command once for each resource type supported by your resource DLL:
            cluster restype MyResourceTypeName /create /dll: \path\dllname

    Specify the path to the location of your DLL (see step 2.). If no path is specified, it defaults to \%systemroot%\cluster.

  5. From any cluster node, call regsvr32 using the following syntax:
            regsvr32 drive:\path\MyExtensionDLLName


Debugging Resource Types

The following sections describe the process of debugging resource types:

  • Debugging Resource DLLs
  • Debugging Extension DLLs


Debugging Resource DLLs

Because the Cluster service runs as a Microsoft Windows NT/Windows 2000 service and the Resource Monitor runs as a separate process, debugging resource DLLs can be more complicated than debugging regular Windows NT/Windows 2000-based DLLs or applications.

The following procedure describes how to debug a resource DLL:

To debug a resource DLL

  1. Configure your environment for debugging. For information, see Preparing a Development Environment.
  2. Stop the Cluster service using the following command:
    net stop clussvc
  3. Restart the Cluster service locally by typing the following command from the cluster directory:
    start clussvc -debug

    When the Cluster service starts, it creates a Resource Monitor for your resource and attaches your debugger to it. At this point, your debugger is invoked. You can now set breakpoints in the DLL. For example, to debug the ResourceTypeControl entry point function, attach a debugger to the main Resource Monitor process and set a breakpoint at s_RmResourceTypeControl. You can set additional breakpoints in the DLL once the call to LoadLibrary is stepped over.

  4. Start Cluster Administrator.
  5. Create a new resource of the type supported by your resource DLL. Specify that the resource should run in a separate Resource Monitor. A dedicated Resource Monitor is required during debugging to help you isolate problems and ensure that other resources remain unaffected by those problems.
  6. View the properties of the new resource by clicking Properties on the File menu after selecting the new resource.
  7. Click the Debug tab.
  8. In the Debug Command Prefix edit control, type the full path to your debugger.
  9. Click OK.

The following procedure describes how to debug a resource type:

To debug a resource type

  • Set the resource type's DebugControlFunctions property to TRUE. Use the following Cluster.exe command:
    cluster restype <resource type display name> /prop DebugControlFunctions=1

    Substitute the display name of your resource type for <resource type display name>.

  • Set the resource type's DebugPrefix property to the path to your debugger. You can use the Debug tab in Cluster Administrator or type the following command:
    cluster restype <resource type display name> /prop DebugPrefix=<path>

    Substitute the display name of your resource type for <resource type display name> and the path to your debugger for <path>.

    When your ResourceTypeControl entry point function is called, the Cluster service checks the settings for these properties. If DebugControlFunctions is set to TRUE and DebugPrefix contains a valid path, the Cluster service creates a new Resource Monitor process for ResourceTypeControl and attaches the specified debugger to it.

  • If you want to debug startup code (the Startup and Open entry point functions) in a resource DLL while the resource is being created, set the DebugPrefix property on the resource type beforehand. You can do this with Cluster.exe or by bringing up properties on the resource type, clicking the Debug tab, and specifying the debugger. Then, when a resource is created, select the Use Separate Resource Monitor check box, and click the Next button to start the debugger immediately.
  • When a resource of the specified type is created, the Resource Monitor waits until the debugger has attached. The Resource Monitor then calls LoadLibrary followed by DebugBreak. Some debuggers (such as CDB and WinDbg) also break when they attach, while others (such as MsDev) do not. In any case, the Resource Monitor displays a message in the debugger's output window when the debugger attaches and after loading the resource DLL.


Debugging Extension DLLs

The following procedure describes how to debug a Cluster Administrator extension DLL:

To debug a Cluster Administrator extension DLL

  1. Run your debugger and load the project workspace that contains your Cluster Administrator extension DLL project.
  2. Select the Win32 Debug version of your Cluster Administrator extension DLL project.
  3. On the Build menu, click Settings.
  4. In the Settings For box, click the entry that represents the Win32 Debug version of your Cluster Administrator extension DLL project.
  5. Click the Debug tab to switch to the Debug property page.
  6. Type the full path to Cluster Administrator (typically c:\Winnt\Cluster\CluAdmin.exe) in the Executable for debug session box and click OK.
  7. Set a breakpoint in the project, such as at the OnInitDialog method for the parameter page in the resprop.cpp source file.
  8. Press F5 to start Cluster Administrator in the debugger.
  9. View the properties of a resource of the type supported by your Cluster Administrator extension DLL.
  10. Click the Parameters tab to switch to the Parameters page. This should cause the debugger to halt at the breakpoint set in step 7.

    The debugger should also halt when you create a new resource of the type supported by your extension DLL.

Warning If you are not running the Cluster service interactively (that is, from the command line), trying to debug a resource DLL with the MSDEV debugger causes the appearance of an error dialog box.


Using the Generic Script Resource Type

The Generic Script resource type provides an easy way to achieve high availability for applications that can be controlled through scriptable interfaces (for example, ActiveX objects or WMI providers). If you have an application that can be started, stopped, and monitored through scripted commands, you can run the application as a Generic Script resource and implement the resource DLL entry points in a script file. A scripted resource is an instance of the Generic Script resource type under the control of a script.

To create a scripted resource

  1. Create a script file that implements required and optional entry points. See Scripting Entry Points.
  2. Create an instance of the Generic Script resource type (see Creating Resources).
  3. Set the ScriptPath property to specify the location of your script file (see Setting Properties).

For each instance of a scripted resource, the Generic Script resource DLL runs an instance of your script in a separate worker thread. Thus there is no need to implement instance management in your script; as far as your script is concerned there is one and only one resource instance.

The Generic Script resource DLL also creates a script object representing the resource. This object, Resource, allows your script to change properties


Scripting Entry Points

The Generic Script resource type allows you to implement the following entry point functions in your script: Open, Online, LooksAlive, IsAlive, Offline, Close, and Terminate. Of these, only LooksAlive and IsAlive are required. For more information see the following sections:

  • Scripting Open
  • Scripting Online
  • Scripting LooksAlive
  • Scripting IsAlive
  • Scripting Offline
  • Scripting Close
  • Scripting Terminate

For each instance of a scripted resource, the Generic Script resource DLL runs an instance of your script in a separate thread. Thus there is no need to implement instance management in your script; as far as your script is concerned there is one and only one resource instance.

The Generic Script resource DLL also creates a Resource object for each resource instance. The Resource object allows your script to log information, manipulate properties, and access the resource name. For more information, see Resource Object.

Note To avoid deadlocks, do not use the Cluster Automation Server or otherwise make any calls to the Cluster API from your control script. All interaction with the cluster should be done through the Resource object.


Scripting Open

The Generic Script resource DLL does not actually call a function named Open in your script. As part of implementing its Open entry point, the DLL instructs the scripting engine to load your script file. When this happens, any code in your script that is not contained inside functions will be executed. The best way to implement an Open routine is to include a declaration section at the beginning of your script. Use this section to initialize global data and create an instances of global objects. Use the Resource object to create private properties (if necessary) and to log errors.


Scripting Online

To implement Online in a script file, create a function named Online that takes no parameters and returns no values. Use the syntax appropriate to the scripting language you are using.

Your implementation of Online should start the resource and bring it to a usable state. Use the Resource object to set property values and to log errors.


Scripting LooksAlive

To implement LooksAlive in a script file, create a function named "LooksAlive" that takes no parameters and returns True or False. Use the syntax appropriate to the scripting language you are using.

Your implementation of LooksAlive should quickly test whether the resource appears to be functioning properly. Use the Resource object to log errors.


Scripting IsAlive

To implement IsAlive in a script file, create a function named "IsAlive" that takes no parameters and returns True or False. Use the syntax appropriate to the scripting language you are using.

Your implementation of IsAlive should accurately determine whether the resource is functioning properly. Use the Resource object to log errors.

Example

See the Scripted Resource Example.


Scripting Offline

To implement Offline in a script file, create a function named "Offline" that takes no parameters and returns no values. Use the syntax appropriate to the scripting language you are using.

Your implementation of Offline should shut down the resource quickly but cleanly. Use the Resource object to log errors.


Scripting Close

To implement Close in a script file, create a function named "Close" that takes no parameters and returns no values. Use the syntax appropriate to the scripting language you are using.

Your implementation of Close should dereference objects and clean up the environment. Use the Resource object to remove custom private properties and to log errors.


Scripting Terminate

To implement Terminate in a script file, create a function named "Terminate" that takes no parameters and returns no values. Use the syntax appropriate to the scripting language you are using.

Your implementation of Terminate should immediately shut down the resource.


Using the Resource Object

The Generic Script resource DLL automatically creates an instance of a Resource object for each instance of a scripted resource. Your script can use the methods and properties of the Resource object to identify the resource, log information about the resource, and manipulate private properties.

Note that the Resource object is internally defined and is only available to your script when a resource is brought online.


Scripted Resource Example

The following example uses the file system object to illustrate a scripted resource implementation.

//////////////////////////////////////////////////////////////////////
//
//  clus_fso.js
//
//  Example script file for a scripted resource.
//
//////////////////////////////////////////////////////////////////////

//--------------------------------------------------------------------
//  Open()
//  Any code not contained within functions is executed during Open().
//  Declare and initialize objects; define properties.
//--------------------------------------------------------------------

var g_strName, g_objFSO;

try
{
    g_strName = Resource.Name;
    Resource.AddProperty( "MyProperty" );
}
catch(e)
{
    Log("Open", e.description);
}

//--------------------------------------------------------------------
//  Online()
//  Bring the resource to a usable state; set initial properties.
//--------------------------------------------------------------------
function Online()
{
    try
    {
        g_objFSO = new ActiveXObject("Scripting.FileSystemObject");
        Resource.MyProperty = "Value";
    }
    catch(e)
    {
        Log("Online", e.description);
    }
}

//--------------------------------------------------------------------
//  LooksAlive()
//  Quickly determine if the resource looks alive.
//--------------------------------------------------------------------
function LooksAlive()
{
    var bAlive;
    try
    {
        bAlive = ( g_objFSO instanceof Object );
    }
    catch(e)
    {
        Log("LooksAlive", e.description);
        bAlive = false;
    }
    finally
    {
        return bAlive;
    }
}

//--------------------------------------------------------------------
//  IsAlive()
//  Confirm that the resource actually is alive by testing basic functionality.
//--------------------------------------------------------------------
function IsAlive()
{
    var objFolders, bAlive;
    bAlive = true;
    try
    {
        objFolders = g_objFSO.Folders;
    }
    catch(e)
    {
        Log("IsAlive", e.description);
        bAlive = false;
    }
    finally
    {
        return bAlive;
    }
}

//--------------------------------------------------------------------
//  Offline()
//  Shut the resource down gracefully.
//--------------------------------------------------------------------
function Offline()
{
    Terminate();
}

//--------------------------------------------------------------------
//  Close()
//  Dereference objects and clean up the environment.
//--------------------------------------------------------------------
function Close()
{
    Terminate();
}

//--------------------------------------------------------------------
//  Terminate()
//  Shut down the resource immediately.
//--------------------------------------------------------------------
function Terminate()
{
    try
    {
        Resource.RemoveProperty( "MyProperty" );
        delete( g_objFSO );
    }
    catch(e)
    {
        Log("Terminate", e.description);
    }
}

//--------------------------------------------------------------------
//  Log()
//  Generic error logging routine.
//--------------------------------------------------------------------
function Log(strFunctionName, strErrorDescription)
{
    var strMessage = strFunctionName + ": " + strErrorDescription;
    try
    {
        Resource.LogInformation( strMessage );
    }
    catch(e)
    {
        WScript.Echo( strMessage );
    }

}


Creating Cluster-Aware Setup Applications

A cluster-aware setup application typically deploys one or more resource types and provides the administrator with some degree of assistance in configuring some initial instances of those types.

The installation process can be divided into the following logical steps, each described in one of the following topics:

  • Installing Files
  • Registering Resource Types
  • Initializing Groups


Installing Files

Use the following procedure to install and distribute the files associated with a resource type.

To install resource type files

  1. Call the GetNodeClusterState function to determine if setup is running in a clustered environment.
  2. If the Cluster service is installed but not running, give the user the option of starting the Cluster service before proceeding with the installation.
  3. If the Cluster service is not installed, you can choose to install a non-cluster version of your resource or not, depending on your requirements.
  4. For each type of resource supported by your resource DLL, install the necessary program files on one of the nodes. This includes binaries, COM and ActiveX components, and other files required for the node to run a local instance of the resource. Data files should be stored on a cluster disk.
  5. Copy your resource DLL and your extension DLL to the node. Use path and filenames that can be consistent across all nodes. For more information, see Deploying Resource Types.
  6. Once the application and the DLLs are installed on one node, enumerate the other nodes and then use the administration shares and remote registry manipulation to install the application and distribute the files over the network. For information on enumeration see Enumerating Objects.
  7. Additionally, copy your extension DLL to any remote system that will use Cluster Administrator to administer the cluster.

Your setup application can now register your resource type. See Registering Resource Types.

Note You should not store program files on cluster disks. Although these drives may seem to be the ideal location for program files because all nodes in the cluster can access them, storing files there causes problems when you upgrade either the Cluster service or the application software, especially if the cluster is in a production environment. Such upgrades require the cluster to be shut down completely. If you choose instead to install program files on all nodes in the cluster, you can use a rolling upgrade approach—upgrading each node individually—without affecting the operation of the cluster.


Registering Resource Types

The following procedure describes how to register new resource types from a cluster-aware setup application. You should complete the steps described in Installing Files before proceeding.

  1. For each resource type supported by your resource DLL, call CreateClusterResourceType once from any cluster node. This establishes the new resource type in the cluster and allows the Cluster service to associate the resource type name with your resource DLL.
  2. Optional: Configure the common properties of your resource type with CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES.
  3. Call the extension DLL's DLLRegisterCluAdminExtension entry point once from any cluster node to register the extension DLL with the cluster.
  4. Perform COM registration for the extension DLL by calling DLLRegisterServer from each cluster node and on each remote system with a copy of the extension.


Initializing Groups

Your resources may have a number of dependencies, required private properties, or optimal common property settings, and will probably need to be published to clients through a virtual server.

After installing the files and registering the new resource types, your cluster-aware setup application can work with the administrator to configure sample resources and groups. Using an interactive format such as a Wizard is often the best solution because:

  • You will need the administrator to supply information such as IP addresses and network names.
  • The administrator will need to learn how to configure and troubleshoot your resources. An interactive procedure allows you to emphasize the critical configuration steps.


Using Cluster Automation Server

Programming with the Cluster Automation Server requires different procedures than those described for the Server Cluster API. The following sections provide information specific to using the Cluster Automation Server:

For illustrations of how the Cluster Automation Server objects relate to each other, see Object Hierarchy.

For procedures describing common programming tasks, see Programming with Cluster Automation Server.

For information on translating Microsoft® Visual Basic® syntax to other programming languages, see Translating Visual Basic.


Object Hierarchy

The Cluster Automation Server objects follow a functional hierarchy in which the objects and collections that can be obtained from any given object are a function of the object's role in the cluster. For example, a ClusResDependencies collection, which controls the dependency relationships for a resource, can only be obtained from a ClusResource object.

The following diagram illustrates the functional hierarchy. Note that there are only two top-level objects: ClusApplication and Cluster.


Programming with Cluster Automation Server

The object-oriented nature of Cluster Automation Server means that almost all cluster programming tasks will involve the following steps:

  1. Determine the cluster operation you need to perform.
  2. Find the Cluster Automation Server object that has a property or method to accomplish the operation.
  3. Determine how to obtain the object in step 2. The Object Hierarchy is useful for this.
  4. Obtain the object and invoke the property or method.

The following sections present examples of common programming tasks:

Creating a Cluster Automation Server Script

Enumerating Objects with Cluster Automation Server

Creating Cluster Objects with Cluster Automation Server

Configuring Resources with Cluster Automation Server


Creating a Cluster Automation Server Script

The following example illustrates a basic Windows Script Host shell in which a script can be inserted. For more information on Windows Script Host, see the Scripting reference in the Platform SDK.

<?xml version="1.0"?>
<!--------------------------------------------------------------------
;  Wshell.wsf
;
;  Generic Windows Script Host shell in which to insert
;  VBScript and JScript code.
;
;  To use this file,
;  1. Save it under a new name (File - Save As - filename)
;     using the "wsf" extension.
;  2. Rename the package and job ID's as needed.
;  3. For each job:
;     a.  Load type library information as needed.
;     b.  Include or insert script code as needed.
;  4. Run the script by calling Windows Script Host from
;     the command prompt according to the following syntax:
;        wscript <filename> [/<options>] [<arguments>]
;        cscript <filename> [/<options>] [<arguments>]
;
;  For more information, see the Scripting reference in the
;  Platform SDK.
--------------------------------------------------------------------->

<package id="Main">

  <job id="Job1">

    <!----------------------------------------------------------------
    ; The following line references the MSCLUS type library, which
    ; makes the library-defined constants and enums available to your
    ; scripts. The reference is job-specific. Each job must include
    ; this line in order to use the type library definitions.
    ----------------------------------------------------------------->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />

    <!----------------------------------------------------------------
    ; To "include" external script files, use the following syntax:
    ;   <script language="VBScript" src="c:\path\filename.vbs" />
    ;   <script language="JScript" src="c:\path\filename.js" />
    ; Otherwise you can embed your script as shown below.
    ; The CDATA wrapper is necessary to appease the XML parser.
    ----------------------------------------------------------------->
    <script language="VBScript">

      <![CDATA[

        'Add VBScript code here.

      ]]>

    </script>

    <script language="JScript">

      <![CDATA[

        //  Add JScript code here.

      ]]>

    </script>

  </job>

  <job id="Job2">
  </job>

</package>


Enumerating Objects with Cluster Automation Server

The following example demonstrates a simple use of the <job> tag to separate functionality in a Windows Script Host script. The example consists of two separate files, MyClusterScriptLibrary.vbs and ClusEnum.wsf.

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'
'  MyClusterScriptLibrary.vbs
'
'  Contains global data and common functions.
'
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
Public objArgs, objCluster

Public Function Connect()
'
' Opens a global cluster object. Using Windows Script Host syntax,
' the cluster name or "" must be passed as the first argument.
'
        Set objArgs = WScript.Arguments
        Set objCluster = CreateObject("MSCluster.Cluster")
        objCluster.Open objArgs(0)
End Function

Public Function Disconnect()
'
' Dereferences global objects.  Used with Connect.
'
        Set objCluster = Nothing
        Set objArgs = Nothing
End Function

Public Function GetEnumString(objCollection, strDelimiter)
'
'  Returns a delimited string of names from a collection.
'  Objects in the collection must support the Name property.
'
        Dim objEnum
        For Each objEnum in objCollection
          GetEnumString = GetEnumString & objEnum.Name & strDelimiter
        Next
        Set objEnum = Nothing
End Function

<?xml version="1.0"?>
<!--------------------------------------------------------------------
;  clusenum.wsf  (requires MyClusterScriptLibrary.vbs to run!)
;
;  Enumerates cluster objects.  Each type of object is contained
;  within a job identified by the object type.  Usage syntax:
;
;     cscript //job:[object type] clusenum.wsf [cluster name]
;
;  Use "" for the cluster name to specify the local cluster.
;
;  Legal object types:   group
;                        network
;                        network interface
;                        node
;                        resource
;                        resource type
;
;  Example:  to enumerate the groups in the local cluster, enter
;
;           cscript //job:"groups" clusenum.wsf ""
;
--------------------------------------------------------------------->
<package id="clusenum">
  <job id="groups">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="MyClusterScriptLibrary.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        Connect
        WScript.Echo GetEnumString(objCluster.ResourceGroups, vbCrLf)
        Disconnect
      ]]>
    </script>
  </job>
  <job id="networks">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="MyClusterScriptLibrary.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        Connect
        WScript.Echo GetEnumString(objCluster.Networks, vbCrLf)
        Disconnect
      ]]>
    </script>
  </job>
  <job id="network interfaces">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="MyClusterScriptLibrary.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        Connect
        WScript.Echo GetEnumString(objCluster.NetInterfaces, vbCrLf)
        Disconnect
      ]]>
    </script>
  </job>
  <job id="nodes">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="MyClusterScriptLibrary.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        Connect
        WScript.Echo GetEnumString(objCluster.Nodes, vbCrLf)
        Disconnect
      ]]>
    </script>
  </job>
  <job id="resources">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="MyClusterScriptLibrary.vbs"/>
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        Connect
        WScript.Echo GetEnumString(objCluster.Resources, vbCrLf)
        Disconnect
      ]]>
    </script>
  </job>
  <job id="resource types">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="MyClusterScriptLibrary.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        Connect
        WScript.Echo GetEnumString(objCluster.ResourceTypes, vbCrLf)
        Disconnect
      ]]>
    </script>
  </job>
</package>


Creating Cluster Objects with Cluster Automation Server

The following HTML/VBScript example creates an HTML form that allows users to create new resources.

<HTML>
<HEAD>
<TITLE>Create Cluster Resource</TITLE>
<SCRIPT LANGUAGE="VBScript" RUNAT="Server">
<!--
''
''  Define globals and open cluster.
''
    Dim objCluster, objGroup, objResType, objRes
    Dim strResName, strResType, strGroupName
    Dim bSepMon
    Set objCluster = CreateObject("MSCluster.Cluster")
    objCluster.Open ""
    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
    Sub lstGroups_OnClick()
        strGroupName = ResCreate.lstGroups.Value
    End Sub
    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
    Sub lstTypes_OnClick()
        strResType = ResCreate.lstTypes.Value
    End Sub
    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
    Sub chkSepMon_OnClick()
        bSepMon = Not bSepMon
    End Sub
    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
    Sub btnOK_OnClick()
        Dim str
        str = ResCreate.txtGroupName.Value
    ''
    ''  If the user has entered text in the group name text box,
    ''  try to create a new group using this name. Otherwise
    ''  the user needs to have selected an existing group
    ''  from the select list.
    ''
        If Len(str) > 0 Then
            strGroupName = str
            Set objGroup = objCluster.ResourceGroups.CreateItem(strGroupName)
        ElseIf Len(strGroupName) > 0 Then
            Set objGroup = objCluster.ResourceGroups.Item(strGroupName)
        Else
            MsgBox("Group name cannot be NULL.")
            Exit Sub
        End If
        strResName = ResCreate.txtResName.Value
        If Len(strResName) > 0 Then
            If bSepMon Then
                Set objRes = objGroup.Resources.CreateItem(strResName, strResType, 1)
            Else
                Set objRes = objGroup.Resources.CreateItem(strResName, strResType, 0)
            End If
        Else
            MsgBox("Group name cannot be NULL.")
            Exit Sub
        End If
        Set objRes = Nothing
        Set objGroup = Nothing
        Set objCluster = Nothing
        Document.Navigate "results.html"  ' TODO: create this page!
    End Sub
    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
    Sub btnCancel_OnClick()
        Document.Navigate "cancel.html"   ' TODO: create this page!
    End Sub
    ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
-->
</SCRIPT>
</HEAD>
<BODY>
<H1>Create Cluster Resource</H1><HR>
<FORM NAME="ResCreate"
      METHOD="POST"
      ACTION="rescreate_results.vbs"
      LANGUAGE="VBScript"
      TITLE="Resource Creation Form">
<!--------------------------------------------------------------------
Add a select list for groups.
--------------------------------------------------------------------->
    <B>Select group in which to create resource...</B><BR>
    <SELECT ID="lstGroups" SIZE="5">
    <SCRIPT LANGUAGE="VBScript">
    <!--
        For Each objGroup in objCluster.ResourceGroups
            Document.Write "<OPTION VALUE=" & Chr(34) & objGroup.Name & Chr(34) & ">" & objGroup.Name & vbCrLf
        Next
    -->
    </SCRIPT>
    </SELECT>
    <BR>
<!--------------------------------------------------------------------
Add a text box to allow the user to create a new group..
--------------------------------------------------------------------->
    <B>...or enter new group name:</B><BR>
    <INPUT TYPE="TEXT" ID="txtGroupName" SIZE="40">
    <BR><BR>
<!--------------------------------------------------------------------
Add a select list for resource types.
--------------------------------------------------------------------->
    <B>Specify resource type:</B><BR>
    <SELECT ID="lstTypes" SIZE="5">
    <SCRIPT LANGUAGE="VBScript">
    <!--
        For Each objResType in objCluster.ResourceTypes
            Document.Write "<OPTION VALUE=" & Chr(34) & objResType.Name & Chr(34) & ">" & objResType.Name & vbCrLf
        Next
    -->
    </SCRIPT>
    </SELECT>
    <BR><BR>
<!--------------------------------------------------------------------
Add "separate monitor" checkbox.
--------------------------------------------------------------------->
    <B>Create resource in a separate Resource Monitor:</B>
    <INPUT TYPE="Checkbox" ID="chkSepMon">
    <BR><BR>
<!--------------------------------------------------------------------
Add a text box for the resource name.
--------------------------------------------------------------------->
    <B>Resource Name:</B>
    <INPUT TYPE="TEXT" ID="txtResName" SIZE="40">
    <BR><HR>
<!--------------------------------------------
Add "OK"and "Cancel" buttons.
--------------------------------------------->
    <INPUT TYPE="BUTTON" ID="btnOK" VALUE="   OK   ">
    <INPUT TYPE="BUTTON" ID="btnCancel" VALUE="Cancel">
</FORM>
</BODY>
</HTML>


Configuring Resources With Cluster Automation Server

The following example creates resources of different types, satisfying required private properties and required dependencies as necessary. The example consists of two separate files, CreateResource.vbs and CreateResource.wsf.

'---------------------------------------------------------------------
' CreateResource.vbs
' Global data and functions supporting CreateResource.wsf.
'---------------------------------------------------------------------
Option Explicit

' In CreateResource.wsf, each resource type assigns appropriate
' values to these global variables. The CreateResource function
' uses these values to parse the command-line arguments and assign
' values to the required private properties for a given resource type.
Public strResType, strSyntax
Public intBasicArgs, intMinArgs, intMaxArgs, intReqDeps
Public varPropNames, varPropValues, varReqDeps

Public Function CreateResource()
    Dim objGroup, objNewRes, objResource, objProperties, objReqDeps, objCluster, objArgs
    Dim strClusterName, strGroupName, strResName
    Dim intCounter
    Set objArgs = WScript.Arguments
    If objArgs.Count < intMinArgs Or objArgs.Count > intMaxArgs Then
        Wscript.Echo strSyntax
        WScript.Quit
    End If
    strClusterName = objArgs(0)
    strGroupName = objArgs(1)
    strResName = objArgs(2)

'   Load property values for required private properties
'   into an array.  The size of the array and the
'   expected arguments are defined by the calling script.
    For intCounter = 0 To objArgs.Count - intBasicArgs - 1
    If IsNumeric( objArgs( intCounter + intBasicArgs )) Then
            varPropValues(intCounter) = CLng(objArgs(intCounter + intBasicArgs))
    Else
            varPropValues(intCounter) = objArgs(intCounter + intBasicArgs)
        End If
    Next

    Set objCluster = CreateObject("MSCluster.Cluster")
    objCluster.Open strClusterName
    Set objGroup = objCluster.ResourceGroups.Item(strGroupName)
    Set objNewRes = objGroup.Resources.CreateItem(strResName, strResType, 0)
    Set objReqDeps = objNewRes.Dependencies

'   Look for resources already in the group that will satisfy the
'   required dependencies specified in CreateResource.wsf.
'   If a resource of the required type does not exist it
'   will have to be created and added as a dependency by some
'   other means.
    For intCounter = 0 To intReqDeps - 1
        For Each objResource In objGroup.Resources
            If objResource.Type.Name = varReqDeps(intCounter) Then
                objNewRes.Dependencies.AddItem objResource
                Exit For
            End If
        Next
    Next
    Set objProperties = objNewRes.PrivateProperties
    For intCounter = 0 To intMaxArgs - intBasicArgs - 1
        objProperties.Item(varPropNames(intCounter)).Value = varPropValues(intCounter)
    Next
    objProperties.SaveChanges
    Set objGroup = Nothing
    Set objNewRes = Nothing
    Set objProperties = Nothing
    Set objReqDeps = Nothing
    Set objCluster = Nothing
End Function

<?xml version="1.0"?>
<!--------------------------------------------------------------------
;  CreateResource.wsf  (requires CreateResource.vbs to run!)
;
;  Creates resources of different types.  To create a resource of
;  a given type, use the resource type name as a job ID.  Each
;  resource type will have a different syntax depending
;  on its required private properties.
;
;  Basic syntax:
;     cscript //job:[object type] CreateResource.wsf cluster group resource prop1, prop2, ... , propN
;
;  Refer to the syntax string in each job for specific commands.
--------------------------------------------------------------------->
<package>
  <job id="File Share">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "File Share"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "Path Sharename <Remarks> <ShareSubDirs>"
        intBasicArgs = 3
        intMinArgs = 5
        intMaxArgs = 7
        varPropNames = Array( "Path", "ShareName", "Remark", "ShareSubDirs" )
        varPropValues = Array( "", "", "", 1 )
        intReqDeps = 3
        varReqDeps = Array( "Physical Disk", "IP Address", "Network Name" )
        CreateResource
      ]]>
    </script>
  </job>
  <job id="Generic Application">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "Generic Application"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "CommandLine CurrentDirectory <InteractWithDesktop> <UseNetworkName>"
        intBasicArgs = 3
        intMinArgs = 5
        intMaxArgs = 7
        varPropNames = Array( "CommandLine", "CurrentDirectory", "InteractWithDesktop", "UseNetworkName" )
        varPropValues = Array( "", "", 1, 0 )
        intReqDeps = 1
        varReqDeps = Array( "Network Name" )
        CreateResource
      ]]>
    </script>
  </job>
  <job id="Generic Service">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "Generic Service"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "ServiceName <StartupParameters> <UseNetworkName>"
        intBasicArgs = 3
        intMinArgs = 4
        intMaxArgs = 6
        varPropNames = Array( "ServiceName", "StartupParameters", "UseNetworkName" )
        varPropValues = Array( "", "", 0 )
        intReqDeps = 1
        varReqDeps = Array( "Network Name" )
        CreateResource
      ]]>
    </script>
  </job>
  <job id="IP Address">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "IP Address"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "Address SubnetMask Network <EnableNetBIOS>"
        intBasicArgs = 3
        intMinArgs = 6
        intMaxArgs = 7
        varPropNames = Array( "Address", "SubnetMask", "Network", "EnableNetBIOS" )
        varPropValues = Array( "", "", "", 1 )
        intReqDeps = 0
        varReqDeps = 0
        CreateResource
      ]]>
    </script>
  </job>
  <job id="Network Name">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "Network Name"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "Name <RemapPipeNames>"
        intBasicArgs = 3
        intMinArgs = 4
        intMaxArgs = 5
        varPropNames = Array( "Name", "RemapPipeNames" )
        varPropValues = Array( "", 0 )
        intReqDeps = 1
        varReqDeps = Array( "IP Address" )
        CreateResource
      ]]>
    </script>
  </job>
  <job id="Physical Disk">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "Physical Disk"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "Signature(in decimal) <SkipChkdsk> <ConditionalMount>"
        intBasicArgs = 3
        intMinArgs = 4
        intMaxArgs = 6
        varPropNames = Array( "Signature", "SkipChkdsk", "ConditionalMount" )
        varPropValues = Array( -1, 0, 1 )
        intReqDeps = 0
        varReqDeps = 0
        CreateResource
      ]]>
    </script>
  </job>
  <job id="Print Spooler">
    <!-- The following line references the MSCLUS type library. -->
    <reference guid="{F2E606E0-2631-11D1-89F1-00A0C90D061E}" version="1.0" />
    <script language="VBScript" src="createresource.vbs" />
    <script language="VBScript">
      <![CDATA[
        Option Explicit
        strResType = "Print Spooler"
        strSyntax = "cscript //job:" & Chr(39) & strResType & Chr(39) & _
                    " CreateResource.wsf cluster group resource " & _
                    "Path <Timeout>"
        intBasicArgs = 3
        intMinArgs = 4
        intMaxArgs = 5
        varPropNames = Array( "DefaultSpoolDirectory", "JobCompletionTimeout" )
        varPropValues = Array( "", 160000 )
        intReqDeps = 2
        varReqDeps = Array( "Physical Disk", "Network Name" )
        CreateResource
      ]]>
    </script>
  </job>
</package>


Translating Visual Basic

The Cluster Automation Server supports many different programming languages. For information on translating Visual Basic syntax to other programming languages, see COM Language Translations.


Server Cluster API Reference

This section describes the functions, interfaces and methods, control codes, properties, and structures and macros available in the Server Cluster API. The information is categorized in the following sections:

  • Cluster Administrator Extension Functions
  • Cluster Database Access Functions
  • Cluster Object Management Functions
  • Cluster Utility Functions
  • Control Code Functions
  • Resource DLL Functions
  • Cluster Properties
  • Cluster Structures


Control Code Reference

The Cluster API defines a small set of control code functions—one for each cluster object—as "generic" interfaces to a wide range of cluster operations. Control codes—32 bit values used as function parameters—determine the kind of operation a control code function will perform. Together, the control code functions and the control codes support nearly every kind of cluster functionality.

Refer to the following sections:

For reference information on the control code functions and their related control codes, see Control Code Functions.

For background information on the control codes, including how to create user-defined control codes, see Using Control Codes.


Control Code Functions

The control code functions take control codes as parameters, allowing them to perform a wide variety of operations on cluster objects. As described in the Standard Order of Preference, cluster-aware applications should use control code functions whenever possible.

Each cluster object has one control code function and several control codes:

  • ClusterControl
  • ClusterGroupControl
  • ClusterNetworkControl
  • ClusterNetInterfaceControl
  • ClusterNodeControl
  • ClusterResourceControl
  • ClusterResourceTypeControl


ClusterControl

The ClusterControl function initiates an operation that affects a cluster. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterControl(
  HCLUSTER hCluster,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hCluster
[in] Handle to the cluster to be affected.
hHostNode
[in] If non-NULL, handle to the node to perform the operation represented by the control code. If NULL, the local node performs the operation. Specifying hHostNode is optional.
dwControlCode
[in] A cluster control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_UNKNOWN
  • CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] The allocated size (in bytes) of the input buffer.
lpOutBuffer
[out] Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.
cbOutBufferSize
[in] The allocated size (in bytes) of the output buffer.
lpcbBytesReturned
[in, out] Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpcbBytesReturned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

If ClusterControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Cluster Control Codes, OpenCluster


ClusterGroupControl

The ClusterGroupControl function initiates an operation that affects a group. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterGroupControl(
  HGROUP hGroup,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hGroup
[in] Handle to the group to be affected.
hHostNode
[in] If non-NULL, handle to the node to perform the operation represented by the control code. If NULL, the node that owns the group performs the operation. Specifying hHostNode is optional.
dwControlCode
[in] A group control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES
  • CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_GET_CHARACTERISTICS
  • CLUSCTL_GROUP_GET_COMMON_PROPERTIES
  • CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_GROUP_GET_FLAGS
  • CLUSCTL_GROUP_GET_ID
  • CLUSCTL_GROUP_GET_NAME
  • CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_QUERY_DELETE
  • CLUSCTL_GROUP_SET_COMMON_PROPERTIES
  • CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_UNKNOWN
  • CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] The allocated size (in bytes) of the input buffer.
lpOutBuffer
[out] Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.
cbOutBufferSize
[in] The allocated size (in bytes) of the output buffer.
lpcbBytesReturned
[in, out] Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpcbBytesReturned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

If ClusterGroupControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterGroupControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Code Example

The following code fragment demonstrates a call to ClusterGroupControl.

// Allocate buffer.
lpPropList = LocalAlloc(
  LPTR, cbAllocated );

// Initial call.
dwResult = ClusterGroupControl(
  hCluster,
  NULL,
  CLUSCTL_GROUP_GET_COMMON_PROPERTIES,
  NULL,
  0,
  lpPropList,
  cbAllocated,
  &cbReturned );

// If the buffer was too small, reallocate it to the necessary size,
// returned in cbReturned.
if (
  dwResult == ERROR_MORE_DATA )
{
    LocalFree(
  lpPropList );
    cbAllocated = cbReturned;
    lpPropList = LocalAlloc(
  LPTR, cbAllocated );
    if (
  lpPropList == NULL )
    {
        // Respond to error.
    }
    dwResult = ClusterGroupControl(
  hCluster,
  NULL,
  CLUSCTL_GROUP_GET_COMMON_PROPERTIES,
  NULL,
  0,
  lpPropList,
  cbAllocated,
  &cbReturned );
}

if (
  dwResult != ERROR_SUCCESS )
{
    // Respond to error.
}

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Group Control Codes, OpenCluster


ClusterNetworkControl

The ClusterNetworkControl function initiates an operation on a network. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterNetworkControl(
  HNETWORK hNetwork,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hNetwork
[in] Handle to the network to be affected by the operation.
hHostNode
[in] If non-NULL, handle to the node hosting the affected network. If NULL, the local node performs the operation. Specifying hHostNode is optional.
dwControlCode
[in] A network control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_GET_CHARACTERISTICS
  • CLUSCTL_NETWORK_GET_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_NETWORK_GET_FLAGS
  • CLUSCTL_NETWORK_GET_ID
  • CLUSCTL_NETWORK_GET_NAME
  • CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_SET_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_UNKNOWN
  • CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] The allocated size (in bytes) of the input buffer.
lpOutBuffer
[out] Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.
cbOutBufferSize
[in] The allocated size (in bytes) of the output buffer.
lpcbBytesReturned
[in, out] Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpcbBytesReturned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

If ClusterNetworkControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned, and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterNetworkControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Network Control Codes, OpenCluster


ClusterNetInterfaceControl

The ClusterNetInterfaceControl function initiates an operation that affects a network interface. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterNetInterfaceControl(
  HNETWORKINTERFACE hNetInterface,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hNetInterface
[in] Handle to the network interface to be affected.
hHostNode
[in] If non-NULL, handle to the node that owns the network interface to be affected. If NULL, the local node performs the operation. Specifying hHostNode is optional.
dwControlCode
[in] A network interface control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS
  • CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_NETINTERFACE_GET_FLAGS
  • CLUSCTL_NETINTERFACE_GET_ID
  • CLUSCTL_NETINTERFACE_GET_NAME
  • CLUSCTL_NETINTERFACE_GET_NETWORK
  • CLUSCTL_NETINTERFACE_GET_NODE
  • CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_UNKNOWN
  • CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] The allocated size (in bytes) of the input buffer.
lpOutBuffer
[out] Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.
cbOutBufferSize
[in] The allocated size (in bytes) of the output buffer.
lpcbBytesReturned
[in, out] Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpcbBytesReturned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

If ClusterNetInterfaceControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterNetInterfaceControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Network Interface Control Codes


ClusterNodeControl

The ClusterNodeControl function initiates an operation that affects a node. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterNodeControl(
  HNODE hNode,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hNode
[in] Handle to the node to be affected.
hHostNode
[in] If non-NULL, handle to the node that will perform the operation instead of the node specified in hNode. If NULL, the node represented by hNode performs the operation.
dwControlCode
[in] A node control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_NODE_ENUM_COMMON_PROPERTIES
  • CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_GET_CHARACTERISTICS
  • CLUSCTL_NODE_GET_COMMON_PROPERTIES
  • CLUSCTL_NODE_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_NODE_GET_FLAGS
  • CLUSCTL_NODE_GET_ID
  • CLUSCTL_NODE_GET_NAME
  • CLUSCTL_NODE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_SET_COMMON_PROPERTIES
  • CLUSCTL_NODE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_UNKNOWN
  • CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] The allocated size (in bytes) of the input buffer.
lpOutBuffer
[out] Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.
cbOutBufferSize
[in] The allocated size (in bytes) of the output buffer.
lpcbBytesReturned
[in, out] Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpcbBytesReturned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

If ClusterNodeControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterNodeControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Node Control Codes, OpenCluster


ClusterResourceControl

The ClusterResourceControl function initiates an operation affecting a resource. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterResourceControl(
  HRESOURCE hResource,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hResource
[in] Handle to the resource to be affected.
hHostNode
[in] Optional handle to the node to perform the operation. If NULL, the node that owns the resource identified by hResource performs the operation.
dwControlCode
[in] A resource control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT
  • CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT
  • CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT
  • CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT
  • CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_GET_CHARACTERISTICS
  • CLUSCTL_RESOURCE_GET_CLASS_INFO
  • CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS
  • CLUSCTL_RESOURCE_GET_FLAGS
  • CLUSCTL_RESOURCE_GET_ID
  • CLUSCTL_RESOURCE_GET_NAME
  • CLUSCTL_RESOURCE_GET_NETWORK_NAME
  • CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS
  • CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES
  • CLUSCTL_RESOURCE_GET_RESOURCE_TYPE
  • CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_QUERY_DELETE
  • CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO
  • CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID
  • CLUSCTL_RESOURCE_UNKNOWN
  • CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to an input buffer containing information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] The allocated size (in bytes) of the input buffer.
lpOutBuffer
[out] Pointer to an output buffer to receive the data resulting from the operation, or NULL if no data will be returned.
cbOutBufferSize
[in] The allocated size (in bytes) of the output buffer.
lpcbBytesReturned
[in, out] Returns the actual size (in bytes) of the data resulting from the operation. If this information is not needed, pass NULL for lpcbBytesReturned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
ERROR_RESOURCE_PROPERTIES_STORED | Applies only to CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES and CLUSTCL_RESOURCE_SET_PRIVATE_PROPERTIES. Indicates that the properties were successfully stored but have not yet been applied to the resource. The new properties will take effect after the resource is taken offline and brought online again.
ERROR_HOST_NODE_NOT_RESOURCE_OWNER | The node specified by the hNode parameter is not the node that owns the resource specified by hResource.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

When ClusterResourceControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned, and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

The ClusterResourceControl function is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Resource Control Codes, OpenCluster


ClusterResourceTypeControl

The ClusterResourceTypeControl function initiates an operation affecting a resource type. The operation performed depends on the control code passed to the dwControlCode parameter.

DWORD WINAPI ClusterResourceTypeControl(
  HCLUSTER hCluster,
  LPCWSTR ResourceTypeName,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hCluster
[in] Handle to the cluster containing the resource type identified in ResourceTypeName.
ResourceTypeName
[in] Pointer to a NULL-terminated Unicode containing the name of the resource type to be affected.
hHostNode
[in] Optional handle to the node hosting the affected resource type.
dwControlCode
[in] A resource type control code specifying the operation to be performed. Refer to the following sections for the syntax associated with a control code:
  • CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS
  • CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO
  • CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS
  • CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS
  • CLUSCTL_RESOURCE_TYPE_GET_FLAGS
  • CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS
  • CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS
  • CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES
  • CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_QUERY_DELETE
  • CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS
  • CLUSCTL_RESOURCE_TYPE_UNKNOWN
  • CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES
lpInBuffer
[in] Pointer to the input buffer with information needed for the operation, or NULL if no information is needed.
cbInBufferSize
[in] Number of bytes in the buffer pointed to by lpInBuffer.
lpOutBuffer
[out] Pointer to the output buffer with information resulting from the operation, or NULL if nothing will be returned.
cbOutBufferSize
[in] Number of bytes in the output buffer pointed to by lpOutBuffer, or zero if the caller does not know how much data will be returned.
lpcbBytesReturned
[in, out] Pointer to the number of bytes in the buffer pointed to by lpOutBuffer that were actually filled in as a result of the operation. The caller can pass NULL for lpcbBytesReturned if ClusterResourceTypeControl doesn't need to pass back the number of bytes in the output buffer.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful. If the operation required an output buffer, lpcbBytesReturned (if not NULL on input) points to the actual size of the data returned in the buffer.
ERROR_MORE_DATA | The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter (if not NULL on input) points to the size required for the output buffer. Only operations requiring an output buffer return ERROR_MORE_DATA.
Win32 Error | The operation was not successful. If the operation required an output buffer, the value specified by lpcbBytesReturned (if not NULL on input) is unreliable.

Remarks

When ClusterResourceTypeControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned, and call the function again.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see LPC and RPC Handles and OpenCluster.

ClusterResourceTypeControl is one of the control code functions. For more information on control codes and control code functions, see Using Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenCluster, Resource Type Control Codes


Control Codes

Control codes are 32-bit integers used to describe an operation on a cluster object. Control codes are categorized as internal or external:

  • Applications use external control codes in control code functions to read, validate, and set properties and to perform a variety of other operations on cluster objects.
  • The Cluster service uses internal control codes to notify resource DLLs of changes affecting resources or resource types.

It is important to become familiar with the capabilities of the control codes. Applications and resource DLLs should always use control codes, if possible, to perform operations on cluster objects. The control codes are designed to maximize security, protect the cluster database, and ensure resource DLL notification.


Cluster Control Codes

The Server Cluster API defines the following external control codes for clusters. There are no internal control codes defined for clusters.

  • CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_CLUSTER_GET_FQDN
  • CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES
  • CLUSCTL_CLUSTER_UNKNOWN
  • CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES


CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES

The CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write cluster common property names. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                // cluster handle
  hHostNode,                               // optional node handle
  CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES,  // this control code
  NULL,                                    // input buffer (not used)
  0,                                       // input buffer size (not used)
  lpOutBuffer,                             // output buffer: array of strings
  cbOutBufferSize,                         // output buffer size (bytes)
  lpcbBytesReturned                        // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, lpOutBuffer contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write cluster common property.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES control code returns only property names, not property values. To retrieve values for common cluster properties, use CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES and CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES, CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES, ClusterControl


CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES control code retrieves a list of the cluster private property names. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                 // cluster handle
  hHostNode,                                // optional node handle
  CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES,  // this control code
  NULL,                                     // input buffer (not used)
  0,                                        // input buffer size (not used)
  lpOutBuffer,                              // output buffer: array of strings
  cbOutBufferSize,                          // output buffer size (bytes)
  lpcbBytesReturned                         // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, lpOutBuffer contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write cluster private property.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private cluster properties. Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES

The CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES control code retrieves the read-write cluster common properties for a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a property list containing the specified cluster's read-write cluster common properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS

The CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS control code retrieves a property list describing the format of each cluster common property. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each common property.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_FQDN

The CLUSCTL_CLUSTER_GET_FQDN control code retrieves the fully qualified domain name (FQDN) of a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_CLUSTER_GET_FQDN,               // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: string
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a null-terminated Uniciode string specifying the FQDN of the cluster.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_FQDN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FQDN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES

The CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES control code retrieves the read-write private properties for a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                // cluster handle
  hHostNode,                               // optional node handle
  CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES,  // this control code
  NULL,                                    // input buffer (not used)
  0,                                       // input buffer size (not used)
  lpOutBuffer,                             // output buffer: property list
  cbOutBufferSize,                         // output buffer size (bytes)
  lpcbBytesReturned                        // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a property list containing the specified cluster's read-write cluster private properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

By default, server clusters do not define any private cluster properties. Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS

The CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS control code retrieves a property list describing the format of each cluster private property. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each private property.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

By default, server clusters do not define any private cluster properties. Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_PRIVATE_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES

The CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                  // cluster handle
  hHostNode,                                 // optional node handle
  CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES,  // this control code
  NULL,                                      // input buffer (not used)
  0,                                         // input buffer size (not used)
  lpOutBuffer,                               // output buffer: property list
  cbOutBufferSize,                           // output buffer size (bytes)
  lpcbBytesReturned                          // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a property list containing the specified cluster's read-only common cluster properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                   // cluster handle
  hHostNode,                                  // optional node handle
  CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES,  // this control code
  NULL,                                       // input buffer (not used)
  0,                                          // input buffer size (not used)
  lpOutBuffer,                                // output buffer: property list
  cbOutBufferSize,                            // output buffer size (bytes)
  lpcbBytesReturned                           // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpOutBuffer
On a successful return, points to a property list containing the specified cluster's read-only cluster private properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

By default, server clusters do not define any private cluster properties. Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES

The CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES control code is used to update the read-write common properties for a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                             // input buffer: property list
  cbInBufferSize,                         // input buffer size (bytes)
  NULL,                                   // output buffer (not used)
  0,                                      // output buffer size (not used)
  NULL                                    // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpInBuffer
Pass a pointer to a property list containing new values for one or more read-write common cluster properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES

The CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES control code is used to update the read-write private properties for a cluster. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                // cluster handle
  hHostNode,                               // optional node handle
  CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                              // input buffer: property list
  cbInBufferSize,                          // input buffer size (bytes)
  NULL,                                    // output buffer (not used)
  0,                                       // output buffer size (not used)
  NULL                                     // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write cluster private properties. Properties that do not already exist will be created.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private cluster properties. You can use the CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES control code to define private properties for a cluster.

By default, server clusters do not define any private cluster properties. Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_UNKNOWN

The CLUSCTL_CLUSTER_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                 // cluster handle
  hHostNode,                // optional node handle
  CLUSCTL_CLUSTER_UNKNOWN,  // this control code
  NULL,                     // input buffer (not used)
  0,                        // input buffer size (not used)
  NULL,                     // output buffer (not used)
  0,                        // output buffer size (not used)
  NULL                      // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.

Remarks

ClusterControl always returns ERROR_SUCCESS when processing the CLUSCTL_CLUSTER_UNKNOWN control code.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid cluster property names and values and that the list is properly formatted. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                    // cluster handle
  hHostNode,                                   // optional node handle
  CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                  // input buffer: property list
  cbInBufferSize,                              // input buffer size (bytes)
  NULL,                                        // output buffer (not used)
  0,                                           // output buffer size (not used)
  NULL                                         // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write common cluster properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES control code verifies that a property list is properly formatted. Applications use this control code as a ClusterControl parameter.

Control Code Function Syntax

dwReturn =
ClusterControl(
  hCluster,                                     // cluster handle
  hHostNode,                                    // optional node handle
  CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                                   // input buffer: property list
  cbInBufferSize,                               // input buffer size (bytes)
  NULL,                                         // output buffer (not used)
  0,                                            // output buffer size (not used)
  NULL                                          // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write cluster private properties.
dwReturn
ClusterControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_CLUSTER_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_CLUSTER
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterControl


Group Control Codes

The Server Cluster API defines the following external control codes for groups. There are no internal control codes defined for groups.

  • CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES
  • CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_GET_CHARACTERISTICS
  • CLUSCTL_GROUP_GET_COMMON_PROPERTIES
  • CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_GROUP_GET_FLAGS
  • CLUSCTL_GROUP_GET_NAME
  • CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_QUERY_DELETE
  • CLUSCTL_GROUP_SET_COMMON_PROPERTIES
  • CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES
  • CLUSCTL_GROUP_UNKNOWN
  • CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES


CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES

The CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write group common property names for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                // group handle
  hHostNode,                             // optional node handle
  CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES,  // this control code
  NULL,                                  // input buffer (not used)
  0,                                     // input buffer size (not used)
  lpOutBuffer,                           // output buffer: array of strings
  cbOutBufferSize,                       // output buffer size (bytes)
  lpcbBytesReturned                      // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, lpOutBuffer contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write group common property.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES control code returns only property names, not property values. To retrieve values for common group properties, use CLUSCTL_GROUP_GET_COMMON_PROPERTIES and CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

#include "ClusDocEx.h"
//////////////////////////////////////////////////////////////////////
// ClusDocEx_IsGroupProperty
//
// Verifies that a string corresponds to a common group property name.
//
// Arguments:
//    IN HGROUP hGroup        Group handle.
//    IN LPWSTR lpszPropName  Possible property name to verify.
//
// Return Values
//    1   The string contains a group common property name.
//    0   The string does not match any common group property name.
//   -1   Results unknown - an error occurred. Call GetLastError for more info.
//////////////////////////////////////////////////////////////////////
int
ClusDocEx_IsGroupProperty
(
    IN HGROUP hGroup,
    IN LPWSTR lpszPropName
)
{
    DWORD  dwResult    = 0;
    DWORD  cbAllocated = 256;
    DWORD  cbRequired  = 0;
    DWORD  cbBufferPos = 0;
    LPVOID lpOutBuffer = LocalAlloc( LPTR, cbAllocated );
    LPWSTR lpszParser  = NULL;
    int    intGroupProperty = -1;

    //
    // Basic bounds checking.
    //
    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto EndFunc;
    }
    if( lpszPropName == NULL || hGroup == NULL )
    {
        dwResult = ERROR_BAD_ARGUMENTS;
        goto EndFunc;
    }

    //
    // First call.
    //
    dwResult = ClusterGroupControl( hGroup,
                                    NULL,
                                    CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES,
                                    NULL,
                                    0,
                                    lpOutBuffer,
                                    cbAllocated,
                                    &cbRequired );

    //
    // Reallocation routine.
    //
    if( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );
        cbAllocated = cbRequired;
        lpOutBuffer = LocalAlloc( LPTR, cbAllocated );
        dwResult = ClusterGroupControl( hGroup,
                                        NULL,
                                        CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES,
                                        NULL,
                                        0,
                                        lpOutBuffer,
                                        cbAllocated,
                                        &cbRequired );
    }

    //
    // Parse the output buffer (array of strings) to
    // find the specified property name.
    //
    if( dwResult == ERROR_SUCCESS )
    {
        cbBufferPos = 0;
        lpszParser = (LPWSTR)lpOutBuffer;

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto EndFunc;
        }

        while(1)
        {
            if( lstrcmpi( lpszPropName, lpszParser ) == 0 )
            {
                intGroupProperty = 1;
                break;
            }

            cbBufferPos += ( lstrlenW(lpszParser) + 1 ) * sizeof( WCHAR );

            if( cbBufferPos < cbRequired )
            {
                lpszParser += lstrlenW(lpszParser) + 1;
            }
            else
            {
                intGroupProperty = 0;
                break;
            }
        }
    }

EndFunc:

    LocalFree( lpOutBuffer );
    SetLastError( dwResult );
    return intGroupProperty;

}

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_GROUP_GET_COMMON_PROPERTIES, CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES, ClusterGroupControl


CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES control code retrieves a list of the private property names for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                 // group handle
  hHostNode,                              // optional node handle
  CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: array of strings
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, lpOutBuffer contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write group private property.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for groups.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_CHARACTERISTICS

The CLUSCTL_GROUP_GET_CHARACTERISTICS control code retrieves the intrinsic characteristics of a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                             // group handle
  hHostNode,                          // optional node handle
  CLUSCTL_GROUP_GET_CHARACTERISTICS,  // this control code
  NULL,                               // input buffer (not used)
  0,                                  // input buffer size (not used)
  lpOutBuffer,                        // output buffer: DWORD bitmask
  cbOutBufferSize,                    // output buffer size (bytes)
  lpcbBytesReturned                   // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing the group's characteristics. Only one bitmask is currently defined:
CLUS_CHAR_UNKNOWN
The group has no known characteristics.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_CHARACTERISTICS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CHARACTERISTICS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_COMMON_PROPERTIES

The CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code retrieves the read-write group common properties for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                               // group handle
  hHostNode,                            // optional node handle
  CLUSCTL_GROUP_GET_COMMON_PROPERTIES,  // this control code
  NULL,                                 // input buffer (not used)
  0,                                    // input buffer size (not used)
  lpOutBuffer,                          // output buffer: property list
  cbOutBufferSize,                      // output buffer size (bytes)
  lpcbBytesReturned                     // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a property list containing the specified group's read-write group common properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS

The CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS control code returns a property list describing the format of each group common property. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each group common property.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The property list returned by CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS contains one entry for each group common property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_COMMON_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_FLAGS

The CLUSCTL_GROUP_GET_FLAGS control code retrieves the flags that are set for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                   // group handle
  hHostNode,                // optional node handle
  CLUSCTL_GROUP_GET_FLAGS,  // this control code
  NULL,                     // input buffer (not used)
  0,                        // input buffer size (not used)
  lpOutBuffer,              // output buffer: property list
  cbOutBufferSize,          // output buffer size (bytes)
  lpcbBytesReturned         // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to DWORD bitmask specifying the flags defined for the group.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, no flags are defined for groups.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_FLAGS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FLAGS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLUSCTL_GROUP_GET_ID

The CLUSCTL_GROUP_GET_ID control code retrieves the cluster database subkey identifier for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                // group handle
  hHostNode,             // optional node handle
  CLUSCTL_GROUP_GET_ID,  // this control code
  NULL,                  // input buffer (not used)
  0,                     // input buffer size (not used)
  lpOutBuffer,           // output buffer: string
  cbOutBufferSize,       // output buffer size (bytes)
  lpcbBytesReturned      // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a NULL-terminated Unicode string containing the GUID that identifies the group.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The GUID string returned in lpOutBuffer resides in the cluster database under HKEY_LOCAL_MACHINE\Cluster\Groups.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_ID as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_ID
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_NAME

The CLUSCTL_GROUP_GET_NAME control code retrieves the name of a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                  // group handle
  hHostNode,               // optional node handle
  CLUSCTL_GROUP_GET_NAME,  // this control code
  NULL,                    // input buffer (not used)
  0,                       // input buffer size (not used)
  lpOutBuffer,             // output buffer: string
  cbOutBufferSize,         // output buffer size (bytes)
  lpcbBytesReturned        // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a NULL-terminated Unicode string containing the name of the group.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The name of a group is stored in the Name property. To retrieve the Name property along with the other read-only common group properties, use the CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NAME
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES, ClusterGroupControl, Name


CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES control code retrieves the read-write private properties for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                // group handle
  hHostNode,                             // optional node handle
  CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES,  // this control code
  NULL,                                  // input buffer (not used)
  0,                                     // input buffer size (not used)
  lpOutBuffer,                           // output buffer: property list
  cbOutBufferSize,                       // output buffer size (bytes)
  lpcbBytesReturned                      // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a property list containing the specified group's read-write group private properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for groups.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS

The CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS control code retrieves a property list describing the format of each group private property. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each private property.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for groups. CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS does not retrieve information about unknown properties.

The property list returned by CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS contains one entry for each group private property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_PRIVATE_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterGroupControl


CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES

The CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                  // group handle
  hHostNode,                               // optional node handle
  CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES,  // this control code
  NULL,                                    // input buffer (not used)
  0,                                       // input buffer size (not used)
  lpOutBuffer,                             // output buffer: property list
  cbOutBufferSize,                         // output buffer size (bytes)
  lpcbBytesReturned                        // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a property list containing the specified group's read-only common group properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl, Name


CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                   // group handle
  hHostNode,                                // optional node handle
  CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES,  // this control code
  NULL,                                     // input buffer (not used)
  0,                                        // input buffer size (not used)
  lpOutBuffer,                              // output buffer: property list
  cbOutBufferSize,                          // output buffer size (bytes)
  lpcbBytesReturned                         // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpOutBuffer
On a successful return, points to a property list containing the specified group's read-only group private properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for groups.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_QUERY_DELETE

The CLUSCTL_GROUP_QUERY_DELETE control code is reserved for future use.


CLUSCTL_GROUP_SET_COMMON_PROPERTIES

The CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code is used to update the read-write common properties for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                               // group handle
  hHostNode,                            // optional node handle
  CLUSCTL_GROUP_SET_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                           // input buffer: property list
  cbInBufferSize,                       // input buffer size (bytes)
  NULL,                                 // output buffer (not used)
  0,                                    // output buffer size (not used)
  NULL                                  // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpInBuffer
Pass a pointer to a property list containing new values for one or more read-write common group properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code is used to update the read-write private properties for a group. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                // group handle
  hHostNode,                             // optional node handle
  CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                            // input buffer: property list
  cbInBufferSize,                        // input buffer size (bytes)
  NULL,                                  // output buffer (not used)
  0,                                     // output buffer size (not used)
  NULL                                   // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write group private properties. Properties that do not already exist will be created.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for groups. However, you can use the CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code to define private properties for a group.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_UNKNOWN

The CLUSCTL_GROUP_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                 // group handle
  hHostNode,              // optional node handle
  CLUSCTL_GROUP_UNKNOWN,  // this control code
  NULL,                   // input buffer (not used)
  0,                      // input buffer size (not used)
  NULL,                   // output buffer (not used)
  0,                      // output buffer size (not used)
  NULL                    // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.

Remarks

ClusterGroupControl always returns ERROR_SUCCESS when processing the CLUSCTL_GROUP_UNKNOWN control code.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid group property names and values and that the list is properly formatted. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                    // group handle
  hHostNode,                                 // optional node handle
  CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                // input buffer: property list
  cbInBufferSize,                            // input buffer size (bytes)
  NULL,                                      // output buffer (not used)
  0,                                         // output buffer size (not used)
  NULL                                       // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write common group properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES control code verifies that a group private property list is properly formatted. Applications use this control code as a ClusterGroupControl parameter.

Control Code Function Syntax

dwReturn =
ClusterGroupControl(
  hGroup,                                     // group handle
  hHostNode,                                  // optional node handle
  CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                                 // input buffer: property list
  cbInBufferSize,                             // input buffer size (bytes)
  NULL,                                       // output buffer (not used)
  0,                                          // output buffer size (not used)
  NULL                                        // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterGroupControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write group private properties.
dwReturn
ClusterGroupControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for groups.

Do not use any group control codes in any resource DLL entry point function. Group control codes can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_GROUP
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterGroupControl


Network Control Codes

The Server Cluster API defines the following external control codes for networks. There are no internal control codes defined for networks.

  • CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_GET_CHARACTERISTICS
  • CLUSCTL_NETWORK_GET_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_NETWORK_GET_FLAGS
  • CLUSCTL_NETWORK_GET_NAME
  • CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_SET_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES
  • CLUSCTL_NETWORK_UNKNOWN
  • CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES


CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES

The CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write common network property names. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                // network handle
  hHostNode,                               // optional host node
  CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES,  // this control code
  NULL,                                    // input buffer (not used)
  0,                                       // input buffer size (not used)
  lpOutBuffer,                             // output buffer: array of strings
  cbOutBufferSize,                         // allocated buffer size (bytes)
  lpcbBytesReturned                        // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, lpOutBuffer contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write common network property.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES control code only returns property names, not property values. To retrieve values for common network properties, use CLUSCTL_NETWORK_GET_COMMON_PROPERTIES and CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NETWORK_GET_COMMON_PROPERTIES, CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES, ClusterNetworkControl


CLUSCTL_NETWORK_GET_COMMON_PROPERTY_FMTS

property list Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.


CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES control code retrieves a list of private property names for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                 // network handle
  hHostNode,                                // optional host node
  CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES,  // this control code
  NULL,                                     // input buffer (not used)
  0,                                        // input buffer size (not used)
  lpOutBuffer,                              // output buffer: array of strings
  cbOutBufferSize,                          // allocated buffer size (bytes)
  lpcbBytesReturned                         // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, lpOutBuffer contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write network private property.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for networks.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_GET_CHARACTERISTICS

The CLUSCTL_NETWORK_GET_CHARACTERISTICS control code retrieves the intrinsic characteristics of a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                             // network handle
  hHostNode,                            // optional host node
  CLUSCTL_NETWORK_GET_CHARACTERISTICS,  // this control code
  NULL,                                 // input buffer (not used)
  0,                                    // input buffer size (not used)
  lpOutBuffer,                          // output buffer: DWORD bitmask
  cbOutBufferSize,                      // allocated buffer size (bytes)
  lpcbBytesReturned                     // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

hNetwork
Network handle.
hHostNode
Optional node handle. Can be NULL.
lpOutBuffer
On a successful return, contains a DWORD bitmask describing the network's characteristics. Only one bitmask is currently defined:
CLUS_CHAR_UNKNOWN
Network has no known characteristics.
lpOutBufferSize
Allocated size (in bytes) of the output buffer.
lpcbBytesReturned
Returns the actual size (in bytes) of the data resulting from the operation.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_CHARACTERISTICS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CHARACTERISTICS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_GET_COMMON_PROPERTIES

The CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code retrieves the read-write common properties for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                               // network handle
  hHostNode,                              // optional host node
  CLUSCTL_NETWORK_GET_COMMON_PROPERTIES,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // allocated buffer size (bytes)
  lpcbBytesReturned                       // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network's read-write common network properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl, Description


CLUSCTL_NETWORK_GET_FLAGS

The CLUSCTL_NETWORK_GET_FLAGS control code retrieves the flags that are set for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                   // network handle
  hHostNode,                  // optional host node
  CLUSCTL_NETWORK_GET_FLAGS,  // this control code
  NULL,                       // input buffer (not used)
  0,                          // input buffer size (not used)
  lpOutBuffer,                // output buffer: array of strings
  cbOutBufferSize,            // allocated buffer size (bytes)
  lpcbBytesReturned           // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing flags set for the network. No flags are currently defined for networks.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_FLAGS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FLAGS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_GET_ID

The CLUSCTL_NETWORK_GET_ID control code retrieves the cluster database subkey identifier for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                // network handle
  hHostNode,               // optional host node
  CLUSCTL_NETWORK_GET_ID,  // this control code
  NULL,                    // input buffer (not used)
  0,                       // input buffer size (not used)
  lpOutBuffer,             // output buffer: string (GUID)
  cbOutBufferSize,         // allocated buffer size (bytes)
  lpcbBytesReturned        // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, points to a NULL-terminated Unicode string containing the GUID that identifies the network.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The GUID string returned in lpOutBuffer resides in the cluster database under HKEY_LOCAL_MACHINE\Cluster\Networks.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_ID as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_ID
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_GET_NAME

The CLUSCTL_NETWORK_GET_NAME control code retrieves the name of a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                  // network handle
  hHostNode,                 // optional host node
  CLUSCTL_NETWORK_GET_NAME,  // this control code
  NULL,                      // input buffer (not used)
  0,                         // input buffer size (not used)
  lpOutBuffer,               // output buffer: string
  cbOutBufferSize,           // allocated buffer size (bytes)
  lpcbBytesReturned          // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, points to a NULL-terminated Unicode string containing the name of the network.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The name of a network is stored in the Name property. To retrieve the Name property along with the other read-only network common properties, use the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NAME
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES, ClusterNetworkControl, Name


CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES control code retrieves the read-write private properties for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                // network handle
  hHostNode,                               // optional host node
  CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES,  // this control code
  NULL,                                    // input buffer (not used)
  0,                                       // input buffer size (not used)
  lpOutBuffer,                             // o1utput buffer: property list
  cbOutBufferSize,                         // allocated buffer size (bytes)
  lpcbBytesReturned                        // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network's read-write network private properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for networks.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_GET_PRIVATE_PROPERTY_FMTS

ClusterNetworkControl Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.


CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES

The CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                  // network handle
  hHostNode,                                 // optional host node
  CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES,  // this control code
  NULL,                                      // input buffer (not used)
  0,                                         // input buffer size (not used)
  lpOutBuffer,                               // output buffer: array of strings
  cbOutBufferSize,                           // allocated buffer size (bytes)
  lpcbBytesReturned                          // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network's read-only common network properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl, Name


CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                   // network handle
  hHostNode,                                  // optional host node
  CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES,  // this control code
  NULL,                                       // input buffer (not used)
  0,                                          // input buffer size (not used)
  lpOutBuffer,                                // output buffer: array of strings
  cbOutBufferSize,                            // allocated buffer size (bytes)
  lpcbBytesReturned                           // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network's read-only network private properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for networks.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_SET_COMMON_PROPERTIES

The CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code is used to update the read-write common properties for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                               // network handle
  hHostNode,                              // optional host node
  CLUSCTL_NETWORK_SET_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                             // input buffer: property list
  cbInBufferSize,                         // allocated buffer size (bytes)
  NULL,                                   // output buffer (not used)
  0,                                      // output buffer size (not used)
  NULL                                    // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write common network properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code is used to update the read-write private properties for a network. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                // network handle
  hHostNode,                               // optional host node
  CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                              // input buffer: property list
  cbInBufferSize,                          // allocated buffer size (bytes)
  NULL,                                    // output buffer (not used)
  0,                                       // output buffer size (not used)
  NULL                                     // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write network private properties. Properties in the list that do not already exist will be created.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for networks. You can use the CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code to define private properties for a network.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_UNKNOWN

The CLUSCTL_NETWORK_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                 // network handle
  hHostNode,                // optional host node
  CLUSCTL_NETWORK_UNKNOWN,  // this control code
  NULL,                     // input buffer (not used)
  0,                        // input buffer size (not used)
  NULL,                     // output buffer (not used)
  0,                        // output buffer size (not used)
  NULL                      // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.

Remarks

ClusterNetworkControl always returns ERROR_SUCCESS when processing the CLUSCTL_NETWORK_UNKNOWN control code.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid network property names and values and that the list is properly formatted. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                    // network handle
  hHostNode,                                   // optional host node
  CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                  // input buffer: property list
  cbInBufferSize,                              // allocated buffer size (bytes)
  NULL,                                        // output buffer (not used)
  0,                                           // output buffer size (not used)
  NULL                                         // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write common network properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

The CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES control code validates only read-write network common properties. Property lists containing private or read-only properties cause validation to fail.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES control code verifies that a property list is properly formatted. Applications use this control code as a ClusterNetworkControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetworkControl(
  hNetwork,                                     // network handle
  hHostNode,                                    // optional host node
  CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                                   // input buffer: property list
  cbInBufferSize,                               // allocated buffer size (bytes)
  NULL,                                         // output buffer (not used)
  0,                                            // output buffer size (not used)
  NULL                                          // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetworkControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write network private properties.
dwReturn
ClusterNetworkControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for networks.

Clusapi.h defines the 32 bits of CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETWORK
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetworkControl


Network Interface Control Codes

The Server Cluster API defines the following external control codes for network interfaces. There are no internal control codes defined for network interfaces.

  • CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS
  • CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_NETINTERFACE_GET_FLAGS
  • CLUSCTL_NETINTERFACE_GET_NAME
  • CLUSCTL_NETINTERFACE_GET_NETWORK
  • CLUSCTL_NETINTERFACE_GET_NODE
  • CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_NETINTERFACE_UNKNOWN
  • CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES


CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write network interface common property names. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                // network interface handle
  hHostNode,                                    // optional host node
  CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES,  // this control code
  NULL,                                         // input buffer (not used)
  0,                                            // input buffer size (not used)
  lpOutBuffer,                                  // output buffer: array of strings
  cbOutBufferSize,                              // allocated buffer size (bytes)
  lpcbBytesReturned                             // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write network interface common property.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES control code returns only property names, not property values. To retrieve values for common network interface properties, use CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES and CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES, CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES, ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES control code retrieves a list of the network interface private properties. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                 // network interface handle
  hHostNode,                                     // optional host node
  CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES,  // this control code
  NULL,                                          // input buffer (not used)
  0,                                             // input buffer size (not used)
  lpOutBuffer,                                   // output buffer: array of strings
  cbOutBufferSize,                               // allocated buffer size (bytes)
  lpcbBytesReturned                              // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write private network interface property.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters define no private properties for network interfaces.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS

The CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS control code retrieves the intrinsic characteristics of a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                             // network interface handle
  hHostNode,                                 // optional host node
  CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS,  // this control code
  NULL,                                      // input buffer (not used)
  0,                                         // input buffer size (not used)
  lpOutBuffer,                               // output buffer: DWORD bitmask
  cbOutBufferSize,                           // allocated buffer size (bytes)
  lpcbBytesReturned                          // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing the network interface's characteristics. Only one bitmask is currently defined:
CLUS_CHAR_UNKNOWN
Network Interface has no known characteristics.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CHARACTERISTICS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES control code retrieves the read-write common properties for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                               // network interface handle
  hHostNode,                                   // optional host node
  CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES,  // this control code
  NULL,                                        // input buffer (not used)
  0,                                           // input buffer size (not used)
  lpOutBuffer,                                 // output buffer: property list
  cbOutBufferSize,                             // allocated buffer size (bytes)
  lpcbBytesReturned                            // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network interface's read-write common network interface properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl, Description Property for Network Interfaces


CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTY_FMTS

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.


CLUSCTL_NETINTERFACE_GET_FLAGS

The CLUSCTL_NETINTERFACE_GET_FLAGS control code retrieves the flags that are set for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                   // network interface handle
  hHostNode,                       // optional host node
  CLUSCTL_NETINTERFACE_GET_FLAGS,  // this control code
  NULL,                            // input buffer (not used)
  0,                               // input buffer size (not used)
  lpOutBuffer,                     // output buffer: DWORD bitmask
  cbOutBufferSize,                 // allocated buffer size (bytes)
  lpcbBytesReturned                // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing flags set for the network interface.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters define no flags for network interfaces.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_FLAGS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FLAGS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_ID

The CLUSCTL_NETINTERFACE_GET_ID control code retrieves the cluster database subkey identifier for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                // network interface handle
  hHostNode,                    // optional host node
  CLUSCTL_NETINTERFACE_GET_ID,  // this control code
  NULL,                         // input buffer (not used)
  0,                            // input buffer size (not used)
  lpOutBuffer,                  // output buffer: string (GUID)
  cbOutBufferSize,              // allocated buffer size (bytes)
  lpcbBytesReturned             // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the GUID that identifies the network interface.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The GUID string returned in lpOutBuffer resides in the cluster database under HClusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_ID as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_ID
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_NAME

The CLUSCTL_NETINTERFACE_GET_NAME control code retrieves the name of a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                  // network interface handle
  hHostNode,                      // optional host node
  CLUSCTL_NETINTERFACE_GET_NAME,  // this control code
  NULL,                           // input buffer (not used)
  0,                              // input buffer size (not used)
  lpOutBuffer,                    // output buffer: string
  cbOutBufferSize,                // allocated buffer size (bytes)
  lpcbBytesReturned               // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the name of the network interface.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The name of a network interface is stored in the Name property. To retrieve the Name property along with the other read-only network interface common properties, use the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NAME
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES, ClusterNetInterfaceControl, Name


CLUSCTL_NETINTERFACE_GET_NETWORK

The CLUSCTL_NETINTERFACE_GET_NETWORK control code retrieves the name of the network to which a network interface is connected. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                     // network interface handle
  hHostNode,                         // optional host node
  CLUSCTL_NETINTERFACE_GET_NETWORK,  // this control code
  NULL,                              // input buffer (not used)
  0,                                 // input buffer size (not used)
  lpOutBuffer,                       // output buffer: string
  cbOutBufferSize,                   // allocated buffer size (bytes)
  lpcbBytesReturned                // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the name of the network interface.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The network name is stored in the network interface Network property. To retrieve the Network property along with the other read-only network interface common properties, use the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_NETWORK as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NETWORK
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES, ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_NODE

The CLUSCTL_NETINTERFACE_GET_NODE control code retrieves the name of the node in which a network interface is installed. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                  // network interface handle
  hHostNode,                      // optional host node
  CLUSCTL_NETINTERFACE_GET_NODE,  // this control code
  NULL,                           // input buffer (not used)
  0,                              // input buffer size (not used)
  lpOutBuffer,                    // output buffer: array of strings
  cbOutBufferSize,                // allocated buffer size (bytes)
  lpcbBytesReturned               // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the name of the network interface.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The node name is stored in the network interface Node property. To retrieve the Node property along with the other read-only network interface common properties, use the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_NODE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NODE
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES, ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES control code retrieves the read-write private properties for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                // network interface handle
  hHostNode,                                    // optional host node
  CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES,  // this control code
  NULL,                                         // input buffer (not used)
  0,                                            // input buffer size (not used)
  lpOutBuffer,                                  // output buffer: property list
  cbOutBufferSize,                              // allocated buffer size (bytes)
  lpcbBytesReturned                             // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network interface's read-write network interface private properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define private properties for network interfaces.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTY_FMTS

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.


CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                  // network interface handle
  hHostNode,                                      // optional host node
  CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES,  // this control code
  NULL,                                           // input buffer (not used)
  0,                                              // input buffer size (not used)
  lpOutBuffer,                                    // output buffer: property list
  cbOutBufferSize,                                // allocated buffer size (bytes)
  lpcbBytesReturned                               // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network interface's ead-only network interface common properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl, Name


CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                   // network interface handle
  hHostNode,                                       // optional host node
  CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES,  // this control code
  NULL,                                            // input buffer (not used)
  0,                                               // input buffer size (not used)
  lpOutBuffer,                                     // output buffer: property list
  cbOutBufferSize,                                 // allocated buffer size (bytes)
  lpcbBytesReturned                                // actual size of resulting data (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpOutBuffer
On a successful return, points to a property list containing the specified network interface's read-only private properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define private properties for network interfaces.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code is used to update the read-write common properties for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                               // network interface handle
  hHostNode,                                   // optional host node
  CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                  // input buffer: property list
  cbInBufferSize,                              // allocated buffer size (bytes)
  NULL,                                        // output buffer (not used)
  0,                                           // output buffer size (not used)
  NULL                                         // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpInBuffer
Pass a pointer to a property list containing new values for one or more read-write common network interface properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

Description Property for Network Interfaces


CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code is used to update the read-write private properties for a network interface. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                // network interface handle
  hHostNode,                                    // optional host node
  CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                                   // input buffer: property list
  cbInBufferSize,                               // allocated buffer size (bytes)
  NULL,                                         // output buffer (not used)
  0,                                            // output buffer size (not used)
  NULL                                          // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write network interface private properties. Any properties that do not already exist will be created.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for network interfaces. You can use the CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code to define private properties for a network interface.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_UNKNOWN

The CLUSCTL_NETINTERFACE_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                 // network interface handle
  hHostNode,                     // optional host node
  CLUSCTL_NETINTERFACE_UNKNOWN,  // this control code
  NULL,                          // input buffer (not used)
  0,                             // input buffer size (not used)
  NULL,                          // output buffer (not used)
  0,                             // output buffer size (not used)
  NULL                           // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.

Remarks

ClusterNetInterfaceControl always returns ERROR_SUCCESS in response to CLUSCTL_NETINTERFACE_UNKNOWN.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid network interface property names and values and that the list is properly formatted. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                    // network interface handle
  hHostNode,                                        // optional host node
  CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                       // input buffer: property list
  cbInBufferSize,                                   // allocated buffer size (bytes)
  NULL,                                             // output buffer (not used)
  0,                                                // output buffer size (not used)
  NULL                                              // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write network interface common properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

The CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES control code validates only read-write network interface common properties. Property lists containing private or read-only properties cause validation to fail. For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES control code verifies that a property list is properly formatted. Applications use this control code as a ClusterNetInterfaceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNetInterfaceControl(
  hNetInterface,                                     // network interface handle
  hHostNode,                                         // optional host node
  CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES,  // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL                                               // actual size of resulting data (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNetInterfaceControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write network interface private properties.
dwReturn
ClusterNetInterfaceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for network interfaces.

Clusapi.h defines the 32 bits of CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NETINTERFACE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNetInterfaceControl


Node Control Codes

The Server Cluster API defines the following external control codes for nodes. There are no internal control codes defined for nodes.

  • CLUSCTL_NODE_ENUM_COMMON_PROPERTIES
  • CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_GET_CHARACTERISTICS
  • CLUSCTL_NODE_GET_COMMON_PROPERTIES
  • CLUSCTL_NODE_GET_COMMON_PROPERTY_FMTS
  • CLUSCTL_NODE_GET_FLAGS
  • CLUSCTL_NODE_GET_NAME
  • CLUSCTL_NODE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_GET_PRIVATE_PROPERTY_FMTS
  • CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_SET_COMMON_PROPERTIES
  • CLUSCTL_NODE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_NODE_UNKNOWN
  • CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES
  • CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES


CLUSCTL_NODE_ENUM_COMMON_PROPERTIES

The CLUSCTL_NODE_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write common property names for nodes. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_ENUM_COMMON_PROPERTIES,               // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write common node property.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The CLUSCTL_NODE_ENUM_COMMON_PROPERTIES control code returns only property names, not property values. To retrieve values for common node properties, use CLUSCTL_NODE_GET_COMMON_PROPERTIES and CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NODE_GET_COMMON_PROPERTIES, CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES, ClusterNodeControl


CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES control code retrieves a list of node private property names. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES,              // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write node private property.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for nodes.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_CHARACTERISTICS

The CLUSCTL_NODE_GET_CHARACTERISTICS control code retrieves the intrinsic characteristics of a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_CHARACTERISTICS,                  // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing the node's characteristics. Only one bitmask is currently defined:
CLUS_CHAR_UNKNOWN
Node has no known characteristics.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_CHARACTERISTICS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CHARACTERISTICS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_COMMON_PROPERTIES

The CLUSCTL_NODE_GET_COMMON_PROPERTIES control code retrieves the read-write common properties for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_COMMON_PROPERTIES,                // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, points to a property list containing the specified node's read-write common node properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_COMMON_PROPERTY_FMTS

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.


CLUSCTL_NODE_GET_FLAGS

The CLUSCTL_NODE_GET_FLAGS control code retrieves the flags that are set for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_FLAGS,                            // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing flags set for the node. No flags are currently defined for nodes.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_FLAGS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FLAGS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_ID

The CLUSCTL_NODE_GET_ID control code retrieves the unique cluster identifier for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_ID,                               // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: string
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the number that identifies the node.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The number returned in lpOutBuffer resides in the cluster database under HKEY_LOCAL_MACHINE\Cluster\Nodes.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_ID as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_ID
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_NAME

The CLUSCTL_NODE_GET_NAME control code retrieves the name of a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_NAME,                             // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: string
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the name of the node.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

The name of a node is stored in the NodeName property. To retrieve the NodeName property along with the other read-only node common properties, use the CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NAME
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES, ClusterNodeControl, NodeName Property for Nodes


CLUSCTL_NODE_GET_PRIVATE_PROPERTIES

The CLUSCTL_NODE_GET_PRIVATE_PROPERTIES control code retrieves the read-write private properties for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_PRIVATE_PROPERTIES,               // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, points to a property list containing the specified node's read-write node private properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for nodes.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_PRIVATE_PROPERTY_FMTS

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.


CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES,             // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, points to a property list containing the specified node's read-only common node properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES,            // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpOutBuffer
On a successful return, points to a property list containing the specified node's read-only node private properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Remarks

By default, server clusters do not define any private properties for nodes.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_SET_COMMON_PROPERTIES

The CLUSCTL_NODE_SET_COMMON_PROPERTIES control code is used to update the read-write common properties for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_SET_COMMON_PROPERTIES,                // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpInBuffer
Pass a pointer to a property list containing new values for one or more read-write common node properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_SET_PRIVATE_PROPERTIES

The CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code is used to update the read-write private properties for a node. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_SET_PRIVATE_PROPERTIES,               // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpInBuffer
Pass a pointer to a property list containing new values for one or more read-write node private properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for nodes. You can use the CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code to define private properties for a node.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_UNKNOWN

The CLUSCTL_NODE_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_UNKNOWN,                              // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

dwReturn
ClusterNodeControl always returns ERROR_SUCCESS in response to this control code.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_NODE_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid node property names and values and that the list is properly formatted. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES,           // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write common node properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

The CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES control code only validates read-write node common properties. Property lists containing private or read-only properties cause validation to fail.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES control code verifies that a property list is properly formatted. Applications use this control code as a ClusterNodeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterNodeControl(
  hNode,                                             // node handle
  hHostNode,                                         // optional host node
  CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES,          // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterNodeControl.

lpInBuffer
Pass a pointer to a property list containing one or more read-write node private properties.
dwReturn
ClusterNodeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Remarks

By default, server clusters do not define any private properties for nodes.

Clusapi.h defines the 32 bits of CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_NODE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterNodeControl


Resource Control Codes

Resource control codes are used in the following ways:

  • Applications use external control codes as ClusterResourceControl parameters to initiate operations on a resource.
  • Resource DLLs receive both external and internal control codes as parameters to the ResourceControl entry point function. A resource DLL may implement special procedures in response to a control code, depending on the control code and the needs of the resources it manages.

To support both application and DLL developers, each resource contol code presents information on how to use the code in a control code function and how to support it in a resource DLL.

Refer to the following sections:

External Resource Control Codes

Internal Resource Control Codes


External Resource Control Codes

The following table lists all of the external control codes for resources.

Control code | DLL support
CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT | Use Default
CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT | Optional
CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT | Use Default
CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT | Optional
CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_GET_CHARACTERISTICS | Optional
CLUSCTL_RESOURCE_GET_CLASS_INFO | Optional
CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS | Use default.
CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS | Optional
CLUSCTL_RESOURCE_GET_FLAGS | Optional
CLUSCTL_RESOURCE_GET_NAME | Optional
CLUSCTL_RESOURCE_GET_NETWORK_NAME | Optional
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS | Required
CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS | Conditional
CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES | Optional
CLUSCTL_RESOURCE_GET_RESOURCE_TYPE | Optional
CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES | Required.
CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO | Conditional
CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID | Conditional
CLUSCTL_RESOURCE_UNKNOWN | Conditional
CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES | Required

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT

The CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT control code is used to add a cryptographic key container to the list of keys that are replicated for a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT,            // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string that specifies the Cryptographic Service Provider (CSP) key container to be replicated. The CSP key container must first be created with the CryptoAPI and the keys in the container must be exportable. The string must specify the CSP provider type, provider name, and key container name using the following syntax:

Type\Name\Key

Note that the values must be separated by a '\'. The provider type should specify the decimal value of the type, not the constant that represents the value. For example, instead of "PROV_RSA_FULL" use "1". The provider name is optional, if omitted, the default CSP provider name associated with the specified provider type will be used.

dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
NTE_BAD_KEY
The keys in the specified container are not exportable. For more information, see CryptGenKey.
NTE_BAD_KEYSET
The specified key container does not exist. For more information, see CryptAcquireContext.
Win32 Error
The operation was not successful.

Resource DLL Support

The CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

For more information on the following points, see the CryptoAPI_Reference.

  • A key container is given a name when it is created using CryptAcquireContext with dwFlags set to CRYPT_NEWKEYSET.
  • Once a key container has been created, the key pairs for that key container must be created using CryptGenKey with the dwFlags parameter set to CRYPT_EXPORTABLE. Note that some CSPs do not allow key exports from their key containers. If a key is not exportable then the ClusterResourceControl call will fail with an NTE_BAD_KEY error.
  • C programs that create key sets need to be compiled and linked by using wincrypt.h and advapi32.lib.

For more information on cluster programming, refer to the following sections:

  • For information on working with control codes, see Using Control Codes.
  • For information on cluster registry checkpointing, see Cluster Database.
  • Cluster-aware applications need to be compiled and linked using clusapi.h, clusapi.lib, resource.h, and resutils.lib. For an example of cluster-related compiler directives, see ClusDocEx.h.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ADD_CRYPTO_CHECKPOINT
Access code | 0-1 | CLUS_ACCESS_WRITE

Code Example

//
// The following line creates a string used to checkpoint a
// key container with the following attributes:
//     provider type  = 1 (PROV_RSA_FULL)
//     provider name  = Microsoft Base Provider
//     container name = MyKey
// Note the use of double backslashes "\\".
//
WCHAR szCryptoCheckpoint[] = L"1\\Microsoft Base Cryptographic Provider v1.0\\MyKey"

//
// The following line creates a string used to checkpoint a
// key container with the following attributes:
//     provider type  = 1 (PROV_RSA_FULL)
//     provider name  = not specified; default will be used
//     container name = MyKey
// Note the use of double backslashes "\\".
//
WCHAR szCryptoCheckpoint[] = L"1\\\\MyKey"

DWORD dwResult = ClusterResourceControl(
                     hRes,
                     NULL,
                     CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT
                     (LPVOID) szCryptoCheckpoint
                     ( lstrlenW( szCryptoCheckpoint ) + 1 ) * sizeof( WCHAR ),
                     NULL,
                     0,
                     NULL );

if( dwResult != ERROR_SUCCESS )
{
    // Handle error.
}

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl, CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT, CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS


CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT

The CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code is used to add a registry tree to the list of registry trees that are replicated for a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT,          // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the registry key name at the root of the subtree that should be replicated for the resource. This is a key name that is relative to HKEY_LOCAL_MACHINE, such as "Software\Microsoft\My Application". Do not use a leading backslash character ("\") in the relative path or the call will fail.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_ALREADY_EXISTS
The specified key is already being checkpointed.
Win32 Error
The operation was not successful.

Resource DLL Support

The CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ADD_REGISTRY_CHECKPOINT
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT, CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT

The CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT control code is used to remove a cryptographic key container from the list of keys that are being replicated for a resource.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                    // resource handle
  hHostNode,                                    // optional node handle
  CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT,    // this control code
  lpInBuffer,                                   // input buffer: string
  cbInBufferSize,                               // input buffer size (bytes)
  NULL,                                         // output buffer (not used)
  0,                                            // output buffer size (not used)
  NULL                                          // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string that specifies the cryptographic service provider type, provider name, and key container name of a key that was previously checkpointed with the CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT control code.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
Win32 Error
The operation was not successful.

Resource DLL Support

The CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

For more information on the CryptoAPI, see the CryptoAPI_Reference.

For more information on cluster programming, refer to the following sections:

  • For information on working with control codes, see Using Control Codes.
  • For information on cluster registry checkpointing, see Cluster Database.
  • Cluster-aware applications need to be compiled and linked using clusapi.h, clusapi.lib, resource.h, and resutils.lib. For an example of cluster-related compiler directives, see ClusDocEx.h.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_DELETE_CRYPTO_CHECKPOINT
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl, CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT, CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS


CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT

The CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT control code is used to remove a registry tree from the list of registry trees that are being replicated for a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                    // resource handle
  hHostNode,                                    // optional node handle
  CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT,  // this control code
  lpInBuffer,                                   // input buffer: string
  cbInBufferSize,                               // input buffer size (bytes)
  NULL,                                         // output buffer (not used)
  0,                                            // output buffer size (not used)
  NULL                                          // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the registry key name at the root of the subtree that should be replicated for the resource. This is a key name that is relative to HKEY_LOCAL_MACHINE, such as "Software\Microsoft\My Application". Do not use a leading backslash character ("\") in the relative path or the call will fail.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_FILE_NOT_FOUND
The specified key is not currently being checkpointed.
Win32 Error
The operation was not successful.

Resource DLL Support

The CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_DELETE_REGISTRY_CHECKPOINT
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write resource common property names. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES,           // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES,           // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write common resource property.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
Win32 Error
The operation was not successful.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor build the list of property names.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

The CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES control code returns only property names, not property values. To retrieve values for common resource properties, use CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES and CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES. For more information, see Getting Information with Control Codes.

Do not use the CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES, CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES control code retrieves a list of the read-write private and read-only resource properties. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES,          // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES,          // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read-write private resource property.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code in addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES control code by returning the names of the resource's private properties in the OutBuffer parameter.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

The CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES control code returns only property names, not property values. To retrieve values for common resource properties, use CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES and CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES.

For more information, see Getting Information with Control Codes.

Do not use the CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES, CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_CHARACTERISTICS

The CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code retrieves the intrinsic characteristics of a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_CHARACTERISTICS,              // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_CHARACTERISTICS,              // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing the resource's characteristics as any combination of the following values.
Value | Description
CLUS_CHAR_UNKNOWN | The resource has no known characteristics.
CLUS_CHAR_QUORUM | The resource can be selected as the quorum resource for the cluster.
CLUS_CHAR_DELETE_REQUIRES_ALL_NODES | The resource cannot be deleted unless all nodes are active.
CLUS_CHAR_LOCAL_QUORUM | The resource can be selected as the quorum resource in clusters configured using the -localquorum switch.
CLUS_CHAR_LOCAL_QUORUM_DEBUG | Reserved for future use.

dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. If you support CLUSCTL_RESOURCE_GET_CHARACTERISTICS, use the output buffer to specify a value that accurately describes the resource.

  • If the resource is quorum-capable and you want users and applications to be able to select it as the quorum resource for the cluster, specify CLUS_CHAR_QUORUM. Note that if a resource that is not quorum-capable is selected as the quorum resource, the cluster becomes unusable.
  • If you want to prevent the resource from being deleted unless all nodes are active, specify CLUS_CHAR_DELETE_REQUIRES_ALL_NODES. Attempts to delete the resource will fail and return ERROR_HOST_NODE_NOT_AVAILABLE unless all nodes are active.

If you do not support this control code, return ERROR_INVALID_FUNCTION to allow the following default processing to occur:

  • If your resource DLL has Arbitrate and Release entry points, the Resource Monitor sets the CLUS_CHAR_QUORUM characteristic for the resource.
  • If your resource DLL does not have Arbitrate and Release entry points, the Resource Monitor clears the CLUS_CHAR_QUORUM characteristic for the resource.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_CHARACTERISTICS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CHARACTERISTICS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_CLASS_INFO

The CLUSCTL_RESOURCE_GET_CLASS_INFO control code retrieves the class and subclass of a resource. A resource class identifies resources of similar capability. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

A resource DLL receives the CLUSCTL_RESOURCE_GET_CLASS_INFO control code when an application requests the resource class of a resource.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_CLASS_INFO,                   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: CLUS_RESOURCE_CLASS_INFO structure
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_CLASS_INFO,                   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: CLUS_RESOURCE_CLASS_INFO structure
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a CLUS_RESOURCE_CLASS_INFO structure containing resource class information for the resource.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. If you do not support it, return ERROR_INVALID_FUNCTION to let the Resource Monitor provide default handling. The Resource Monitor will specify CLUS_RESCLASS_UNKNOWN as the class and zero as the subclass.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_GET_CLASS_INFO control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_CLASS_INFO as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CLASS_INFO
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_GET_CLASS_INFO, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code retrieves the read-write common properties for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES,            // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES,            // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a property list containing the resource's read-write common resource properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of common resource properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETRWCPROPS_CPP
#define _CLUSDOCEX_RESGETRWCPROPS_CPP

LPVOID
ClusDocEx_ResGetRWCProperties

(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
)
// ====================================================================
//
// Description:
//
//     Retrieves the read-write common properties of a resource
//     using CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//    OUT LPDWORD  lpcbDataSize   Returns the byte size of the
//                                resulting data.
//
// Return Value:
//
//    If successful, returns a property list containing the
//    read-write common properties of the resource identified
//    by hRes.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    lpOutBuffer     Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    LPVOID lpOutBuffer   = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES;

    lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      lpcbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbDataSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
            );

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbDataSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;  // Call LocalFree to release the memory.

//
//  The calling function will need to parse the property list to
//  extract the property names and values.
//
//  See "Parsing Property Lists" for procedures and an example.
//

}

#endif

// end ClusDocEx_ResGetRWCProperties

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl


CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS

The CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS control code returns a property list describing the format of each resource common property. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each resource common property.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of common resource properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

The property list returned by CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS contains one entry for each resource common property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterResourceControl


CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS

The CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS control code is used to retrieve a list of all the cryptographic key checkpoints set for a resource.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS,           // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains a cryptographic service provider (CSP) type, provider name, and key container name in the following format:

Type\Name\Key

Note the values are separated by a '\'. The provider type specifies the decimal value of the type, not the constant that represents the value. For example, "1" instead of "PROV_RSA_FULL". The provider name may be omitted, indicating that the default CSP name associated with the specified provider type should be used.

dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Resource DLL Support

The CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

For more information on the CryptoAPI, see the CryptoAPI_Reference.

For more information on cluster programming, refer to the following sections:

  • For information on working with control codes, see Using Control Codes.
  • For information on cluster registry checkpointing, see Cluster Database.
  • Cluster-aware applications need to be compiled and linked using clusapi.h, clusapi.lib, resource.h, and resutils.lib. For an example of cluster-related compiler directives, see ClusDocEx.h.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_CRYPTO_CHECKPOINTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CRYPTO_CHECKPOINT
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl, CLUSCTL_RESOURCE_ADD_CRYPTO_CHECKPOINT, CLUSCTL_RESOURCE_DELETE_CRYPTO_CHECKPOINT


CLUSCTL_RESOURCE_GET_FLAGS

The CLUSCTL_RESOURCE_GET_FLAGS control code retrieves the flags that are set for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_FLAGS,                        // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_FLAGS,                        // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing flags set for the resource, as follows.
Flag | Description
0 | No flags are defined for the resource.
CLUS_FLAG_CORE | Indicates that the resource is essential to the cluster and cannot be deleted. Included in this group of essential resources are the cluster IP Address, the cluster Network Name, and the quorum resource
Other nonzero | Indicates a user-defined flag created by a third party developer for a custom resource type.

dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. Support CLUSCTL_RESOURCE_GET_FLAGS only if you define flags specific to the resources supported by your DLL. The Server Cluster API reserves only the lower 16 bits of the DWORD bitmask. Use the upper 16 bits to define your own resource-specific flags. Be sure to document or otherwise communicate what your flags do and how they should be used.

If you do not define resource-specific flags, return ERROR_INVALID_FUNCTION to let the Resource Monitor handle the operation. The Resource Monitor will read the Flags value from the resource key in the cluster database.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_GET_FLAGS control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_FLAGS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FLAGS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_ID

The CLUSCTL_RESOURCE_GET_ID control code retrieves the cluster database subkey identifier for a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_ID,                           // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: string (GUID)
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the GUID that identifies the resource.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Resource DLL Support

The CLUSCTL_RESOURCE_GET_ID control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

The GUID string returned in lpOutBuffer resides in the cluster database under HKEY_LOCAL_MACHINE\Cluster\Resources.

Do not use the CLUSCTL_RESOURCE_GET_ID control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_ID as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_ID
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_LOADBAL_PROCESS_LIST

The CLUSCTL_RESOURCE_GET_LOADBAL_PROCESS_LIST control code is reserved for future use.


CLUSCTL_RESOURCE_GET_NAME

The CLUSCTL_RESOURCE_GET_NAME control code retrieves the name of a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_NAME,                         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: string
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the name of the resource.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Resource DLL Support

The CLUSCTL_RESOURCE_GET_NAME control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

The name of a resource is stored in the Name property. To retrieve the Name property along with the other read-only resource common properties, use the CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code.

Do not use the CLUSCTL_RESOURCE_GET_NAME control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NAME
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETNAME_CPP
#define _CLUSDOCEX_RESGETNAME_CPP

LPWSTR
ClusDocEx_ResGetName
(
    IN HRESOURCE hRes,
    IN HNODE     hNode
)
// ====================================================================
//
// Description:
//
//     Retrieves the name of a resource
//     using CLUSCTL_RESOURCE_GET_NAME.
//
//
//     Call LocalFree on the returned pointer to free the memory
//
//
// Arguments:
//
//     IN HRESOURCE hRes       Handle to the resource to affect.
//
//     IN HNODE     hNode      Optional handle to the node that
//                             owns the resource.
//
// Return Value:
//
//     If successful, the name of the resource.
//     If not, a NULL pointer; call GetLastError() for details.
//
//
// Local Variables:
//
//     dwResult      Captures return values.
//
//     cbBufSize     Byte size of the output buffer.
//
//     cbResultSize  Actual size of the resulting data.
//
//     lpszName      Output buffer for the control code operation.
//                   Used as the return value.
//
// ====================================================================
{
    DWORD  dwResult     = ERROR_SUCCESS;
    DWORD  cbBufSize    = ClusDocEx_DEFAULT_CB;
    DWORD  cbResultSize = 0;
    LPWSTR lpszName     = NULL;

//--------------------------------------------------------------------
//  Allocate the output buffer.
//--------------------------------------------------------------------

    lpszName = (LPWSTR) LocalAlloc( LPTR, cbBufSize );

    if( lpszName == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//--------------------------------------------------------------------
//  Call the control code function.
//--------------------------------------------------------------------
//
//  Use the output configuration:
//

    dwResult = ClusterResourceControl(
                   hRes,
                   hNode,
                   CLUSCTL_RESOURCE_GET_RESOURCE_TYPE,
                   NULL,
                   0,
                   (LPVOID) lpszName,
                   cbBufSize,
                   &cbResultSize );

//--------------------------------------------------------------------
//  Reallocation routine.
//--------------------------------------------------------------------
//
//  If the buffer was too small, cbResultSize now indicates the
//  necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpszName );

        cbBufSize = cbResultSize;

        lpszName = (LPWSTR) LocalAlloc( LPTR, cbBufSize );

        dwResult = ClusterResourceControl(
                       hRes,
                       hNode,
                       CLUSCTL_RESOURCE_GET_RESOURCE_TYPE,
                       NULL,
                       0,
                       (LPVOID) lpszName,
                       cbBufSize,
                       &cbResultSize );
    }

endf:

    SetLastError( dwResult );

    return lpszName;
}

#endif

// end ClusDocEx_ResGetName

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES, ClusterResourceControl, Name, ResourceControl


CLUSCTL_RESOURCE_GET_NETWORK_NAME

The CLUSCTL_RESOURCE_GET_NETWORK_NAME control code retrieves the name private property of a Network Name resource. This control code is unsupported by the other default resource types. Applications can use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_NETWORK_NAME,                 // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: string
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the name of the resource.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Resource DLL Support

Do not support this control code in your resource DLL. Return ERROR_INVALID_FUNCTION.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_GET_NETWORK_NAME control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_NETWORK_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_NETWORK_NAME
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code retrieves the read-write private properties for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES,           // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES,           // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a property list containing the resource's read-write private properties
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES in your implementation of ResourceControl. Return a property list that includes the names and data values for all of the resource-specific read-write private properties. Remember to terminate the list with CLUSPROP_SYNTAX_ENDMARK. For more information on working with property lists, see Creating Property Lists.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETRWPPROPS_CPP
#define _CLUSDOCEX_RESGETRWPPROPS_CPP

LPVOID
ClusDocEx_ResGetRWPProperties

(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
)
// ====================================================================
//
// Description:
//
//     Retrieves the read-write private properties of a resource
//     using CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//    OUT LPDWORD  lpcbDataSize   Returns the byte size of the
//                                resulting data.
//
// Return Value:
//
//    If successful, returns a property list containing the
//    read-write private properties of the resource identified
//    by hRes.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    lpOutBuffer     Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    LPVOID lpOutBuffer   = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES;

    lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      lpcbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbDataSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbDataSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;  // Call LocalFree to release the memory.

//
//  The calling function will need to parse the property list to
//  extract the property names and values.
//
//  See "Parsing Property Lists" for procedures and an example.
//

}

#endif

// end ClusDocEx_ResGetRWPProperties

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS

The CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS control code retrieves a property list describing the format of each resource private property. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each private property.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Return a property list that describes the formats of all of your resource-specific private properties (see Remarks below).

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

The property list returned by CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS contains one entry for each resource private property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterResourceControl


CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS

The CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS control code retrieves a list of all the registry checkpoints set for a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS,         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains a registry key that has previously been added to the resource's list of checkpoints with the CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Resource DLL Support

The CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_REGISTRY_CHECKPOINT
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETREGISTRYCHECKPOINTS_CPP
#define _CLUSDOCEX_RESGETREGISTRYCHECKPOINTS_CPP

LPVOID
ClusDocEx_ResGetRegistryCheckpoints

(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
)
// ====================================================================
//
// Description:
//
//     Retrieves the current registry checkpoints of a resource
//     using CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//    OUT LPDWORD  lpcbDataSize   Returns the byte size of the
//                                resulting data.
//
// Return Value:
//
//    If successful, returns a string array containing the
//    checkpointed registry keys currently established for
//    the resource identified by hRes.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    lpOutBuffer     Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    LPVOID lpOutBuffer   = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS;

    lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      lpcbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbDataSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
            );

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbDataSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;  // Call LocalFree to release the memory.

//
//  The calling function will need to parse the returned buffer
//  to read individual key names from the array.
//

}

#endif

// end ClusDocEx_ResGetRegistryCheckpoints

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES

The CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code retrieves a list of all required dependencies for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES,        // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES,        // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a value list containing a CLUSPROP_REQUIRED_DEPENDENCY union for each dependency.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Conditional. If your resource has required dependencies, you must support the CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code in your implementation of ResourceControl. Return a value list containing one CLUSPROP_REQUIRED_DEPENDENCY union for each resource on which your resource is required to depend. Remember to terminate the list with CLUSPROP_SYNTAX_ENDMARK.

For example, if your resource has required dependencies on a storage class resource and a Network Name resource, ResourceControl should return a value list with three entries:

  • A CLUSPROP_REQUIRED_DEPENDENCY union with the ResClass member set to CLUS_RESCLASS_STORAGE.
  • A CLUSPROP_REQUIRED_DEPENDENCY union with the ResTypeName member set to "Network Name".
  • A CLUSPROP_VALUE structure with the Syntax member set to CLUSPROP_SYNTAX_ENDMARK.

The Resource Monitor provides no default processing.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

For examples of using CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES, see Creating a Value List and Parsing a Value List.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_REQUIRED_DEPENDENCIES
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETREQDEPS_CPP
#define _CLUSDOCEX_RESGETREQDEPS_CPP

LPVOID
ClusDocEx_ResGetRequiredDependencies

(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
)
// ====================================================================
//
// Description:
//
//     Retrieves the required dependencies of a resource
//     using CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES.
//     Note that the resource DLL that manages the resource
//     is responsible for returning the resource's required
//     dependencies.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//    OUT LPDWORD  lpcbDataSize   Returns the byte size of the
//                                resulting value list.
//
// Return Value:
//
//    If successful, returns a value list containing a
//    CLUSPROP_REQUIRED_DEPENDENCY union for each resource that
//    hRes depends on.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    lpReqDeps       Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    LPVOID lpReqDeps     = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES;

    lpReqDeps = LocalAlloc( LPTR, cbBufSize );

    if( lpReqDeps == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpReqDeps,       // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      lpcbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpReqDeps );

        cbBufSize = *lpcbDataSize;

        lpReqDeps = LocalAlloc( LPTR, cbBufSize );

        if( lpReqDeps == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpReqDeps,       // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
            );

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpReqDeps );
        lpReqDeps = NULL;
        *lpcbDataSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpReqDeps;  // Call LocalFree to release the memory.

//
//  The calling function will need to parse the value list to
//  extract the resource type names and resource classes
//  that hRes depends on.
//
//  See "Parsing Value Lists" for procedures and an example.
//

}

#endif

// End ClusDocEx_ResGetRequiredDependencies.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_GET_RESOURCE_TYPE

The CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code retrieves the resource type name for a resource. Applications use this control code as a ClusterResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_RESOURCE_TYPE,                // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: string
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl.

lpOutBuffer
On a successful return, points to a null-terminated Unicode string containing the resource type of the resource.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.

Resource DLL Support

The CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code is handled by the Cluster service and is not passed to resource DLLs.

Remarks

The resource type name is stored in the Type property. This is the registered name of the resource type, such as "File Share" or "Physical Disk", and not the display name. For information on the difference between registered and display names, see Display Names.

Do not use the CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_RESOURCE_TYPE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RESOURCE_TYPE
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETTYPE_CPP
#define _CLUSDOCEX_RESGETTYPE_CPP

LPWSTR
ClusDocEx_ResGetResourceType

(
    IN HRESOURCE hRes,
    IN HNODE     hNode
)
// ====================================================================
//
// Description:
//
//     Retrieves the resource type of a resource
//     using CLUSCTL_RESOURCE_GET_RESOURCE_TYPE.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//
// Return Value:
//
//    If successful, returns a string specifying the resource type
//    of the resource identified by hRes.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    cbDataSize      Actual byte size of the resulting data.
//    lpszType        Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    DWORD  cbDataSize    = 0;
    LPWSTR lpszType      = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_RESOURCE_TYPE;

    lpszType = (LPWSTR) LocalAlloc( LPTR, cbBufSize );

    if( lpszType == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   (LPVOID)lpszType,// Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   &cbDataSize      // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      cbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpszType );

        cbBufSize = cbDataSize;

        lpszType = (LPWSTR) LocalAlloc( LPTR, cbBufSize );

        if( lpszType == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   (LPVOID)lpszType,// Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   &cbDataSize      // Byte size of the resulting data.
            );

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpszType );
        lpszType = NULL;
    }

endf:

    SetLastError( dwResult );

    return lpszType;  // Call LocalFree to release the memory.

}

#endif

// end ClusDocEx_ResGetType

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl, Type


CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES,         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES,         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a property list containing the resource's read-only common resource properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Whether or not your implementation of ResourceControl performs processing for CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES, return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of resource common properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use the CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETROCPROPS_CPP
#define _CLUSDOCEX_RESGETROCPROPS_CPP

LPVOID
ClusDocEx_ResGetROCProperties

(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
)
// ====================================================================
//
// Description:
//
//     Retrieves the read-only common properties of a resource
//     using CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//    OUT LPDWORD  lpcbDataSize   Returns the byte size of the
//                                resulting data.
//
// Return Value:
//
//    If successful, returns a property list containing the
//    read-only common properties of the resource identified
//    by hRes.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    lpOutBuffer     Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    LPVOID lpOutBuffer   = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES;

    lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      lpcbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbDataSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
            );

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbDataSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;  // Call LocalFree to release the memory.

//
//  The calling function will need to parse the property list to
//  extract the property names and values.
//
//  See "Parsing Property Lists" for procedures and an example.
//

}

#endif

// end ClusDocEx_ResGetROCProperties

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, Name, ResourceControl


CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES,        // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES,        // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a property list containing the resource's read-only private properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code in your implementation of ResourceControl. Return a property list that includes all of the read-only properties specific to your resource. Remember to terminate the list with CLUSPROP_SYNTAX_ENDMARK. For more information on working with property lists, see Creating Property Lists.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use the CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Code Example

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

#ifndef _CLUSDOCEX_RESGETROPPROPS_CPP
#define _CLUSDOCEX_RESGETROPPROPS_CPP

LPVOID
ClusDocEx_ResGetROPProperties

(
    IN HRESOURCE hRes,
    IN HNODE     hNode,
    OUT LPDWORD  lpcbDataSize
)
// ====================================================================
//
// Description:
//
//     Retrieves the read-only private properties of a resource
//     using CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES.
//
// >!! Call LocalFree on the returned pointer to free the memory. !!<
//
//
// Arguments:
//
//    IN HRESOURCE hRes           Handle to the resource to query.
//
//    IN HNODE     hNode          Handle to the node to perform the
//                                operation or NULL to default to
//                                the owner node.
//
//    OUT LPDWORD  lpcbDataSize   Returns the byte size of the
//                                resulting data.
//
// Return Value:
//
//    If successful, returns a property list containing the
//    read-only private properties of the resource identified
//    by hRes.
//
//    If unsuccessful, returns a NULL pointer;
//    call GetLastError() for details.
//
//
// Local Variables:
//
//    dwResult        Captures return values.
//    cbBufSize       Allocated byte size of the output buffer.
//    lpOutBuffer     Output buffer for the control code operation.
//    dwControlCode   Specifies the operation to perform.
//
// ====================================================================
{
    DWORD  dwResult      = ERROR_SUCCESS;
    DWORD  cbBufSize     = ClusDocEx_DEFAULT_CB;
    LPVOID lpOutBuffer   = NULL;
    DWORD  dwControlCode = CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES;

    lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

    if( lpOutBuffer == NULL )
    {
        dwResult = GetLastError();
        goto endf;
    }

//
//  1.  Call the control code function:
//
    dwResult = ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
               );

//
//  2.  Reallocate if necessary. If the buffer was too small,
//      lpcbDataSize now indicates the necessary byte size.
//
    if ( dwResult == ERROR_MORE_DATA )
    {
        LocalFree( lpOutBuffer );

        cbBufSize = *lpcbDataSize;

        lpOutBuffer = LocalAlloc( LPTR, cbBufSize );

        if( lpOutBuffer == NULL )
        {
            dwResult = GetLastError();
            goto endf;
        }

        dwResult =
            ClusterResourceControl(
                   hRes,            // Resource to query.
                   hNode,           // Node to perform operation.
                   dwControlCode,   // Control code.
                   NULL,            // Input buffer (not used).
                   0,               // Input buffer size (not used).
                   lpOutBuffer,     // Output buffer.
                   cbBufSize,       // Byte size of the buffer.
                   lpcbDataSize     // Byte size of the resulting data.
            );

    }

//
//  3.  Handle errors.
//
    if( dwResult != ERROR_SUCCESS )
    {
        LocalFree( lpOutBuffer );
        lpOutBuffer = NULL;
        *lpcbDataSize = 0;
    }

endf:

    SetLastError( dwResult );

    return lpOutBuffer;  // Call LocalFree to release the memory.

//
//  The calling function will need to parse the property list to
//  extract the property names and values.
//
//  See "Parsing Property Lists" for procedures and an example.
//

}

#endif

// end ClusDocEx_ResGetROPProperties

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_QUERY_DELETE

The CLUSCTL_RESOURCE_QUERY_DELETE control code is reserved for future use.


CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code is used to update the read-write common properties for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES,            // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES,            // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpInBuffer
Points to a property list containing one or more read-write common resource properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
ERROR_RESOURCE_PROPERTIES_STORED
The properties were successfully saved, but will not take effect until the specified resource is taken offline and brought online.
Win32 Error
The operation was not successful.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor set the properties in the cluster database.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl


CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code is used to update the read-write private properties for a resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES,           // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES,           // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpInBuffer
Points to a property list containing one or more read-write private resource properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
ERROR_RESOURCE_PROPERTIES_STORED
The properties were successfully saved, but will not take effect until the specified resource is taken offline and brought online.
Win32 Error
The operation was not successful.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code in your implementation of ResourceControl. This allows you to validate the property values before writing them to the cluster database. Be sure to return ERROR_RESOURCE_PROPERTIES_STORED if the new property values do not take effect immediately for the resource.

If you do not support this control code, the Resource Monitor uses the unvalidated content of InBuffer to update the cluster database, which can result in invalid properties being specified for your resource.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Do not use this control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO

The CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO control code retrieves information about a particular storage class resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO,            // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO,            // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpOutBuffer
On a successful return, points to a value list describing the storage class resource. For information on the format of this list see Value Lists for Storage Class Resources..
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Conditional. You must support the CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO control code if your resource DLL handles storage class resources such as quorum-capable resources. Return a value list that fully describes the storage class resource. For information on working with value lists, see Using Value Lists.

The Resource Monitor does not provide default handling.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_STORAGE_GET_DISK_INFO
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl, CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS


CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID

The CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID control code is used to verify that a specified path exists on a storage class resource. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID,            // this control code
  lpInBuffer                                         // input buffer
  cbInBufferSize,                                    // input buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of result (not used)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID,            // this control code
  lpInBuffer                                         // input buffer
  cbInBufferSize,                                    // input buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of result (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string specifying the path to validate.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The specified path is valid for the storage class resource identified by hResource.
ERROR_PATH_NOT_FOUND
The specified path does not exist on the storage class resource identified by hResource.
ERROR_BAD_PATHNAME
The specified pathname is illegal and cannot exist on the storage class resource identified by hResource.
Win32 Error
The operation was not successful. The validity of the path is uncertain.
Implementations of ResourceControl can return one of the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Conditional. Support the CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID control code if your resource DLL handles storage class resources. Keep in mind that this control code is a "yes-or-no" question, so try to return only ERROR_SUCCESS, ERROR_PATH_NOT_FOUND, ERROR_BAD_PATHNAME, or other values that unambiguously indicate whether the path is valid.

The Resource Monitor does not provide default handling.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

In Windows 2000, the Physical Disk resource type does not support this control code.

Do not use the CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_STORAGE_IS_PATH_VALID
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_UNKNOWN

The CLUSCTL_RESOURCE_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_UNKNOWN,                          // this control code
  NULL,                                              // input buffer: (not used)
  0,                                                 // input buffer size (not used)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_UNKNOWN,                          // this control code
  NULL,                                              // input buffer: (not used)
  0,                                                 // input buffer size (not used)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
Indicates that a resource DLL is processing control codes for the specified resource.
ERROR_INVALID_FUNCTION
Indicates that no resource DLL is processing control codes for the specified resource.

Resource DLL Support

Required. Your resource DLL should return ERROR_SUCCESS in response to this control code.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Do not use the CLUSCTL_RESOURCE_UNKNOWN control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceTypeControl


CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid resource common property names and values and that the list is properly formatted. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES,       // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES,       // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpInBuffer
Points to a property list containing one or more read-write common resource properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.
Implementations of ResourceControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor validate the properties in the cluster database.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

The CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES control code only validates read-write common resource properties. Property lists containing private or read-only properties cause validation to fail.

For information on working with property lists, see Using Property Lists.

Do not use the CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl


CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES control code verifies that a property list contains valid resource private property names and values and that the list is properly formatted. Applications use this control code as a ClusterResourceControl parameter, and resource DLLs receive the control code as a ResourceControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceControl(
  hResource,                                         // resource handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES,      // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES,      // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpInBuffer
Points to a property list containing one or more read-write private resource properties.
dwReturn
ClusterResourceControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.

Implementations of ResourceControl can return the above values or the following value:

ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES control code. Your implementation should parse the property list passed in the InBuffer parameter, verifying that each property value is valid for the resource.

If you do not support this control code, the Resource Monitor verifies that the property list is formatted correctly but does not actually validate the data. This can result in the assignment of invalid property values.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

For information on working with property lists, see Using Property Lists.

Do not use the CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES control code in any resource DLL entry point function. This control code can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


Internal Resource Control Codes

The following table lists all of the internal control codes for resources.

Control code | DLL support
CLUSCTL_RESOURCE_ADD_DEPENDENCY | Optional
CLUSCTL_RESOURCE_ADD_OWNER | Optional
CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED | Optional
CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED | Optional
CLUSCTL_RESOURCE_DELETE | Optional
CLUSCTL_RESOURCE_EVICT_NODE | Optional
CLUSCTL_RESOURCE_INSTALL_NODE | Optional
CLUSCTL_RESOURCE_REMOVE_DEPENDENCY | Optional
CLUSCTL_RESOURCE_REMOVE_OWNER | Optional
CLUSCTL_RESOURCE_SET_NAME | Optional

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_ADD_DEPENDENCY

Internal. CLUSCTL_RESOURCE_ADD_DEPENDENCY notifies a resource DLL that a dependency being added to a resource managed by the DLL. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_ADD_DEPENDENCY,                   // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the name of the new dependency.
dwReturn
When implementing ResourceControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_ADD_DEPENDENCY control code for any resource that needs to retrieve or update properties or perform other tasks in response to the new dependency. The Resource Monitor does not provide any default processing.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_ADD_DEPENDENCY as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_ADD_DEPENDENCY
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

AddClusterResourceDependency, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_ADD_OWNER

Internal. CLUSCTL_RESOURCE_ADD_OWNER notifies a resource DLL that a node has been added to the list of possible owner nodes for a resource managed by the DLL. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_ADD_OWNER,                        // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the name of the node being added to the possible owners list.
dwReturn
When implementing ResourceControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_ADD_OWNER control code if the resource needs to retrieve or update properties or perform other tasks in response to the new possible owner. The Resource Monitor does not provide any default processing.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_ADD_OWNER as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_ADD_OWNER
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

AddClusterResourceNode, ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED

Internal. The CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED control code is reserved for internal use only. It informs the core network name resource that the name of the cluster has changed.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED

Internal. The Cluster service uses the CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED control code to notify a resource DLL that the cluster version has changed. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
YourResourceControl(
  ResourceId,                               // resource identifier
  CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED,  // this control code
  NULL,                                     // input buffer
  0,                                        // input buffer size (not used)
  NULL,                                     // output buffer (not used)
  0,                                        // output buffer size (not used)
  NULL                                      // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

dwReturn
When implementing ResourceControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED control code if your resource DLL needs to perform operations in response to the version change (for an overview of the versioning process, see Version Compatibility). The Resource Monitor does not provide any default processing.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_CLUSTER_VERSION_CHANGED
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, ResourceControl


CLUSCTL_RESOURCE_DELETE

Internal. The Cluster service uses the CLUSCTL_RESOURCE_DELETE control code to notify a resource DLL that a resource it is managing is about to be deleted from the cluster. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,               // resource identifier
  CLUSCTL_RESOURCE_DELETE,  // this control code
  NULL,                     // input buffer
  0,                        // input buffer size (not used)
  NULL,                     // output buffer (not used)
  0,                        // output buffer size (not used)
  NULL                      // resulting data size (not used)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

dwReturn
Your implementation of ResourceControl should return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. Supporting the CLUSCTL_RESOURCE_DELETE control code allows you to perform any cleanup tasks that may be necessary before the deletion occurs, such as removing temporary files. Note that the Cluster service allows only offline resources to be deleted. Thus your resource DLL will receive this control code only for resources that are already offline. The Resource Monitor does not provide any default processing.

By default, the CLUSCTL_RESOURCE_DELETE control code is sent only to the resource DLL on the node that currently owns the resource. For information about ensuring that the control code is sent to every node in the cluster, see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.

Note that when your resource DLL receives this notification, the deletion is inevitable. Your DLL cannot prevent any of its resources from being deleted.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_DELETE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_DELETE
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceControl, DeleteClusterResource, ResourceControl


CLUSCTL_RESOURCE_EVICT_NODE

The Cluster service uses the CLUSCTL_RESOURCE_EVICT_NODE control code to notify a resource DLL that a node is being permanently removed from the cluster. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceID,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_EVICT_NODE,                       // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the name of the evicted node.
dwReturn
When implementing ResourceControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_EVICT_NODE control code if your resource stores node-localized or node-specific data. By handling this code, you can remove this data and perform any other necessary cleanup tasks. The Resource Monitor provides no default processing.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_EVICT_NODE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_EVICT_NODE
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceControl, ClusterResourceControl, CLUSCTL_RESOURCE_EVICT_NODE, EvictClusterNode


CLUSCTL_RESOURCE_INSTALL_NODE

The CLUSCTL_RESOURCE_INSTALL_NODE control code is used by the Cluster service to notify a resource DLL that a node is being added to the cluster. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_INSTALL_NODE,                     // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

lpInBuffer
null-terminated Unicode string containing the name of the newly added node.
dwReturn
Implementations of ResourceControl should return one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_INSTALL_NODE control code if you have any tasks that must be performed when a new node is added to a cluster. The Resource Monitor provides no default processing.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_INSTALL_NODE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_INSTALL_NODE
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceControl, ClusterResourceControl


CLUSCTL_RESOURCE_REMOVE_DEPENDENCY

The CLUSCTL_RESOURCE_REMOVE_DEPENDENCY control code is used by the Cluster service to notify a resource DLL that a dependency is being removed from a resource managed by the DLL. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_REMOVE_DEPENDENCY,                // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the name of the dependent resource.
dwReturn
Implementations of ResourceControl should return one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_REMOVE_DEPENDENCY control code if the resource needs to retrieve or update properties or perform other tasks in response to the removed dependency. Otherwise, return ERROR_INVALID_FUNCTION to let the Resource Monitor process the control code.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_REMOVE_DEPENDENCY as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_REMOVE_DEPENDENCY
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceControl, ClusterResourceControl


CLUSCTL_RESOURCE_REMOVE_OWNER

The CLUSCTL_RESOURCE_REMOVE_OWNER control code is used by the Cluster service to notify a resource DLL that a node is being removed from the list of possible owner nodes for a resource managed by the DLL. Resource DLLs receive this control code as a ResourceControl parameter. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_REMOVE_OWNER,                     // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceControl.

lpInBuffer
Pointer to a null-terminated Unicode string containing the name of the node being removed from the possible owners list.
dwReturn
Implementations of ResourceControl should return one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_REMOVE_OWNER control code if the resource needs to retrieve or update properties or perform other tasks in response to the removed node. Otherwise, return ERROR_INVALID_FUNCTION to let the Resource Monitor process the control code.

For more information on the ResourceControl entry point, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_REMOVE_OWNER as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_REMOVE_OWNER
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceControl, ClusterResourceControl


CLUSCTL_RESOURCE_SET_NAME

The Cluster service uses the CLUSCTL_RESOURCE_SET_NAME control code to notify a resource DLL that the name of a resource has been changed. Because the control code is internal, applications cannot use it in a control code function.

DLL Syntax

dwReturn =
ResourceControl(
  ResourceId,                                        // identifier of affected resource
  CLUSCTL_RESOURCE_SET_NAME,                         // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceControl or ResourceControl.

lpInBuffer
null-terminated Unicode string containing the new resource name.
dwReturn
Implementations of ResourceControl should return:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

None required. The resource name has already been changed in the cluster database. Respond to the CLUSCTL_RESOURCE_SET_NAME control code if you need to perform other tasks when the name of your resource changes.

For more information on the ResourceControl entry point function, see Implementing ResourceControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_SET_NAME as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_SET_NAME
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceControl, ClusterResourceControl,


Resource Type Control Codes

Resource type control codes are used in the following ways:

  • Applications use external control codes as ClusterResourceTypeControl parameters to initiate operations on a resource type.
  • The Cluster service uses internal resource type control codes to notify resource DLLs of changes to the cluster environment.
  • Resource DLLs receive internal and external resource type control codes as parameters to the ResourceTypeControl entry point function. A resource DLL may implement special procedures in response to a control code, depending on the control code and the needs of the resource type it manages. For more information, see Implementing ResourceTypeControl.

Refer to the following sections:

External Resource Type Control Codes

Internal Resource Type Control Codes


External Resource Type Control Codes

The following table lists all of the external resource type control codes.

Control code | DLL support
CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS | Optional
CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO | Optional
CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS | Use default
CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS | Use default
CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS | Use default
CLUSCTL_RESOURCE_TYPE_GET_FLAGS | Optional
CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS | Conditional
CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS | Required
CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS | Conditional
CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES | Conditional
CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES | Required
CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS | Conditional
CLUSCTL_RESOURCE_TYPE_UNKNOWN | Conditional
CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES | Use default
CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES | Required

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES control code retrieves a list of the read-write resource type common property names. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                               // resource type name
  hCluster,                                      // cluster handle
  hHostNode,                                     // optional host node
  CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES,  // this control code
  NULL,                                          // input buffer (not used)
  0,                                             // input buffer size (not used)
  lpOutBuffer,                                   // output buffer: array of strings
  cbOutBufferSize,                               // allocated buffer size (bytes)
  lpcbBytesReturned );                           // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                               // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES,  // this control code
  NULL,                                          // input buffer (not used)
  0,                                             // input buffer size (not used)
  lpOutBuffer,                                   // output buffer: array of strings
  cbOutBufferSize,                               // allocated buffer size (bytes)
  lpcbBytesReturned );                           // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read/write common resource type property.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
Win32 Error
The operation was not successful.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code in addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor build the list of property names.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

The CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES control code returns only property names, not property values. To retrieve values for common resource type properties, use CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES and CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES. For more information, see Getting Information with Control Codes.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES, CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES, ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES control code retrieves a list of the read/write and read-only resource type private properties. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES,     // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES,     // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: array of strings
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, contains an array of null-terminated Unicode strings with an additional NULL terminator appended to the last string. Each string in the array contains the name of a read/write private resource type property.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES control code by returning the names of the resource type's private properties in the OutBuffer parameter.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

The CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES control code returns only property names, not property values. To retrieve values for common resource type properties, use CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES and CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES.

For more information, see Getting Information with Control Codes.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_ENUM_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES, CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES, ClusterResourceTypeControl, and ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS

The CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS control code retrieves the intrinsic characteristics of a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS,         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS,         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing the resource type's characteristics as one of the following values.
Value | Description
CLUS_CHAR_UNKNOWN | Resources of this type have no known characteristics.
CLUS_CHAR_QUORUM | Resources of this type are capable of being the quorum resource type for a cluster.
CLUS_CHAR_DELETE_REQUIRES_ALL_NODES | Resources of this type cannot be deleted unless all nodes are active.

dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. If you do not support the control code, return ERROR_INVALID_FUNCTION to let the Resource Monitor read the Characteristics value from the resource type key in the cluster database.

If you do support CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS, return a value that accurately describes the resources supported by the resource type. For more information, see CLUSCTL_RESOURCE_GET_CHARACTERISTICS.

For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CHARACTERISTICS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, and ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO

The CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO control code retrieves the class and subclass of a resource type. A resource type class identifies resource types of similar capability. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

A resource DLL receives the CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO control code when an application requests the resource type class of a resource type.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO,         // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: CLUS_RESOURCE_TYPE_CLASS_INFO structure
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO,              // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: CLUS_RESOURCE_TYPE_CLASS_INFO structure
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a CLUS_RESOURCE_CLASS_INFO structure containing resource type class information for the resource type.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. If you do not support it, return ERROR_INVALID_FUNCTION to let the Resource Monitor provide default handling. The Resource Monitor will specify CLUS_RESCLASS_UNKNOWN as the class and zero as the subclass.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_CLASS_INFO
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO, ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code retrieves the read/write common properties for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES,       // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES,       // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list containing the resource type's read/write common resource type properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of common resource type properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

For information on working with property lists, Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS

The CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS control code returns a property list describing the format of each resource type common property. Applications use this control code as a ClusterResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each resource type common property.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of common resource type properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

The property list returned by CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS contains one entry for each resource type common property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS

The CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS control code returns a property list describing the format of each resource common property. Applications use this control code as a ClusterResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hHostNode,                              // optional node handle
  CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each resource common property.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of common resource type properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

Both CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS and CLUSCTL_RESOURCE_GET_COMMON_PROPERTY_FMTS return the formats of the resource common properties. The CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTY_FMTS control code returns the

The property list returned by CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS contains one entry for each resource common property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_COMMON_RESOURCE_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_COMMON_RESOURCE_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS

The CLUSCTL_RESOURCE_TYPE_GET_CRYPTO_CHECKPOINTS control code is reserved for future use.


CLUSCTL_RESOURCE_TYPE_GET_FLAGS

The CLUSCTL_RESOURCE_TYPE_GET_FLAGS control code retrieves the flags that are set for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_FLAGS,                   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_FLAGS,                   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: DWORD bitmask
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, contains a DWORD bitmask describing flags set for the resource type, as follows:
Flag | Description
0 | No flags are defined for the resource type.
Nonzero | Indicates a user-defined flag created by a third party developer for a custom resource type.

dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Optional. Support CLUSCTL_RESOURCE_TYPE_GET_FLAGS only if you define flags specific to the resource type. The Server Cluster API reserves only the lower 16 bits of the DWORD bitmask. Use the upper 16 bits to define your own resource type-specific flags. Be sure to document or otherwise communicate what your flags do and how they should be used.

If you do not define resource type-specific flags, return ERROR_INVALID_FUNCTION to let the Resource Monitor handle the operation. The Resource Monitor will read the Flags value from the resource type key in the cluster database.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_FLAGS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_FLAGS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES control code retrieves the read/write private properties for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES,      // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES,      // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list containing the resource type's read/write private properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES in your implementation of ResourceTypeControl. Return a property list that includes the names and data values for all of the resource type-specific read/write private properties. Remember to terminate the list with CLUSPROP_SYNTAX_ENDMARK. For more information on working with property lists, see Creating Property Lists.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS

The CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS control code retrieves a property list describing the format of each resource type private property. Applications use this control code as a ClusterResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  hCluster,                               // cluster handle
  hHostNode,                              // optional node handle
  CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list describing the format of each private property.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required if you define private properties for your resource type. Otherwise return ERROR_INVALID_FUNCTION. For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

By default, server clusters do not define any private properties for resource types. CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS does not retrieve information about unknown properties.

The property list returned by CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS contains one entry for each resource type private property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS

The CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS control code returns a property list describing the format of each resource private property. Applications use this control code as a ClusterResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hHostNode,                              // optional node handle
  CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTY_FMTS,  // this control code
  NULL,                                   // input buffer (not used)
  0,                                      // input buffer size (not used)
  lpOutBuffer,                            // output buffer: property list
  cbOutBufferSize,                        // output buffer size (bytes)
  lpcbBytesReturned                       // resulting data size (bytes)
);

Parameters

The following control code function parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl

lpOutBuffer
On a successful return, points to a property list describing the format of each resource private property.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

The property list returned by CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS contains one entry for each resource private property, formatted as follows:

  • A CLUSPROP_PROPERTY_NAME structure describing the property name.
  • Alignment padding (see ALIGN_CLUSPROP).
  • A CLUSPROP_WORD structure describing the format of the property value.
  • A CLUSPROP_SYNTAX structure set to CLUSPROP_SYNTAX_ENDMARK.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_RESOURCE_PROPERTY_FMTS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_PRIVATE_RESOURCE_PROPERTY_FMTS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h; include Clusapi.lib.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS

The CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS control code is reserved for future use.


CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES

The CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES control code retrieves a list of all required dependencies for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES,   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES,   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a value list containing a CLUSPROP_REQUIRED_DEPENDENCY union for each dependency.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Conditional. If your resource type has required dependencies, support the CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES control code in your implementation of ResourceTypeControl. Return a value list containing one CLUSPROP_REQUIRED_DEPENDENCY union for each resource on which resources of this type are required to depend. Remember to terminate the list with CLUSPROP_SYNTAX_ENDMARK.

For example, if your resource type has required dependencies on a storage class device and a Network Name resource type, ResourceTypeControl should return a value list with three entries:

  • A CLUSPROP_REQUIRED_DEPENDENCY union with the ResClass member set to CLUS_RESCLASS_STORAGE.
  • A CLUSPROP_REQUIRED_DEPENDENCY union with the ResTypeName member set to "Network Name".
  • A CLUSPROP_VALUE structure with the Syntax member set to CLUSPROP_SYNTAX_ENDMARK.

(For an example, see Creating a Value List.) The Resource Monitor provides no default processing.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

For examples of using CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES, see Creating a Value List and Parsing a Value List.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_REQUIRED_DEPENDENCIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl, CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES


CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES control code retrieves the read-only common properties for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES,    // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES,    // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list containing the resource type's read-only common resource type properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Whether or not your implementation of ResourceTypeControl performs processing for CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES, return ERROR_INVALID_FUNCTION to let the Resource Monitor create the property list. The Resource Monitor will return a version-appropriate list of common resource type properties.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

For information on working with property lists, Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, Name, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES control code retrieves the read-only private properties for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES,   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES,   // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: property lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a property list containing the resource type's read-only private properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES control code in your implementation of ResourceTypeControl. Return a property list that includes all of the read-only properties specific to your resource type. Remember to terminate the list with CLUSPROP_SYNTAX_ENDMARK. For more information on working with property lists, see Creating Property Lists.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_RO_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_QUERY_DELETE

The CLUSCTL_RESOURCE_TYPE_QUERY_DELETE control code is reserved for future use.


CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code is used to update the read/write common properties for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES,       // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceTypeControl(
  ResourceId,                                        // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES,       // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpInBuffer
Points to a property list containing one or more read/write common resource type properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
ERROR_RESOURCE_TYPE_PROPERTIES_STORED
The properties were successfully saved, but will not take effect until the specified resource type is taken offline and brought online.
Win32 Error
The operation was not successful.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor set the properties in the cluster database.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code is used to update the read/write private properties for a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES,      // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceTypeControl(
  ResourceId,                                        // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES,      // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpInBuffer
Points to a property list containing one or more read/write private resource type properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
ERROR_RESOURCE_TYPE_PROPERTIES_STORED
The properties were successfully saved, but will not take effect until the specified resource type is taken offline and brought online.
Win32 Error
The operation was not successful.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code in your implementation of ResourceTypeControl. This allows you to validate the property values before writing them to the cluster database. Be sure to return ERROR_RESOURCE_TYPE_PROPERTIES_STORED if the new property values do not take effect immediately for the resource type.

If you do not support this control code, the Resource Monitor uses the unvalidated content of InBuffer to update the cluster database, which can result in invalid properties being specified for your resource type.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Remarks

The Server Cluster API currently defines no private properties for resource types.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_SET_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS

The CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code retrieves information about storage class devices supported by a resource type. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS, // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value list
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

DLL Syntax

dwReturn =
ResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS, // this control code
  NULL,                                              // input buffer (not used)
  0,                                                 // input buffer size (not used)
  lpOutBuffer,                                       // output buffer: value lisst
  cbOutBufferSize,                                   // allocated buffer size (bytes)
  lpcbBytesReturned );                               // actual size of resulting data (bytes)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpOutBuffer
On a successful return, points to a value list describing all available storage class devices in the cluster supported by the resource type specified by lpszResTypeName.
  • For information on the format of this list see Value Lists for Storage Class Resources.
  • A storage class device is available if it is not currently owned by a node. Because resources are always owned by a node at any point in time, storage class devices configured as resources will not be included in the returned value list.
  • Any given storage class resource can appear more than once in the list.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The operation was successful. The lpcbBytesReturned parameter points to the actual size of the returned data.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer was not large enough to hold the data resulting from the operation. The lpcbBytesReturned parameter points to the size required for the output buffer.
Win32 Error
The operation was not successful. The lpcbBytesReturned parameter points to an unreliable value.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Conditional. If your DLL handles quorum-capable resource storage class resources, you must support the CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code. Create and return a value list formatted as described under lpOutBuffer. For more information, see Creating a Value List and Implementing ResourceTypeControl.

Otherwise, return ERROR_INVALID_FUNCTION.

Remarks

For examples of using CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS, see Creating a Physical Disk Resource. For information on accessing the data in a value list, see Parsing a Value List.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_GET_AVAILABLE_DISKS
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl, CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO


CLUSCTL_RESOURCE_TYPE_UNKNOWN

The CLUSCTL_RESOURCE_TYPE_UNKNOWN control code verifies that control codes are being processed. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_UNKNOWN,                     // this control code
  NULL,                                              // input buffer: (not used)
  0,                                                 // input buffer size (not used)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceTypeControl(
  ResourceId,                                        // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_UNKNOWN,                     // this control code
  NULL,                                              // input buffer: (not used)
  0,                                                 // input buffer size (not used)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
Indicates that a resource DLL is processing control codes for the specified resource type.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Conditional. If your DLL supports any other resource type control codes for the indicated resource type, return ERROR_SUCCESS. Otherwise, return ERROR_INVALID_FUNCTION.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_UNKNOWN as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_UNKNOWN
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES control code verifies that a property list contains valid resource type common property names and values and that the list is properly formatted. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceTypeControl(
  ResourceId,                                        // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES,  // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpInBuffer
Points to a property list containing one or more read/write common resource type properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Use default. Return ERROR_INVALID_FUNCTION to let the Resource Monitor validate the properties in the cluster database.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

The CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES control code only validates read/write common resource type properties. Property lists containing private or read-only properties cause validation to fail.

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_COMMON_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES control code verifies that a property list contains valid resource type property names and values and that the list is properly formatted. Applications use this control code as a ClusterResourceTypeControl parameter, and resource DLLs receive the control code as a ResourceTypeControl parameter.

Control Code Function Syntax

dwReturn =
ClusterResourceTypeControl(
  lpszResTypeName,                                   // resource type name
  hCluster,                                          // cluster handle
  hHostNode,                                         // optional host node
  CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES, // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

DLL Syntax

dwReturn =
ResourceTypeControl(
  ResourceId,                                        // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES, // this control code
  lpInBuffer,                                        // input buffer: property list
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following control code function and DLL support parameters are specific to this control code. For complete parameter descriptions, see ClusterResourceTypeControl or ResourceTypeControl.

lpInBuffer
Points to a property list containing one or more read/write private resource type properties.
dwReturn
ClusterResourceTypeControl returns one of the following values:
ERROR_SUCCESS
The property list is correctly formatted and contains valid data values.
ERROR_INSUFFICIENT_BUFFER
The actual size of the property list buffer as determined by the Cluster service is larger than the size specified in the cbInBufferSize parameter.
ERROR_INVALID_DATA
The property list is either formatted incorrectly or contains invalid data, such as an out-of-range value.
ERROR_INVALID_PARAMETER
The property list is not formatted correctly.
Win32 Error
The operation was not successful.
Implementations of ResourceTypeControl can return the above values or the following value:
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).

Resource DLL Support

Required. Always support the CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES control code. Your implementation should parse the property list passed in the InBuffer parameter, verifying that each property value is valid for the resource type.

If you do not support this control code, the Resource Monitor verifies that the property list is formatted correctly but does not actually validate the data. This can result in the assignment of invalid property values.

As a general guideline, the Resource Monitor should handle all of the control codes for common properties, while your DLL should handle all control codes for private properties.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

For information on working with property lists, see Using Property Lists.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_NO_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | External
Operation code | 2-19 | CLCTL_VALIDATE_PRIVATE_PROPERTIES
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


Internal Resource Type Control Codes

The following table lists all of the internal resource type control codes.

Control code | DLL support
CLUSCTL_RESOURCE_TYPE_CLUSTER_VERSION_CHANGED | Optional
CLUSCTL_RESOURCE_TYPE_EVICT_NODE | Optional
CLUSCTL_RESOURCE_TYPE_FIXUP_ON_UPGRADE | Optional
CLUSCTL_RESOURCE_TYPE_HOLD_IO | Do not support
CLUSCTL_RESOURCE_TYPE_INSTALL_NODE | Optional
CLUSCTL_RESOURCE_TYPE_RESUME_IO | Do not support
CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1 | Optional
CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 | Optional

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_CLUSTER_VERSION_CHANGED

Internal. The CLUSCTL_RESOURCE_TYPE_CLUSTER_VERSION_CHANGED control code indicates that the cluster version has changed. Resource DLLs receive this control code through the ResourceTypeControl entry point, which is called once for every resource type supported by the DLL.

DLL Syntax

dwReturn =
YourResourceTypeControl(
  lpszResTypeName,                               // name of affected resource type
  CLUSCTL_RESOURCE_TYPE_CLUSTER_VERSION_CHANGED, // this control code
  NULL,                                          // input buffer
  0,                                             // input buffer size (not used)
  NULL,                                          // output buffer (not used)
  0,                                             // output buffer size (not used)
  NULL                                           // resulting data smze (not used)
);

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceTypeControl.

dwReturn
When implementing ResourceTypeControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_TYPE_CLUSTER_VERSION_CHANGED control code if your resource DLL needs to perform operations in response to the version change (for an overview of the versioning process, see Version Compatibility).

The Resource Monitor does not provide any default processing.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_CLUSTER_VERSION_CHANGED
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusterResourceTypeControl, ResourceTypeControl


CLUSCTL_RESOURCE_TYPE_EVICT_NODE

Internal. The CLUSCTL_RESOURCE_TYPE_EVICT_NODE control code indicates that a node is being permanently removed from the cluster. Resource DLLs receive this control code through the ResourceTypeControl entry point, which is called once for every resource type supported by the DLL.

DLL Syntax

dwReturn =
YourResourceTypeControl(
  lpszResTypeName,                                   // identifier of affected resource type
  CLUSCTL_RESOURCE_TYPE_EVICT_NODE,                  // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceTypeControl.

lpInBuffer
Pointer to a NULL-terminated Unicode string containing the name of the evicted node.
dwReturn
When implementing ResourceTypeControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_TYPE_EVICT_NODE control code if your resource type stores node-localized or node-specific data. By handling this code, you can remove this data and perform any other necessary cleanup tasks. The Resource Monitor provides no default processing.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_EVICT_NODE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_EVICT_NODE
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceTypeControl, ClusterResourceTypeControl, CLUSCTL_RESOURCE_TYPE_EVICT_NODE, EvictClusterNode


CLUSCTL_RESOURCE_TYPE_FIXUP_ON_UPGRADE

Internal. The CLUSCTL_RESOURCE_TYPE_FIXUP_ON_UPGRADE control code indicates that a node in the cluster has just completed an upgrade of the Cluster service. Resource DLLs receive this control code through the ResourceTypeControl entry point function, which is called once for every resource type supported by the DLL.

DLL Syntax

dwReturn =
YourResourceTypeControl(
  lpszResTypeName,                                   // name of affected resource type
  CLUSCTL_RESOURCE_TYPE_FIXUP_ON_UPGRADE             // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceTypeControl.

lpInBuffer
Pointer to a NULL-terminated Unicode string containing the name of the evicted node.
dwReturn
When implementing ResourceTypeControl, return one of the following values:
ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_TYPE_FIXUP ON UPGRADE control code if your resource type needs to make adjustments in response to the change.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_FIXUP_ON_UPGRADE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_FIXUP_ON_UPGRADE
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceTypeControl, ClusterResourceTypeControl, CLUSCTL_RESOURCE_TYPE_EVICT_NODE, EvictClusterNode


CLUSCTL_RESOURCE_TYPE_HOLD_IO

The CLUSCTL_RESOURCE_TYPE_HOLD_IO control code is reserved for future use.


CLUSCTL_RESOURCE_TYPE_INSTALL_NODE

Internal. The CLUSCTL_RESOURCE_TYPE_INSTALL_NODE control code indicates that a new node has been added to the cluster. Resource DLLs receive this control code through the ResourceTypeControl entry point function, which is called once for every resource type supported by the DLL.

DLL Syntax

dwReturn =
YourResourceTypeControl(
  lpszResTypeName,                                   // name of affected resource type
  CLUSCTL_RESOURCE_TYPE_INSTALL_NODE,                // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceTypeControl.

lpInBuffer
NULL-terminated Unicode string containing the name of the newly added node.
dwReturn
Implementations of ResourceTypeControl should return one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_TYPE_INSTALL_NODE control code if you have any tasks that must be performed when a new node is added to a cluster. The Resource Monitor provides no default processing.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_INSTALL_NODE as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_INSTALL_NODE
Access code | 0-1 | CLUS_ACCESS_WRITE

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ResourceTypeControl, ClusterResourceTypeControl


CLUSCTL_RESOURCE_TYPE_RESUME_IO

The CLUSCTL_RESOURCE_TYPE_RESUME_IO control code is reserved for future use.


CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1

CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1 is an internal control code that indicates that the Cluster service is starting on one of the cluster nodes. Resource DLLs receive this control code through the ResourceTypeControl entry point function, which is called once for every resource type supported by the DLL.

DLL Syntax

dwReturn =
YourResourceTypeControl(
  lpszResTypeName,                                   // name of affected resource type
  CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1              // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceTypeControl.

lpInBuffer
Points to a CLUS_STARTING_PARAMS structure describing whether the start of the Cluster service represents an attempt to form a new cluster or an attempt to join an existing cluster, and whether this is the first start of the Cluster service on the node.
dwReturn
Implementations of ResourceTypeControl should return one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code in addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1 control code if you have any tasks that must be performed while the Cluster service is starting on a node.

The Resource Monitor provides no default processing.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

The Cluster API will be unavailable to the node on which the Cluster service is starting until your DLL receives the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 control code.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1 as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_STARTING_PHASE1
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUS_STARTING_PARAMS, CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2


CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2

CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 is an internal control code that indicates that a node in the cluster has just completed a startup of the Cluster service. Resource DLLs receive this control code through the ResourceTypeControl entry point function, which is called once for every resource type supported by the DLL.

DLL Syntax

dwReturn =
YourResourceTypeControl(
  lpszResTypeName,                                   // name of affected resource type
  CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2              // this control code
  lpInBuffer,                                        // input buffer: string
  cbInBufferSize,                                    // allocated buffer size (bytes)
  NULL,                                              // output buffer: (not used)
  0,                                                 // output buffer size (not used)
  NULL );                                            // actual size of resulting data (not used)

Parameters

The following DLL support parameters are specific to this control code. For complete parameter descriptions, see ResourceTypeControl.

lpInBuffer
Pointer to a CLUS_STARTING_PARAMS structure describing whether the start represents a form or join operation, and whether this is the first start of the Cluster service on the node.
dwReturn
Implementations of ResourceTypeControl should return one of the following values:
ERROR_SUCCESS
The operation was successful.
ERROR_INVALID_FUNCTION
Requests that the Resource Monitor perform default processing (if any) for the control code addition to processing supplied by the DLL (if any).
Win32 Error
The operation was not successful.

Resource DLL Support

Optional. Support the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 control code if you have any tasks that must be performed after the Cluster service has started on the node. The Resource Monitor provides no default processing.

For more information on the ResourceTypeControl entry point, see Implementing ResourceTypeControl.

Remarks

Once your DLL receives the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 control code, the Cluster API is available to the node on which the Cluster service has started.

Clusapi.h defines the 32 bits of CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 as follows (for more information, see Control Code Architecture).

Component | Bit location | Value
Object code | 24-31 | CLUS_OBJECT_RESOURCE_TYPE
Global bit | 23 | CLUS_NOT_GLOBAL
Modify bit | 22 | CLUS_MODIFY
User bit | 21 | CLCTL_CLUSTER_BASE
Type bit | 20 | Internal
Operation code | 2-19 | CLCTL_STARTING_PHASE2
Access code | 0-1 | CLUS_ACCESS_READ

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUS_STARTING_PARAMS, CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1


Cluster Object Management Functions

Cluster-aware applications and resource DLLs must discover information about other cluster objects and exert control over them. To serve this need, the Cluster API defines a set of functions to manage cluster objects, the cluster database, and the cluster, itself. Collectively, these sets of functions are called the cluster object management functions.

Applications and resource DLLs use the cluster object management functions to:

  • Open object handles.
  • Enumerate objects.
  • Create and remove object instances.
  • Read state, configuration, and property data for objects.
  • Change an object's state, configuration, or properties.
  • Perform object-specific tasks.

See the following sections for function descriptions:

  • Cluster Database Access Functions
  • Cluster Management Functions
  • Control Code Functions
  • Group Management Functions
  • Network Management Functions
  • Network Interface Management Functions
  • Node Management Functions
  • Resource Management Functions
  • Resource Type Management Functions


Cluster Management Functions

The following functions manage entire clusters.

Function | Description
CloseCluster | Closes a cluster handle.
CloseClusterNotifyPort | Closes a notification port established through CreateClusterNotifyPort.
ClusterCloseEnum | Closes a cluster enumeration handle.
ClusterEnum | Enumerates objects in a cluster, returning the name of one object with each call.
ClusterOpenEnum | Opens an enumerator for iterating through objects in a cluster.
CreateClusterNotifyPort | Creates a notification port to handle cluster event notification.
GetClusterInformation | Returns a cluster's name and version.
GetClusterNotify | Returns the next notification event from a notification port.
GetClusterQuorumResource | Returns the name of a cluster's quorum resource.
OpenCluster | Opens a connection to a cluster and returns a handle to it.
RegisterClusterNotify | Adds an event type to the list of events stored for a notification port.
SetClusterName | Sets the name for a cluster.
SetClusterQuorumResource | Sets the quorum resource for a cluster.


CloseCluster

The CloseCluster function closes a cluster handle.

BOOL WINAPI CloseCluster(
  HCLUSTER hCluster
);

Parameters

hCluster
[in] Handle to the cluster to close.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful; for more information, call the Win32 function GetLastError.

Remarks

Do not close a cluster handle if there are any object handles still in use that were obtained from the cluster handle. Once a cluster handle has been closed, all handles obtained from that handle are invalid.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenCluster


CloseClusterNotifyPort

The CloseClusterNotifyPort function closes a notification port established through CreateClusterNotifyPort.

BOOL WINAPI CloseClusterNotifyPort(
  HCHANGE hChange
);

Parameters

hChange
[in] Handle to the notification port to close.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful; for more information, call the Win32 function GetLastError.

Example

See Receiving Cluster Events and the Notification Port Example.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CreateClusterNotifyPort, GetClusterNotify, RegisterClusterNotify, GetLastError


ClusterCloseEnum

The ClusterCloseEnum function closes a cluster enumeration handle originally opened by ClusterOpenEnum.

DWORD WINAPI ClusterCloseEnum(
  HCLUSENUM hEnum
);

Parameters

hEnum
[in] Cluster enumeration handle to close. This is a handle originally returned by the ClusterOpenEnum function.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterCloseEnum returns a Win32 error value.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterOpenEnum, ClusterEnum


ClusterEnum

The ClusterEnum function enumerates the cluster objects in a cluster, returning the name of one object with each call.

DWORD WINAPI ClusterEnum(
  HCLUSENUM hEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszName,
  LPDWORD lpcchName
);

Parameters

hEnum
[in] A cluster enumeration handle returned by the ClusterOpenEnum function.
dwIndex
[in] Index used to identify the next entry to be enumerated. This parameter should be zero for the first call to ClusterEnum and then incremented for subsequent calls.
lpdwType
[out] Pointer to the type of object returned. One of the following object types is returned with each call.
lpdwType value | Objects enumerated
CLUSTER_ENUM_NODE | Enumerate the nodes in the cluster.
CLUSTER_ENUM_INTERNAL_NETWORK Enumerates the networks used by the cluster for internal communication. The networks are enumerated in order of highest-to-lowest priority as established by SetClusterNetworkPriorityOrder.

Note: Unlike the other enumeration bitmasks, this value must be used alone. Do not use the OR operator to combine it with other bitmasks.
CLUSTER_ENUM_NETWORK | Enumerate the networks in the cluster.
CLUSTER_ENUM_NETINTERFACE | Enumerate the network interfaces in the cluster.
CLUSTER_ENUM_GROUP | Enumerate the groups in the cluster.
CLUSTER_ENUM_RESOURCE | Enumerate the resources in the cluster.
CLUSTER_ENUM_RESTYPE | Enumerate the resource types in the cluster.
CLUSTER_ENUM_ALL | Enumerate all cluster objects.

lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the returned object.
lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more objects of the requested type to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

Remarks

The ClusterEnum function is typically used to iterate through a collection of cluster objects of one or more types. If, for example, an application wants to enumerate all of the nodes in a cluster, it calls ClusterOpenEnum to open a cluster enumerator that can process nodes. The dwType parameter is set to CLUSTER_ENUM_NODE to specify nodes as the object type to be enumerated. If the application enumerates groups in addition to nodes, the dwType parameter is set to CLUSTER_ENUM_NODE | CLUSTER_ENUM_GROUP. With the handle that ClusterOpenEnum returns, the application calls ClusterEnum repeatedly to retrieve each of the objects. The lpdwType parameter points to the type of object that is retrieved.

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterOpenEnum, ClusterCloseEnum, SetClusterNetworkPriorityOrder


ClusterOpenEnum

The ClusterOpenEnum function opens an enumerator for iterating through cluster objects in a cluster.

HCLUSENUM WINAPI ClusterOpenEnum(
  HCLUSTER hCluster,
  DWORD dwType
);

Parameters

hCluster
[in] Handle to a cluster.
dwType
[in] Bitmask describing the type of objects to be enumerated. One or more of the following values are valid.
lpdwType value | Objects enumerated
CLUSTER_ENUM_NODE | Enumerate the nodes in the cluster.
CLUSTER_ENUM_INTERNAL_NETWORK Enumerates the networks used by the cluster for internal communication. The networks are enumerated in order of highest-to-lowest priority as established by SetClusterNetworkPriorityOrder.

Note: Unlike the other enumeration bitmasks, this value must be used alone. Do not use the OR operator to combine it with other bitmasks.
CLUSTER_ENUM_NETWORK | Enumerate the networks in the cluster.
CLUSTER_ENUM_NETINTERFACE | Enumerate the network interfaces in the cluster.
CLUSTER_ENUM_GROUP | Enumerate the groups in the cluster.
CLUSTER_ENUM_RESOURCE | Enumerate the resources in the cluster.
CLUSTER_ENUM_RESTYPE | Enumerate the resource types in the cluster.
CLUSTER_ENUM_ALL | Enumerate all cluster objects.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, ClusterOpenEnum returns a handle to a cluster enumerator.

Remarks

Applications call the ClusterOpenEnum function to create a particular type of enumerator. ClusterOpenEnum can create enumerators for iterating through groups, nodes, resource types, resources, or all of these. For example, an application can call ClusterOpenEnum to get an enumeration of all of the nodes and groups in a cluster by specifying CLUSTER_ENUM_GROUP | CLUSTER_ENUM_NODE in the dwType parameter. ClusterOpenEnum returns a handle that can be passed to ClusterEnum to access each of the cluster groups or nodes and to ClusterCloseEnum to release the enumerator.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterEnum, ClusterCloseEnum, SetClusterNetworkPriorityOrder


CreateClusterNotifyPort

The CreateClusterNotifyPort function creates or modifies a notification port. For information on notification ports, see Receiving Cluster Events.

HCHANGE WINAPI CreateClusterNotifyPort(
  HCHANGE hChange,
  HCLUSTER hCluster,
  DWORD dwFilter,
  DWORD_PTR dwNotifyKey
);

Parameters

hChange
[in] Handle to a notification port or INVALID_HANDLE_VALUE, indicating that a new handle should be created. If hChange is an existing handle, the events specified in dwFilter are added to the notification port.
hCluster
[in] Handle to the cluster to be associated with the notification port identified by hChange, or INVALID_HANDLE_VALUE, indicating that the notification port should not be associated with a cluster. If hChange is not set to INVALID_HANDLE_VALUE, hCluster cannot be set to INVALID_HANDLE_VALUE.
dwFilter
[in] Bitmask of flags that specifies the events that will cause notifications to be stored in the queue. One or more of the following flags can be set using the OR operator, or you can specify all of the flags by using the value CLUSTER_CHANGE_ALL.
Flag Event
CLUSTER_CHANGE_CLUSTER_PROPERTY
(0x40000000) 		The queue receives a notification when the cluster's prioritized list of internal networks changes.
CLUSTER_CHANGE_CLUSTER_STATE
(0x20000000) 		The queue receives a notification when the cluster becomes unavailable, meaning that all attempts to communicate with the cluster fail.
CLUSTER_CHANGE_GROUP_ADDED
(0x00004000) 		The queue receives a notification when a new group is created in the cluster.
CLUSTER_CHANGE_GROUP_DELETED
(0x00002000) 		The queue receives a notification when an existing group is deleted.
CLUSTER_CHANGE_GROUP_PROPERTY
(0x00008000) 		The queue receives a notification when the properties of a group change or when a resource is added or removed from a group.
CLUSTER_CHANGE_GROUP_STATE
(0x00001000) 		The queue receives a notification when a group changes state. For a list of the possible group state values, see GetClusterGroupState.
CLUSTER_CHANGE_HANDLE_CLOSE
(0x80000000) 		The queue receives a notification when a handle associated with a cluster object is closed.
CLUSTER_CHANGE_NETINTERFACE_ADDED
(0x04000000) 		The queue receives a notification when a new network interface is added to a cluster node.
CLUSTER_CHANGE_NETINTERFACE_DELETED
(0x02000000) 		The queue receives a notification when a network interface is permanently removed from a cluster node.
CLUSTER_CHANGE_NETINTERFACE_PROPERTY
(0x08000000) 		The queue receives a notification when the properties of an existing network interface change.
CLUSTER_CHANGE_NETINTERFACE_STATE
(0x01000000) 		The queue receives a notification when a network interface changes state. For a list of the possible network interface state values, see GetClusterNetInterfaceState.
CLUSTER_CHANGE_NETWORK_ADDED
(0x00400000) 		The queue receives a notification when a new network is added to the cluster environment.
CLUSTER_CHANGE_NETWORK_DELETED
(0x00200000) 		The queue receives a notification when a network is permanently removed from the cluster environment.
CLUSTER_CHANGE_NETWORK_PROPERTY
(0x00800000) 		The queue receives a notification when the properties of an existing network change.
CLUSTER_CHANGE_NETWORK_STATE
(0x00100000) 		The queue receives a notification when a network changes state. For a list of the possible network state values, see GetClusterNetworkState.
CLUSTER_CHANGE_NODE_ADDED
(0x00000004) 		The queue receives a notification when a new node is added to the cluster. A node can be added only when the Cluster service is initially installed on the node.
CLUSTER_CHANGE_NODE_DELETED
(0x00000002) 		The queue receives a notification when a node is permanently removed from a cluster. A node can be permanently deleted from an existing cluster with a call to the EvictClusterNode function.
CLUSTER_CHANGE_NODE_PROPERTY
(0x00000008) 		This notification is reserved for future use.
CLUSTER_CHANGE_NODE_STATE
(0x00000001) 		The queue receives a notification when a node changes state. For a list of possible node state values, see GetClusterNodeState.
CLUSTER_CHANGE_QUORUM_STATE
(0x10000000) 		This notification is reserved for future use.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES
(0x00000020) 		The queue receives a notification when a cluster database key's attributes are changed. The only currently defined cluster database key attribute is its security descriptor, which can be changed with ClusterRegSetKeySecurity.
CLUSTER_CHANGE_REGISTRY_NAME
(0x00000010) 		The queue receives a notification when the name of a cluster database key has changed.
CLUSTER_CHANGE_REGISTRY_SUBTREE
(0x00000080) 		Indicates that the other CLUSTER_CHANGE_REGISTRY events apply to the entire cluster database. If this flag is not included, the events apply only to the specified key.
CLUSTER_CHANGE_REGISTRY_VALUE
(0x00000040) 		The queue receives a notification when a value of the specified cluster database key is changed or deleted. Cluster database values can be changed with the ClusterRegSetValue function and deleted with the ClusterRegDeleteValue function.
CLUSTER_CHANGE_RESOURCE_ADDED
(0x00000400) 		The queue receives a notification when a new resource is created in the cluster.
CLUSTER_CHANGE_RESOURCE_DELETED
(0x00000200) 		The queue receives a notification when a resource is deleted.
CLUSTER_CHANGE_RESOURCE_PROPERTY
(0x00000800) 		The queue receives a notification when the properties, dependencies, or possible owner nodes of a resource change.
CLUSTER_CHANGE_RESOURCE_STATE
(0x00000100) 		The queue receives a notification when a resource changes state. For a list of the possible resource state values, see GetClusterResourceState.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED
(0x00020000) 		The queue receives a notification when a new resource type is created in the cluster.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED
(0x00010000) 		The queue receives a notification when an existing resource type is deleted.
CLUSTER_CHANGE_RESOURCE_TYPE_PROPERTY
(0x00040000) 		The queue receives a notification when the properties of a resource type change.

dwNotifyKey
[in] A user-specified value to be associated with retrieving notifications from the notification port. The dwNotifyKey is returned from GetClusterNotify when an event of one of the types specified in dwFilter occurs.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterNotifyPort returns a notification port handle.

Remarks

For more information on using the CreateClusterNotifyPort, GetClusterNotify, and RegisterClusterNotify, functions, see Receiving Cluster Events.

Example

See the Notification Port Example.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterGroupState, GetClusterNetInterfaceState, GetClusterNetworkState, GetClusterNodeState, GetClusterNotify, GetClusterResourceState, GetLastError, RegisterClusterNotify


GetClusterInformation

The GetClusterInformation function retrieves a cluster's name and version.

DWORD WINAPI GetClusterInformation(
  HCLUSTER hCluster,
  LPWSTR lpszClusterName,
  LPDWORD lpcchClusterName,
  LPCLUSTERVERSIONINFO lpClusterInfo
);

Parameters

hCluster
[in] Handle to a cluster.
lpszClusterName
[out] Pointer to a null-terminated Unicode string containing the name of the cluster identified by hCluster.
lpcchClusterName
[in, out] Pointer to the size of the lpszClusterName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
lpClusterInfo
[out] Either NULL or a pointer to a CLUSTERVERSIONINFO structure describing the version of the Cluster service. When lpClusterInfo is not NULL, the dwVersionInfoSize member of this structure should be set as follows:
lpClusterInfo->dwVersionInfoSize =
sizeof(CLUSTERVERSIONINFO);

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_MORE_DATA | The buffer pointed to by lpszClusterName is not big enough to hold the result. The lpcchClusterName parameter returns the number of characters in the result, excluding the terminating NULL.

If the operation was not successful for a reason other than insufficient size in the buffer pointed to by lpszClusterName, GetClusterInformation returns a Win32 error value.

Remarks

Note that lpcchClusterName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CLUSTERVERSIONINFO


GetClusterNotify

The GetClusterNotify function returns information relating to the next notification event stored for a notification port.

DWORD WINAPI GetClusterNotify(
  HCHANGE hChange,
  DWORD_PTR* lpdwNotifyKey,
  LPDWORD lpdwFilterType,
  LPWSTR lpszName,
  LPDWORD lpcchName,
  DWORD dwMilliseconds
);

Parameters

hChange
[in] Handle to a notification port created with the CreateClusterNotifyPort function.
lpdwNotifyKey
[out] Pointer to the notification key for the port identified by hChange.
lpdwFilterType
[out] Pointer to a flag indicating the type of returned event. This flag is one of the following.
Flag Event
CLUSTER_CHANGE_CLUSTER_PROPERTY
(0x40000000) 		The queue receives a notification when the cluster's prioritized list of internal networks changes.
CLUSTER_CHANGE_CLUSTER_STATE
(0x20000000) 		The queue receives a notification when the cluster becomes unavailable, meaning that all attempts to communicate with the cluster fail.This notification is reserved for future use.
CLUSTER_CHANGE_GROUP_ADDED
(0x00004000) 		The queue receives a notification when a new group is created in the cluster.
CLUSTER_CHANGE_GROUP_DELETED
(0x00002000) 		The queue receives a notification when an existing group is deleted.
CLUSTER_CHANGE_GROUP_PROPERTY
(0x00008000) 		The queue receives a notification when the properties of a group change or when a resource is added or removed from a group.
CLUSTER_CHANGE_GROUP_STATE
(0x00001000) 		The queue receives a notification when a group changes state. For a list of the possible group state values, see GetClusterGroupState.
CLUSTER_CHANGE_HANDLE_CLOSE
(0x80000000) 		The queue receives a notification when a handle associated with a cluster object is closed.
CLUSTER_CHANGE_NETINTERFACE_ADDED
(0x04000000) 		The queue receives a notification when a new network interface is added to a cluster node.
CLUSTER_CHANGE_NETINTERFACE_DELETED
(0x02000000) 		The queue receives a notification when a network interface is permanently removed from a cluster node.
CLUSTER_CHANGE_NETINTERFACE_PROPERTY
(0x08000000) 		The queue receives a notification when the properties of an existing network interface change.
CLUSTER_CHANGE_NETINTERFACE_STATE
(0x01000000) 		The queue receives a notification when a network interface changes state. For a list of the possible network interface state values, see GetClusterNetInterfaceState.
CLUSTER_CHANGE_NETWORK_ADDED
(0x00400000) 		The queue receives a notification when a new network is added to the cluster environment.
CLUSTER_CHANGE_NETWORK_DELETED
(0x00200000) 		The queue receives a notification when a network is permanently removed from the cluster environment.
CLUSTER_CHANGE_NETWORK_PROPERTY
(0x00800000) 		The queue receives a notification when the properties of an existing network change.
CLUSTER_CHANGE_NETWORK_STATE
(0x00100000) 		The queue receives a notification when a network changes state. For a list of the possible network state values, see GetClusterNetworkState.
CLUSTER_CHANGE_NODE_ADDED
(0x00000004) 		The queue receives a notification when a new node is added to the cluster. A node can be added only when the Cluster service is initially installed on the node.
CLUSTER_CHANGE_NODE_DELETED
(0x00000002) 		The queue receives a notification when a node is permanently removed from a cluster. A node can be permanently deleted from an existing cluster with a call to the EvictClusterNode function.
CLUSTER_CHANGE_NODE_PROPERTY
(0x00000008) 		This notification is reserved for future use.
CLUSTER_CHANGE_NODE_STATE
(0x00000001) 		The queue receives a notification when a node changes state. For a list of possible node state values, see GetClusterNodeState.
CLUSTER_CHANGE_QUORUM_STATE
(0x10000000) 		This notification is reserved for future use.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES
(0x00000020) 		The queue receives a notification when a cluster database key's attributes are changed. The only currently defined cluster database key attribute is its security descriptor, which can be changed with ClusterRegSetKeySecurity.
CLUSTER_CHANGE_REGISTRY_NAME
(0x00000010) 		The queue receives a notification when the name of a cluster database key has changed.
CLUSTER_CHANGE_REGISTRY_SUBTREE
(0x00000080) 		Indicates that the other CLUSTER_CHANGE_REGISTRY events apply to the entire cluster database. If this flag is not included, the events apply only to the specified key.
CLUSTER_CHANGE_REGISTRY_VALUE
(0x00000040) 		The queue receives a notification when a value of the specified cluster database key is changed or deleted. Cluster database values can be changed with the ClusterRegSetValue function and deleted with the ClusterRegDeleteValue function.
CLUSTER_CHANGE_RESOURCE_ADDED
(0x00000400) 		The queue receives a notification when a new resource is created in the cluster.
CLUSTER_CHANGE_RESOURCE_DELETED
(0x00000200) 		The queue receives a notification when a resource is deleted.
CLUSTER_CHANGE_RESOURCE_PROPERTY
(0x00000800) 		The queue receives a notification when the properties, dependencies, or possible owner nodes of a resource change.
CLUSTER_CHANGE_RESOURCE_STATE
(0x00000100) 		The queue receives a notification when a resource changes state. For a list of the possible resource state values, see GetClusterResourceState.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED
(0x00020000) 		The queue receives a notification when a new resource type is created in the cluster.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED
(0x00010000) 		The queue receives a notification when an existing resource type is deleted.
CLUSTER_CHANGE_RESOURCE_TYPE_PROPERTY
(0x00040000) 		The queue receives a notification when the properties of a resource type change.

lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the cluster object that triggered the event. The following table describes the content of lpszName by event type. Note that CLUSTER_CHANGE_REGISTRY_SUBTREE is not included in the table; this event type is never handled by GetClusterNotify.
Value of lpdwFilterType | Value of lpszName
CLUSTER_CHANGE_CLUSTER_PROPERTY | Name of the changed cluster.
CLUSTER_CHANGE_CLUSTER_STATE | Name of the changed cluster.
CLUSTER_CHANGE_GROUP_ADDED | New group name.
CLUSTER_CHANGE_GROUP_DELETED | Deleted group name.
CLUSTER_CHANGE_GROUP_PROPERTY | Name of changed group.
CLUSTER_CHANGE_GROUP_STATE | Name of changed group.
CLUSTER_CHANGE_HANDLE_CLOSE | Name of object being closed.
CLUSTER_CHANGE_NODE_ADDED | Name of new node.
CLUSTER_CHANGE_NODE_DELETED | Name of deleted node.
CLUSTER_CHANGE_NODE_PROPERTY | Name of changed node.
CLUSTER_CHANGE_NODE_STATE | Name of changed node.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES | Relative name of changed cluster database key.
CLUSTER_CHANGE_REGISTRY_NAME | Relative name of changed cluster database key.
CLUSTER_CHANGE_REGISTRY_VALUE | Relative name of changed cluster database key.
CLUSTER_CHANGE_RESOURCE_ADDED | New resource name.
CLUSTER_CHANGE_RESOURCE_DELETED | Deleted resource name.
CLUSTER_CHANGE_RESOURCE_PROPERTY | Name of changed resource.
CLUSTER_CHANGE_RESOURCE_STATE | Name of changed resource.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED | Name of new resource type.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED | Name of deleted resource type.

lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
dwMilliseconds
[in] Optional time-out value that specifies how long the caller is willing to wait for the notification.

Return Values

Value | Meaning
ERROR_SUCCESS | The notification was successfully returned.
ERROR_INVALID_HANDLE | The handle represented in the hChange parameter is invalid or has been closed by another thread.
WAIT_TIMEOUT | The call timed out before the notification could be successfully returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

If the notification was not successfully returned, GetClusterNotify returns a Win32 error value. For more information about the error, call the Win32 function GetLastError.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Example

See the Notification Port Example.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CreateClusterNotifyPort, CloseClusterNotifyPort, RegisterClusterNotify, GetLastError


GetClusterQuorumResource

The GetClusterQuorumResource function returns the name of a cluster's quorum resource.

DWORD WINAPI GetClusterQuorumResource(
  HCLUSTER hCluster,
  LPWSTR lpszResourceName,
  LPDWORD lpcchResourceName,
  LPWSTR lpszDeviceName,
  LPDWORD lpcchDeviceName,
  LPDWORD lpdwMaxQuorumLogSize
);

Parameters

hCluster
[in] Handle to an existing cluster.
lpszResourceName
[out] Pointer to a null-terminated Unicode string containing the name of the cluster's quorum resource. The name is read from the quorum resource's Name common property. Do not pass NULL for this parameter.
lpcchResourceName
[in, out] Pointer to the size of the lpszResourceName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
lpszDeviceName
[out] Pointer to a null-terminated Unicode string containing the path to the location of the quorum log files maintained by the Cluster service. Do not pass NULL for this parameter.
lpcchDeviceName
[in, out] Pointer to the size of the lpszDeviceName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
lpdwMaxQuorumLogSize
[out] Pointer to the maximum size (in bytes) of the log being maintained by the quorum resource. Do not pass NULL for this parameter.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_MORE_DATA | The lpszResourceName or the lpszDeviceName buffer is not big enough to hold the result. The lpcchResourceName and lpcchDeviceName parameters return the number of characters in the result, excluding the terminating NULL.

If the operation was not successful, GetClusterQuorumResource can also return a Win32 error value.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

SetClusterQuorumResource, Name


OpenCluster

The OpenCluster function opens a connection to a cluster and returns a handle to it.

HCLUSTER WINAPI OpenCluster(
  LPCWSTR lpszClusterName
);

Parameters

lpszClusterName
[in] Specifies one of the following values:
  • Pointer to a null-terminated Unicode string containing the name of the cluster or one of the cluster nodes expressed as a NetBIOS name, a fully-qualified DNS name, or an IP address. This produces an RPC cluster handle.
  • NULL, which produces an LPC handle to the cluster to which the local computer belongs.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenCluster returns a cluster handle.

Remarks

A cluster handle is a pointer to an internally-defined structure which stores information about the RPC or LPC connection to the cluster. Any object handles obtained from the cluster handle will be associated with the RPC or LPC session data stored in the cluster structure. Combining RPC and LPC handles or using handles obtained from different contexts can cause exceptions or other unpredictable results. For more information, see LPC and RPC Handles.

When finished with a cluster handle, it is important to call CloseCluster to ensure that all memory is freed and the connection is shut down cleanly.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CloseCluster, GetLastError


RegisterClusterNotify

The RegisterClusterNotify function adds an event type to the list of events stored for a notification port.

DWORD WINAPI RegisterClusterNotify(
  HCHANGE hChange,
  DWORD dwFilter,
  HANDLE hObject,
  DWORD_PTR dwNotifyKey
);

Parameters

hChange
[in] Handle to a notification port created with the CreateClusterNotifyPort function.
dwFilter
[in] Bitmask of flags that describes the event to be added to the set of events currently being monitored by the notification port. For more information about these event types, see CreateClusterNotifyPort. The dwFilter parameter can be set to one of the following flags.
Value Description
CLUSTER_CHANGE_CLUSTER_PROPERTY
(0x40000000) 		The queue receives a notification when the cluster's prioritized list of internal networks changes.
CLUSTER_CHANGE_CLUSTER_STATE
(0x20000000) 		The queue receives a notification when the cluster becomes unavailable, meaning that all attempts to communicate with the cluster fail.This notification is reserved for future use.
CLUSTER_CHANGE_GROUP_ADDED
(0x00004000) 		The queue receives a notification when a new group is created in the cluster.
CLUSTER_CHANGE_GROUP_DELETED
(0x00002000) 		The queue receives a notification when an existing group is deleted.
CLUSTER_CHANGE_GROUP_PROPERTY
(0x00008000) 		The queue receives a notification when the properties of an existing group change.
CLUSTER_CHANGE_GROUP_STATE
(0x00001000) 		The queue receives a notification when a group changes state.
CLUSTER_CHANGE_HANDLE_CLOSE
(0x80000000) 		The queue receives a notification when a handle to a cluster object isclosed.
CLUSTER_CHANGE_NETINTERFACE_ADDED
(0x04000000) 		The queue receives a notification when a new network interface is added to a cluster node.
CLUSTER_CHANGE_NETINTERFACE_DELETED
(0x02000000) 		The queue receives a notification when a network interface is permanently removed from a cluster node.
CLUSTER_CHANGE_NETINTERFACE_PROPERTY
(0x08000000) 		The queue receives a notification when the properties of an existing network interface change.
CLUSTER_CHANGE_NETINTERFACE_STATE
(0x01000000) 		The queue receives a notification when a network interface changes state. For a list of the possible network interface state values, see GetClusterNetInterfaceState.
CLUSTER_CHANGE_NETWORK_ADDED
(0x00400000) 		The queue receives a notification when a new network is added to the cluster environment.
CLUSTER_CHANGE_NETWORK_DELETED
(0x00200000) 		The queue receives a notification when a network is permanently removed from the cluster environment.
CLUSTER_CHANGE_NETWORK_PROPERTY
(0x00800000) 		The queue receives a notification when the properties of an existing network change.
CLUSTER_CHANGE_NETWORK_STATE
(0x00100000) 		The queue receives a notification when a network changes state. For a list of the possible network state values, see GetClusterNetworkState.
CLUSTER_CHANGE_NODE_ADDED
(0x00000004) 		The queue receives a notification when a new node is added to the cluster. A node can be added only when the Cluster service is initially installed on the node.
CLUSTER_CHANGE_NODE_DELETED
(0x00000002) 		The queue receives a notification when a node is permanently removed from a cluster. A node can be permanently deleted from an existing cluster with a call to the EvictClusterNode function.
CLUSTER_CHANGE_NODE_PROPERTY
(0x00000008) 		The queue receives a notification when the properties of a node change.
CLUSTER_CHANGE_NODE_STATE
(0x00000001) 		The queue receives a notification when a node changes state.
CLUSTER_CHANGE_QUORUM_STATE
(0x10000000) 		The queue receives a notification when the quorum resource changes state.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES
(0x00000020) 		The queue receives a notification when a cluster database key's attributes are changed.
CLUSTER_CHANGE_REGISTRY_NAME
(0x00000010) 		The queue receives a notification when a change to a name is made in the cluster database.
CLUSTER_CHANGE_REGISTRY_SUBTREE
(0x00000080) 		Indicates that the other CLUSTER_CHANGE_REGISTRY events apply to the root of the cluster database and to all of the subkeys. If CLUSTER_CHANGE_REGISTRY_SUBTREE is not specified, the notifications apply only to the root.
CLUSTER_CHANGE_REGISTRY_VALUE
(0x00000040) 		The queue receives a notification when a value of the specified cluster database key is changed or deleted.
CLUSTER_CHANGE_RESOURCE_ADDED
(0x00000400) 		The queue receives a notification when a new resource is created in the cluster.
CLUSTER_CHANGE_RESOURCE_DELETED
(0x00000200) 		The queue receives a notification when a resource is deleted.
CLUSTER_CHANGE_RESOURCE_PROPERTY
(0x00000800) 		Indicates that a notification should be issued when the properties of a resource change.
CLUSTER_CHANGE_RESOURCE_STATE
(0x00000100) 		The queue receives a notification when a resource changes state.
CLUSTER_CHANGE_RESOURCE_TYPE_ADDED
(0x00020000) 		The queue receives a notification when a new resource type is created in the cluster.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED
(0x00010000) 		The queue receives a notification when an existing resource type is deleted.
CLUSTER_CHANGE_RESOURCE_TYPE_PROPERTY
(0x00040000) 		The queue receives a notification when the properties of a resource type change.

hObject
[in] Handle to the server cluster object affected by the event specified in the dwFilter parameter. The type of handle depends on the value of dwFilter as described in the following table.
Value of dwFilter | Value of hObject
CLUSTER_CHANGE_CLUSTER_PROPERTY | HCLUSTER
CLUSTER_CHANGE_CLUSTER_STATE | HCLUSTER
CLUSTER_CHANGE_GROUP_DELETED | HGROUP
CLUSTER_CHANGE_GROUP_PROPERTY | HGROUP
CLUSTER_CHANGE_GROUP_STATE | HGROUP
CLUSTER_CHANGE_HANDLE_CLOSE | HCLUSTER
CLUSTER_CHANGE_NODE_DELETED | HNODE
CLUSTER_CHANGE_NODE_PROPERTY | HNODE
CLUSTER_CHANGE_NODE_STATE | HNODE
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES | HKEY
CLUSTER_CHANGE_REGISTRY_NAME | HKEY
CLUSTER_CHANGE_REGISTRY_SUBTREE | HKEY
CLUSTER_CHANGE_REGISTRY_VALUE | HKEY
CLUSTER_CHANGE_RESOURCE_DELETED | HRESOURCE
CLUSTER_CHANGE_RESOURCE_PROPERTY | HRESOURCE
CLUSTER_CHANGE_RESOURCE_STATE | HRESOURCE

The cluster database functions return a valid cluster database key that can be used to set hObject when dwFilter is set to an event type affecting the cluster database.

dwNotifyKey
[in] Notification key returned from GetClusterNotify when the requested event occurs.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, RegisterClusterNotify returns a Win32 error value.

Remarks

The RegisterClusterNotify function enables an application that has already created a notification port with CreateClusterNotifyPort to register for an additional event that affects a node, resource, or group.

To receive notifications of cluster database changes, one or more of the flags applicable to the database must be set in the dwFilter parameter. Applicable flags start with the prefix CLUSTER_CHANGE_REGISTRY. Making manual changes to the cluster database through the registry editor, REGEDT32, does not generate notifications.

Example

See the Notification Port Example.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CreateClusterNotifyPort, GetClusterNotify, CloseClusterNotifyPort


SetClusterName

The SetClusterName function sets the name for a cluster.

DWORD WINAPI SetClusterName(
  HCLUSTER hCluster,
  LPCWSTR lpszNewClusterName
);

Parameters

hCluster
[in] Handle to a cluster to rename.
lpszNewClusterName
[in] Pointer to a null-terminated Unicode string containing the new cluster name.

Return Values

Value | Meaning
ERROR_RESOURCE_PROPERTIES_STORED | The operation was successful.

If the operation was not successful, SetClusterName returns a Win32 error value.

Remarks

The cluster name is stored in the Name private property of the core Network Name resource (that is, the Network Name resource of the cluster). Because of possible dependencies on this resource, the change is not effective until the Network Name resource is brought back online.

Do not call SetClusterName from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Name


SetClusterQuorumResource

The SetClusterQuorumResource function establishes a resource as the quorum resource for a cluster.

DWORD WINAPI SetClusterQuorumResource(
  HRESOURCE hResource,
  LPCWSTR lpszDeviceName,
  DWORD dwMaxQuoLogSize
);

Parameters

hResource
[in] Handle to the new quorum resource.
lpszDeviceName
[in] Determines the drive letter and path that the Cluster service will use to maintain the quorum files on the new quorum resource. Pass a null-terminated Unicode string or NULL, as follows:
  • If you specify a drive letter in the path, the Cluster service will verify that the drive letter refers to a valid partition on the new quorum resource.
  • If you do not specify a drive letter in the path, the Cluster service will use a default partition on the new quorum resource (see below).
  • If NULL, the Cluster service will use a default partition and a default path name (see below).

In all versions of the Cluster service prior to Whistler, the default partition is simply the first available partition on the new quorum resource. This can result in problems if, for example, the first partition is not an NTFS partition.

Whistler: Starting in Whistler, the Cluster service uses the partition flagged as CLUSPROP_PIFLAG_DEFAULT_QUORUM as the default partition (see CLUSPROP_PARTITION_INFO), or, if the flag cannot be found, the first available NTFS partition on the new quorum resource.

For the default path name, the Cluster service uses the previous path name if one exists; otherwise it uses "MSCS".

dwMaxQuoLogSize
[in] Maximum size for the log file to be maintained by the new quorum resource.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_RESOURCE_NOT_ONLINE | The quorum resource is not online.

If the operation was unsuccessful, SetClusterQuorumResource can also return a Win32 error value.

Remarks

Do not call SetClusterQuorumResource from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterQuorumResource


Group Management Functions

The following functions manage cluster groups.

Function | Description
CloseClusterGroup | Closes a group handle.
ClusterGroupCloseEnum | Closes a group enumeration handle.
ClusterGroupControl | Control code function; can perform a variety of operations on groups.
ClusterGroupEnum | Enumerates the resources in a group and/or the nodes that are preferred owners of a group, returning the name of the resource or node with each call.
ClusterGroupOpenEnum | Opens an enumerator for iterating through a group's resources and/or the nodes that are included in its list of preferred owners.
CreateClusterGroup | Adds a group to a cluster and returns a handle to the newly added group.
DeleteClusterGroup | Removes a group from a cluster.
GetClusterFromGroup | Returns a handle to the cluster associated with a group.
GetClusterGroupState | Returns the current state of a group.
MoveClusterGroup | Moves a group and all of its resources from one node to another.
OfflineClusterGroup | Takes an online group offline.
OnlineClusterGroup | Takes an offline group online.
OpenClusterGroup | Opens a group and returns a handle to it.
SetClusterGroupName | Sets the name for a group.
SetClusterGroupNodeList | Sets the preferred node list for a group.


CloseClusterGroup

The CloseClusterGroup function closes a group handle.

BOOL WINAPI CloseClusterGroup(
  HGROUP hGroup
);

Parameters

hGroup
[in] Handle to the group to close.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterGroup


ClusterGroupCloseEnum

The ClusterGroupCloseEnum function closes a group enumeration handle.

DWORD WINAPI ClusterGroupCloseEnum(
  HGROUPENUM hGroupEnum
);

Parameters

hGroupEnum
[in] Enumeration handle to close.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterGroupCloseEnum returns a Win32 error value.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterGroupOpenEnum, ClusterGroupEnum


ClusterGroupEnum

The ClusterGroupEnum function enumerates the resources in a group and/or the nodes that are the preferred owners of a group, returning the name of the resource or node with each call.

DWORD WINAPI ClusterGroupEnum(
  HGROUPENUM hGroupEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszResourceName,
  LPDWORD lpcchName
);

Parameters

hGroupEnum
[in] Group enumeration handle returned by the ClusterGroupOpenEnum function.
dwIndex
[in] Index of the resource or node to return. This parameter should be zero for the first call to ClusterGroupEnum and then incremented for subsequent calls.
lpdwType
[out] Pointer to the type of object returned by ClusterGroupEnum. The following are valid values.
Value | Object returned
CLUSTER_GROUP_ENUM_CONTAINS | The object is one of the resources in the group.
CLUSTER_GROUP_ENUM_NODES | The object is one of the nodes in the preferred owners list of the group.

lpszResourceName
[out] Pointer to a null-terminated Unicode string containing the name of the returned resource or node.
lpcchName
[in, out] Pointer to the size of the lpszResourceName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more resources or nodes to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszResourceName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

If the operation was not successful due to a problem other than those described with the ERROR_NO_MORE_ITEMS or ERROR_MORE_DATA values, ClusterGroupEnum returns a Win32 error value.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Do not call ClusterGroupEnum from any resource DLL entry point function. ClusterGroupEnum can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterGroupCloseEnum, ClusterGroupOpenEnum


ClusterGroupOpenEnum

The ClusterGroupOpenEnum function opens an enumerator for iterating through a group's resources and/or the nodes that are included in its list of preferred owners.

HGROUPENUM WINAPI ClusterGroupOpenEnum(
  HGROUP hGroup,
  DWORD dwType
);

Parameters

hGroup
[in] Handle to the group to be enumerated.
dwType
[in] Bitmask describing the cluster objects to be enumerated. The following are valid values.
Value | Objects to be enumerated
CLUSTER_GROUP_ENUM_CONTAINS | Enumerates the resources in the group.
CLUSTER_GROUP_ENUM_NODES | Enumerates the nodes in the preferred owners list of the group.
CLUSTER_GROUP_ENUM_ALL | Enumerates the resources in the group and the perferred owners of the group.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, ClusterGroupOpenEnum returns a handle to an enumerator that can be passed to the ClusterGroupEnum function.

Remarks

Do not call ClusterGroupOpenEnum from any resource DLL entry point function. ClusterGroupOpenEnum can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterGroupCloseEnum, ClusterGroupEnum, GetLastError, OpenClusterGroup


CreateClusterGroup

The CreateClusterGroup function adds a group to a cluster and returns a handle to the newly added group.

HGROUP WINAPI CreateClusterGroup(
  HCLUSTER hCluster,
  LPCWSTR lpszGroupName
);

Parameters

hCluster
[in] Handle to the target cluster.
lpszGroupName
[in] Pointer to a null-terminated Unicode string containing the name of the group to be added to the cluster identified by hCluster. If there is not a group by this name, CreateClusterGroup creates it.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterGroup returns a group handle.

Remarks

Do not call CreateClusterGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Example

See Creating Groups.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterGroup


DeleteClusterGroup

The DeleteClusterGroup function removes a group from a cluster.

DWORD WINAPI DeleteClusterGroup(
  HGROUP hGroup
);

Parameters

hGroup
[in] Handle to the group to be removed. You must close this handle separately.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, DeleteClusterGroup returns a Win32 error value.

Remarks

Because the DeleteClusterGroup function only removes groups that are empty, a group must not have any resources if it is to be successfully deleted.

DeleteClusterGroup does not close the group handle specified by hGroup. To avoid memory leaks, be sure to close this handle with CloseClusterGroup.

Do not call DeleteClusterGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterGroup, CloseClusterGroup, CreateClusterGroup


GetClusterFromGroup

The GetClusterFromGroup function returns a handle to the cluster associated with a group.

HCLUSTER WINAPI GetClusterFromGroup(
  IN HGROUP hGroup
);

Parameters

hGroup
[in] Handle to the group.

Return Values

If the operation was successful, GetClusterFromGroup returns a handle to the cluster that owns the group. Otherwise, it returns the following error code.

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

For hGroup to be a valid handle, there must necessarily be an open cluster handle (see OpenClusterGroup). GetClusterFromGroup returns another instance of the handle from which hGroup was obtained.

Be sure to call CloseCluster on the handle returned from GetClusterFromGroup before the handle goes out of scope. Closing this handle does not invalidate hGroup or the cluster handle from which hGroup was obtained.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterFromNetwork, GetClusterFromNetInterface, GetClusterFromNode, GetClusterFromResource, CloseCluster, OpenCluster, OpenClusterGroup


GetClusterGroupState

The GetClusterGroupState function returns the current state of a group.

CLUSTER_GROUP_STATE WINAPI GetClusterGroupState(
  HGROUP hGroup,
  LPWSTR lpszNodeName,
  LPDWORD lpcchNodeName
);

Parameters

hGroup
[in] Handle to the group for which state information should be returned.
lpszNodeName
[out] Pointer to a null-terminated Unicode string containing the name of the node that currently owns the group.
lpcchNodeName
[in, out] Pointer to the size of the lpszNodeName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

GetClusterGroupState returns the current state of the group, which is represented by one of the following values.

State | Description
ClusterGroupFailed | At least one resource in the group has failed.
ClusterGroupPending | At least one resource in the group is in a pending state. There are no failed resources.
ClusterGroupOnline | All of the resources in the group are online.
ClusterGroupPartialOnline | At least one resource in the group is online. No resources are pending or failed.
ClusterGroupOffline | All of the resources in the group are offline or there are no resources in the group.
ClusterGroupStateUnknown | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Do not call GetClusterGroupState from any resource DLL entry point function. GetClusterGroupState can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterGroup


MoveClusterGroup

The MoveClusterGroup function moves a group and all of its resources from one node to another.

DWORD WINAPI MoveClusterGroup(
  HGROUP hGroup,
  HNODE hDestinationNode
);

Parameters

hGroup
[in] Handle to the group to be moved.
hDestinationNode
[in] Optional handle to the node where the moved group should be brought back online or NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The reassignment of ownership of the group is complete.
ERROR_IO_PENDING | The reassignment of ownership of the group is in progress.

If the operation was not successful, MoveClusterGroup returns a Win32 error value.

Remarks

The return value from the MoveClusterGroup function does not imply anything about the state of the group or any of its resources. The return value only indicates whether the change of ownership was successful. After returning from MoveClusterGroup, the cluster always attempts to return the group to the state it was in prior to the move.

If you want your application to ensure a particular state for a resource or a group after a move:

  1. Check the state prior to the move. The cluster will attempt to restore that state after the move.
  2. Poll for the state after the move and adjust as necessary. Or create a notification port (see Receiving Cluster Events) and wait for a CLUSTER_CHANGE_GROUP_STATE event.

When hDestinationNode is set to NULL, MoveClusterGroup attempts to move the group to the best possible node. If there is no node available that can accept the group, the function fails. MoveClusterGroup also fails if MoveClusterGroup determines that the group cannot be brought online on the node identified by the hDestinationNode parameter.

Do not call MoveClusterGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterGroup, OpenClusterNode, OpenCluster


OfflineClusterGroup

The OfflineClusterGroup function takes a group offline.

DWORD WINAPI OfflineClusterGroup(
  HGROUP hGroup
);

Parameters

hGroup
[in] Handle to the group to be taken offline.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_IO_PENDING | The operation is in progress.

If the operation was not successful, OfflineClusterGroup returns a Win32 error value.

Remarks

Do not call OfflineClusterGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OnlineClusterGroup, OpenClusterGroup


OnlineClusterGroup

The OnlineClusterGroup function brings a group online.

DWORD WINAPI OnlineClusterGroup(
  HGROUP hGroup,
  HNODE hDestinationNode
);

Parameters

hGroup
[in] Handle to the group to be brought online.
hDestinationNode
[in] Optional handle to the node where the group identified by hGroup should be brought online or NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_HOST_NODE_NOT_AVAILABLE | A suitable host node was not available.
ERROR_IO_PENDING | The operation is in progress.

If the operation was not successful, OnlineClusterGroup can return a Win32 error value.

Remarks

If the group cannot be brought online on the node identified by the hDestinationNode parameter, the OnlineClusterGroup function fails.

If the hDestinationNode parameter is set to NULL, OnlineClusterGroup brings the group online on the current node.

Do not call OnlineClusterGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OfflineClusterGroup, OpenClusterGroup, OpenCluster


OpenClusterGroup

The OpenClusterGroup function opens a group and returns a handle to it.

HGROUP WINAPI OpenClusterGroup(
  HCLUSTER hCluster,
  LPCWSTR lpszGroupName
);

Parameters

hCluster
[in] Handle to a cluster that includes the group to open.
lpszGroupName
[in] Name of the group to open.

Return Values

Value | Meaning
NULL | The operation was not successful. For information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterGroup returns a group handle.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CloseClusterGroup


SetClusterGroupName

The SetClusterGroupName function sets the name for a group.

DWORD WINAPI SetClusterGroupName(
  HGROUP hGroup,
  LPCWSTR lpszGroupName
);

Parameters

hGroup
[in] Handle to the group to name.
lpszGroupName
[in] Pointer to the new name for the group identified by hGroup.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, SetClusterGroupName returns a Win32 error value.

Remarks

SetClusterGroupName changes the Name common property of the group identified by hGroup. This is the only way that Name, a read-only property, can be changed.

Do not call SetClusterGroupName from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Name, OpenClusterGroup


SetClusterGroupNodeList

The SetClusterGroupNodeList function sets the preferred node list for a group.

DWORD WINAPI SetClusterGroupNodeList(
  HGROUP hGroup,
  DWORD cNodeCount,
  HNODE phNodeList[]
);

Parameters

hGroup
[in] Handle to the group to be assigned the list of nodes.
cNodeCount
[in] Count of nodes in the list identified by phNodeList.
phNodeList
[in] Array of handles to nodes, in order by preference, with the first node being the most preferred and the last node the least preferred. The number of nodes in the phNodeList array is controlled by the cNodeCount parameter.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, SetClusterGroupNodeList returns a Win32 error value.

Remarks

Do not call SetClusterGroupNodeList from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenCluster, OpenClusterGroup, OpenClusterNode


Network Management Functions

The following functions manage cluster networks.

Function | Description
CloseClusterNetwork | Closes a network handle.
ClusterNetworkCloseEnum | Closes an enumerator for iterating through cluster objects on a network.
ClusterNetworkControl | Control code function; can perform a variety of operations on networks.
ClusterNetworkEnum | Enumerates objects on a network, returning the name of one object with each call.
ClusterNetworkOpenEnum | Opens an enumerator for iterating through objects on a network.
GetClusterFromNetwork | Returns a handle to the cluster associated with a network.
GetClusterNetworkId | Returns the identifier of a network.
GetClusterNetworkState | Returns the current state of a network.
OpenClusterNetwork | Opens a connection to a network and returns a handle to it.
SetClusterNetworkName | Sets the name for a network.
SetClusterNetworkPriorityOrder | Sets the priority order for the networks used for internal communication.


CloseClusterNetwork

The CloseClusterNetwork function closes a network handle.

BOOL WINAPI CloseClusterNetwork(
  HNETWORK hNetwork
);

Parameters

hNetwork
[in] Handle to the network to close.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful; call the Win32 function GetLastError for more information.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenClusterNetwork


ClusterNetworkCloseEnum

The ClusterNetworkCloseEnum function closes a network enumeration handle.

DWORD WINAPI ClusterNetworkCloseEnum(
  HNETWORKENUM hNetworkEnum
);

Parameters

hNetworkEnum
[in] Handle to the network enumerator to close. This is a handle originally returned by the ClusterNetworkOpenEnum function.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterNetworkCloseEnum returns a Win32 error value.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterNetworkOpenEnum, ClusterNetworkEnum


ClusterNetworkEnum

The ClusterNetworkEnum function enumerates cluster objects on a network, returning the name of one object with each call.

DWORD WINAPI ClusterNetworkEnum(
  HNETWORKENUM hNetworkEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszName,
  LPDWORD lpcchName
);

Parameters

hNetworkEnum
[in] Handle to an existing enumeration object originally returned by the ClusterNetworkOpenEnum function.
dwIndex
[in] Index used to identify the next entry to be enumerated. This parameter should be zero for the first call to ClusterNetworkEnum and then incremented for subsequent calls.
lpdwType
[out] Pointer to the type of object returned. The following object type information is returned with each call:
CLUSTER_NETWORK_ENUM_NETINTERFACES
The object is a network interface.
lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the returned object.
lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more objects of the requested type to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

Remarks

The ClusterNetworkEnum function is typically used to iterate through a collection of objects of one or more types belonging to a network object. If, for example, an application wants to enumerate all of the network interface objects on a network, it calls ClusterNetworkOpenEnum to open a network enumerator that can process network interface objects. The dwType parameter is set to CLUSTER_NETWORK_ENUM_NETINTERFACES to specify network interfaces as the object type to be enumerated. With the handle that ClusterNetworkOpenEnum returns, the application calls ClusterNetworkEnum repeatedly to retrieve each of the objects. The lpdwType parameter points to the type of object that is retrieved.

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterNetworkOpenEnum, ClusterNetworkCloseEnum


ClusterNetworkOpenEnum

The ClusterNetworkOpenEnum function opens an enumerator for iterating through objects on a network.

HNETWORKENUM WINAPI ClusterNetworkOpenEnum(
  HNETWORK hNetwork,
  DWORD dwType
);

Parameters

hNetwork
[in] Handle to a network.
dwType
[in] Bitmask describing the type of objects to be enumerated. One or more of the following values are valid.
State | Description
CLUSTER_NETWORK_ENUM_NETINTERFACES | Enumerate the network interface objects on the network.
CLUSTER_NETWORK_ENUM_ALL | Enumerate all objects on the network.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, ClusterNetworkOpenEnum returns a handle to a network enumerator.

Remarks

Applications call the ClusterNetworkOpenEnum function to create a particular type of enumerator. ClusterNetworkOpenEnum can create enumerators for iterating through all of the objects on a network or only the network interface objects. ClusterNetworkOpenEnum returns a handle that can be passed to ClusterNetworkEnum to access each of the objects to be enumerated and to ClusterNetworkCloseEnum to release the enumerator.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterNetworkCloseEnum, ClusterNetworkEnum, GetLastError, OpenClusterNetwork


GetClusterFromNetwork

The GetClusterFromNetwork function returns a handle to the cluster associated with a network.

HCLUSTER WINAPI GetClusterFromNetwork(
  IN HNETWORK hNetwork
);

Parameters

hNetwork
[in] Handle to the network.

Return Values

If the operation was successful, GetClusterFromNetwork returns a handle to the cluster that owns the network. Otherwise, it returns the following error code.

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

For hNetwork to be a valid handle, there must necessarily be an open cluster handle (see OpenClusterNetwork). GetClusterFromNetwork returns another instance of the handle from which hNetwork was obtained.

Be sure to call CloseCluster on the handle returned from GetClusterFromNetwork before the handle goes out of scope. Closing this handle does not invalidate hNetwork or the cluster handle from which hNetwork was obtained.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterFromGroup , GetClusterFromNetInterface, GetClusterFromNode, GetClusterFromResource, CloseCluster, OpenCluster, OpenClusterNetwork, CloseClusterNetwork


GetClusterNetworkId

The GetClusterNetworkId function returns the identifier of a network.

DWORD WINAPI GetClusterNetworkId(
  HNETWORK hNetwork,
  LPWSTR lpszNetworkId,
  LPDWORD lpcchNetworkId
);

Parameters

hNetwork
[in] Handle to a network.
lpszNetworkId
[out] Pointer to the identifier of the network associated with hNetwork, including the null-terminating character.
lpcchNetworkId
[in, out] Pointer to the size of the lpszNetworkID buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_MORE_DATA | The buffer pointed to by lpszNetworkId is not big enough to hold the result. The lpcchNetworkID parameter returns the number of characters in the result, excluding the terminating NULL.

If the operation was not successful for a reason other than insufficient size in the buffer pointed to by lpszNetworkId, GetClusterNetworkId returns a Win32 error value.

Remarks

Note that lpcchNetworkID refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterNetwork


GetClusterNetworkState

The GetClusterNetworkState function returns the current state of a network.

CLUSTER_NETWORK_STATE WINAPI GetClusterNetworkState(
  HNETWORK hNetwork
);

Parameters

hNetwork
[in] Handle to the network for which state information should be returned.

Return Values

GetClusterNetworkState returns the current state of the network, which is represented by one of the following values.

State | Description
ClusterNetworkUnavailable | All of the network interfaces on the network are unavailable, which means that the nodes that own the network interfaces are down.
ClusterNetworkDown | The network is not operational; none of the nodes on the network can communicate.
ClusterNetworkPartitioned | The network is operational, but two or more nodes on the network cannot communicate. Typically a path-specific problem has occurred.
ClusterNetworkUp | The network is operational; all of the nodes in the cluster can communicate.
ClusterNetworkStateUnknown | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenClusterNetwork


OpenClusterNetwork

The OpenClusterNetwork function opens a connection to a network and returns a handle to it.

HNETWORK WINAPI OpenClusterNetwork(
  HCLUSTER hCluster,
  LPCWSTR lpszNetworkName
);

Parameters

hCluster
[in] Handle to a cluster.
lpszNetworkName
[in] Pointer to the name of an existing network.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterNetwork returns a network handle.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CloseClusterNetwork, GetLastError


SetClusterNetworkName

The SetClusterNetworkName function sets the name for a network.

DWORD WINAPI SetClusterNetworkName(
  HNETWORK hNetwork,
  LPCWSTR lpszName
);

Parameters

hNetwork
[in] Handle to a network to name.
lpszName
[in] Pointer to a null-terminated Unicode string containing the new network name.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, SetClusterNetworkName returns a Win32 error value. For more information about the error, call the Win32 function GetLastError.

Remarks

SetClusterNetworkName changes the Name common property of the network identified by hNetwork. This is the only way that Name, a read-only property, can be changed.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, Name, OpenClusterNetwork


SetClusterNetworkPriorityOrder

The SetClusterNetworkPriorityOrder function sets the priority order for the set of networks used for internal communication between cluster nodes.

DWORD WINAPI SetClusterNetworkPriorityOrder(
  HCLUSTER hCluster,
  DWORD NetworkCount,
  HNETWORK NetworkList[]
);

Parameters

hCluster
[in] Handle to the cluster to be affected.
NetworkCount
[in] Number of items in the list specified by the NetworkList parameter.
NetworkList
[in] Prioritized array of handles to network objects. The first handle in the array has the highest priority. The list must contain only those networks that are used for internal communication between nodes in the cluster, and there can be no duplicates.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NOT_ENOUGH_MEMORY | The operation was not successful due to insufficient memory.
ERROR_INVALID_PARAMETER | There was a duplicate network in NetworkList.

If the operation was not successful, SetClusterNetworkPriorityOrder can also return a Win32 error value.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterEnum, OpenClusterNetwork, OpenCluster


Network Interface Management Functions

The following functions manage network interfaces.

Function | Description
CloseClusterNetInterface | Closes a network interface handle.
ClusterNetInterfaceControl | Control code function; can perform a variety of operations on network interfaces.
GetClusterFromNetInterface | Returns a handle to the cluster associated with a network interface.
GetClusterNetInterface | Returns the name of a node's interface to a network in a cluster.
GetClusterNetInterfaceState | Returns the current state of a network interface.
OpenClusterNetInterface | Opens a handle to a network interface.


CloseClusterNetInterface

The CloseClusterNetInterface function closes a network interface handle.

BOOL WINAPI CloseClusterNetInterface(
  HNETINTERFACE hNetInterface
);

Parameters

hNetInterface
[in] Handle of the network interface to close.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful; call the Win32 function GetLastError for more information.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenClusterNetInterface


GetClusterFromNetInterface

The GetClusterFromNetInterface function returns a handle to the cluster associated with a network interface.

HCLUSTER WINAPI GetClusterFromNetInterface(
  IN HNETINTERFACE hNetInterface
);

Parameters

hNetInterface
[in] Handle to the network interface.

Return Values

If the operation was successful, GetClusterFromNetInterface returns a handle to the cluster that owns the network interface. Otherwise, it returns the following error code.

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

For hNetInterface to be a valid handle, there must necessarily be an open cluster handle (see OpenClusterNetInterface). GetClusterFromNetInterface returns another instance of the handle from which hNetInterface was obtained.

Be sure to call CloseCluster on the handle returned from GetClusterFromNetInterface before the handle goes out of scope. Closing this handle does not invalidate hNetInterface or the cluster handle from which hNetInterface was obtained.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterFromGroup , GetClusterFromNetwork, GetClusterFromNode, GetClusterFromResource CloseCluster, OpenCluster, OpenClusterNetInterface, CloseClusterNetInterface


GetClusterNetInterface

The GetClusterNetInterface function returns the name of a node's interface to a network in a cluster.

DWORD WINAPI GetClusterNetInterface(
  HCLUSTER hCluster,
  LPCWSTR lpszNodeName,
  LPCWSTR lpszNetworkName,
  LPWSTR lpszInterfaceName,
  LPDWORD lpcchInterfaceName
);

Parameters

hCluster
[in] Handle to a cluster.
lpszNodeName
[in] Pointer to a null-terminated Unicode string containing the name of the node in the cluster.
lpszNetworkName
[in] Pointer to a null-terminated Unicode string containing the name of the network.
lpszInterfaceName
[out] Pointer to an output buffer holding the name of the network interface.
lpcchInterfaceName
[in, out] Pointer to the size of the lpszInterfaceName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The network interface name was returned successfully.
ERROR_MORE_DATA | The buffer pointed to by lpszInterfaceName is not big enough to hold the result. The lpcchInterfaceName parameter returns the number of characters in the result, excluding the terminating NULL.

If the operation was not successful, GetClusterNetInterface can also return a Win32 error.

Remarks

Note that lpcchInterfaceName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenCluster


GetClusterNetInterfaceState

The GetClusterNetInterfaceState function returns the current state of a network interface.

CLUSTER_NETINTERFACE_STATE WINAPI GetClusterNetInterfaceState(
  HNETINTERFACE hNetInterface
);

Parameters

hNetInterface
[in] Handle to the network interface for which state information should be returned.

Return Values

GetClusterNetInterfaceState returns the current state of the network interface, which is represented by one of the following values.

State | Description
ClusterNetInterfaceFailed | The network interface cannot communicate with any other network interface.
ClusterNetInterfaceUnreachable | The network interface cannot communicate with at least one other network interface whose state is not ClusterNetInterfaceFailed or ClusterNetInterfaceUnavailable.
ClusterNetInterfaceUp | The network interface can communicate with all other network interfaces whose state is not ClusterNetInterfaceFailed or ClusterNetInterfaceUnavailable.
ClusterNetInterfaceUnavailable | The node that owns the network interface is down.
ClusterNetInterfaceStateUnknown | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenClusterNetInterface


OpenClusterNetInterface

The OpenClusterNetInterface function opens a handle to a network interface.

HNETINTERFACE WINAPI OpenClusterNetInterface(
  HCLUSTER hCluster,
  LPCWSTR lpszInterfaceName
);

Parameters

hCluster
[in] Handle to a cluster.
lpszInterfaceName
[in] Pointer to a null-terminated Unicode string containing the name of the network interface to open.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterNetInterface returns an open handle to the specified network interface.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CloseClusterNetInterface, GetLastError


Node Management Functions

The following functions manage cluster nodes.

Function | Description
CloseClusterNode | Closes a node handle.
ClusterNodeCloseEnum | Closes a node enumeration handle returned by ClusterNodeOpenEnum.
ClusterNodeControl | Control code function; can perform a variety of operations on nodes.
ClusterNodeEnum | Enumerates the network interfaces installed on a node, returning the name of one object with each call.
ClusterNodeOpenEnum | Opens an enumeration handle for iterating through the network interfaces installed on a node.
EvictClusterNode | Deletes a node from the cluster database.
GetClusterFromNode | Returns a handle to the cluster associated with a node.
GetClusterNodeId | Returns the identifier of a cluster node.
GetClusterNodeState | Returns the current state of a node.
GetNodeClusterState | Determines whether the Cluster service is installed and running on a node.
OpenClusterNode | Opens a node and returns a handle to it.
PauseClusterNode | Requests that a node temporarily suspend its cluster activity.
ResumeClusterNode | Requests that a node resume its cluster activity following a temporary suspension.


CloseClusterNode

The CloseClusterNode function closes a node handle.

BOOL WINAPI CloseClusterNode(
  HNODE hNode
);

Parameters

hNode
[in] Handle to an existing node.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterNode, GetLastError


ClusterNodeCloseEnum

The ClusterNodeCloseEnum function closes a node enumeration handle.

DWORD WINAPI ClusterNodeCloseEnum(
  HNODEENUM hNodeEnum
);

Parameters

hNodeEnum
[in] Handle to the node enumerator to close. This is a handle originally returned by the ClusterNodeOpenEnum function.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterNodeCloseEnum returns a Win32 error value.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterNodeOpenEnum, ClusterNodeEnum


ClusterNodeEnum

The ClusterNodeEnum function enumerates the network interfaces installed on a node, returning the name of one network interface with each call.

DWORD WINAPI ClusterNodeEnum(
  HNODEENUM hNodeEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszName,
  LPDWORD lpcchName
);

Parameters

hNodeEnum
[in] Handle to an existing enumeration object originally returned by the ClusterNodeOpenEnum function.
dwIndex
[in] Index used to identify the next entry to be enumerated. This parameter should be zero for the first call to ClusterNodeEnum and then incremented for subsequent calls.
lpdwType
[out] Pointer to the type of object returned. The following object type information is returned with each call:
CLUSTER_NODE_ENUM_NETINTERFACES
The object is a network interface.
lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the returned object.
lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more objects of the requested type to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

Remarks

To use ClusterNodeEnum, applications first open a node enumeration handle by calling ClusterNodeOpenEnum with the dwType parameter set to CLUSTER_NODE_ENUM_NETINTERFACES. For more information, see Enumerating Objects.

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterNodeOpenEnum, ClusterNodeCloseEnum


ClusterNodeOpenEnum

The ClusterNodeOpenEnum function opens an enumerator for iterating through the network interfaces installed on a node.

HNODEENUM WINAPI ClusterNodeOpenEnum(
  HNODE hNode,
  DWORD dwType
);

Parameters

hNode
[in] Handle to a node.
dwType
[in] Bitmask describing the type of objects to be enumerated. The following value is valid:
CLUSTER_NODE_ENUM_NETINTERFACES
Enumerate the network interface objects on the node.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, ClusterNodeOpenEnum returns a handle to a node enumerator.

Remarks

The ClusterNodeOpenEnum function returns a handle that can be passed to ClusterNodeEnum to access each of the objects to be enumerated and to ClusterNodeCloseEnum to release the enumerator.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterNodeCloseEnum, ClusterNodeEnum, GetLastError, OpenClusterNode


EvictClusterNode

The EvictClusterNode function deletes a node from the cluster database.

DWORD WINAPI EvictClusterNode(
  HNODE hNode
);

Parameters

hNode
[in] Handle to the node to delete.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, EvictClusterNode returns a Win32 error value.

Remarks

To reinstate an evicted node, you must first remove the Cluster service from the node and then reinstall it. During installation, choose the Join an Existing Cluster option.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterNode


EvictClusterNodeEx

The EvictClusterNodeEx function evicts a node from the cluster and initiates cleanup operations on the node.

DWORD WINAPI EvictClusterNodeEx(
  IN HNODE hNode,
  IN DWORD dwTimeOut,
  OUT LPDWORD pdwCleanupStatus
);

Parameters

hNode
[in] Handle to the node to remove from the cluster.
dwTimeout
[in] Specifies the number of milliseconds for the function to wait for cleanup operations to occur. The function will return when the cleanup is complete or when the specified time elapses, whichever is sooner.
pdwCleanupStatus
[out] On a successful return, points to a value indicating the results of the cleanup operation. Possible values:
ERROR_SUCCESS
Cleanup operations were successfully completed on the node.
RPC_S_CALL_PENDING
The function timed out before cleanup operations could complete.

If the function is not successful, the value of pdwCleanupStatus is undefined.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, EvictClusterNodeEx returns a Win32 error value.

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterNode, EvictClusterNode


GetClusterFromNode

The GetClusterFromNode function returns a handle to the cluster associated with a node.

HCLUSTER WINAPI GetClusterFromNode(
  IN HNODE hNode
);

Parameters

hNode
[in] Handle to the node.

Return Values

If the operation was successful, GetClusterFromNode returns a handle to the cluster that owns the node. Otherwise, it returns the following error code.

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

For hNode to be a valid handle, there must necessarily be an open cluster handle (see OpenClusterNode). GetClusterFromNode returns another instance of the handle from which hNode was obtained.

Be sure to call CloseCluster on the handle returned from GetClusterFromNode before the handle goes out of scope. Closing this handle does not invalidate hNode or the cluster handle from which hNode was obtained.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterFromGroup, GetClusterFromNetwork, GetClusterFromNetInterface, GetClusterFromResource, CloseCluster, OpenCluster, OpenClusterNode, CloseClusterNode


GetClusterNodeId

The GetClusterNodeId function returns the unique identifier of a cluster node.

DWORD WINAPI GetClusterNodeId(
  HNODE hNode,
  LPWSTR lpszNodeId,
  LPDWORD lpcchNodeId
);

Parameters

hNode
[in] Handle to the node with the identifier to be returned or NULL. If hNode is set to NULL, the node identifier for the node on which the application is running is returned in the content of lpszNodeId.
lpszNodeId
[out] Pointer to the unique identifier of the node represented by hNode.
lpcchNodeId
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszNodeId parameter, including the NULL terminator. On output, pointer to the count of characters stored in the buffer excluding the NULL terminator.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_MORE_DATA | The buffer pointed to by lpszNodeId is not long enough to hold the required number of characters. GetClusterNodeId sets the content of lpcchNodeId to the required length.

If the operation was not successful, GetClusterNodeId returns a Win32 error value.

Remarks

If hNode is set to NULL and the caller is running on an active cluster node, the GetClusterNodeId function returns the identifier of the node on which the application is running. Setting hNode to NULL is a convenient way for resource DLLs to determine the node identifier of the node they are running on.

A cluster node identifier is a unique identifier that does not change even if the node's name is changed.

Note that lpcchNodeID refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterNode


GetClusterNodeState

The GetClusterNodeState function returns the current state of a node.

CLUSTER_NODE_STATE WINAPI GetClusterNodeState(
  HNODE hNode
);

Parameters

hNode
[in] Handle to the node for which state information should be returned.

Return Values

GetClusterNodeState returns the current state of the node, which is represented by one of the following values.

State | Description
ClusterNodeUp | The node is active.
ClusterNodeDown | The node is inactive.
ClusterNodeJoining | The node is in the process of joining a cluster.
ClusterNodePaused | The node has temporarily suspended activity.
ClusterNodeStateUnknown | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

The ClusterNodeDown state only indicates that a node is inactive; it does not specify the reason for the inactivity. A node can be in the ClusterNodeDown state for the following reasons:

  • The node is not running.
  • The Cluster service on the node is not running.
  • The node cannot communicate with the node controlling the quorum resource.
  • The node is inactive for any other reason.

When a node is operating as an active member of a cluster but cannot host any resources or groups, it is in the ClusterNodePaused state (see the PauseClusterNode function). Nodes that are undergoing maintenance are typically placed in this state.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenClusterNode, PauseClusterNode


GetNodeClusterState

The GetNodeClusterState function determines whether the Cluster service is installed and running on a node.

DWORD WINAPI GetNodeClusterState(
  LPCWSTR lpszNodeName,
  DWORD *pdwClusterState
);

Parameters

lpszNodeName
[in] Pointer to a null-terminated Unicode string containing the name of the node to query. If lpszNodeName is NULL, the local node is queried.
pdwClusterState
[out] Pointer to a value describing the state of the Cluster service on the node. A node will be described by one of the following values.
Value | Description
ClusterStateNotInstalled | The Cluster service is not installed on the node.
ClusterStateNotConfigured | The Cluster service is installed on the node but has not yet been configured.
ClusterStateNotRunning | The Cluster service is installed and configured on the node but is not currently running.
ClusterStateRunning | The Cluster service is installed, configured, and running on the node.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, GetNodeClusterState returns a Win32 error value.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.


OpenClusterNode

The OpenClusterNode function opens a node and returns a handle to it.

HNODE WINAPI OpenClusterNode(
  HCLUSTER hCluster,
  LPCWSTR lpszNodeName
);

Parameters

hCluster
[in] Handle to a cluster returned from the OpenCluster function.
lpszNodeName
[in] Pointer to the name of an existing node.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterNode returns a node handle.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, OpenCluster, CloseClusterNode


PauseClusterNode

The PauseClusterNode function requests that a node temporarily suspend its cluster activity.

DWORD WINAPI PauseClusterNode(
  HNODE hNode
);

Parameters

hNode
[in] Handle to the node to suspend activity.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, PauseClusterNode returns a Win32 error value.

Remarks

When a node temporarily suspends its cluster activity, groups cannot be moved to the node. Furthermore, groups that would normally fail over to the node cannot do so when it is in the paused state.

Groups that are owned by a paused node remain owned by the node. A paused node's groups and resources can be taken offline, but they cannot be brought online. Because the paused state is persistent, a paused node that is rebooted continues to be paused when it comes back up.

A paused node is said to be in the ClusterNodePaused state (see GetClusterNodeState). To resume a node's cluster activity, use the ResumeClusterNode function.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterNodeState, OpenClusterNode, ResumeClusterNode


ResumeClusterNode

The ResumeClusterNode function requests that a paused node resume its cluster activity.

DWORD WINAPI ResumeClusterNode(
  HNODE hNode
);

Parameters

hNode
[in] Handle to the paused node.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ResumeClusterNode returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterNode, PauseClusterNode


Resource Management Functions

The following functions manage cluster resources.

Function | Description
AddClusterResourceDependency | Creates a dependency relationship between two resources.
AddClusterResourceNode | Adds a node to the list of possible nodes that a resource can run on.
CanResourceBeDependent | Determines if one resource can be dependent upon another resource.
ChangeClusterResourceGroup | Moves a resource from one group to another.
CloseClusterResource | Closes a resource handle.
ClusterResourceCloseEnum | Closes a resource enumeration handle.
ClusterResourceControl | Control code function; can perform a variety of operations on resources.
ClusterResourceEnum | Enumerates a resource's dependent resources and/or nodes, returning the name of one cluster object with each call.
ClusterResourceOpenEnum | Opens an enumerator for iterating through a resource's dependencies and nodes.
CreateClusterResource | Creates a resource in a cluster.
DeleteClusterResource | Removes an offline resource from a cluster.
FailClusterResource | Initiates a resource failure.
GetClusterFromResource | Returns a handle to the cluster associated with a resource.
GetClusterResourceNetworkName | Retrieves the name of the Network Name resource on which a resource depends.
GetClusterResourceState | Returns the current state of a resource.
OfflineClusterResource | Takes an online resource offline.
OnlineClusterResource | Takes an offline resource online.
OpenClusterResource | Opens a resource and returns a handle to it.
RemoveClusterResourceDependency | Removes a dependency relationship between two resources.
RemoveClusterResourceNode | Removes a node from the list of nodes that can host a resource.
SetClusterResourceName | Sets the name for a resource.


AddClusterResourceDependency

The AddClusterResourceDependency function creates a dependency relationship between two resources.

DWORD WINAPI AddClusterResourceDependency(
  HRESOURCE hResource,
  HRESOURCE hDependsOn
);

Parameters

hResource
[in] Handle to the dependent resource.
hDependsOn
[in] Handle to the resource that the resource identified by hResource should depend on.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, AddClusterResourceDependency returns a Win32 error value.

Remarks

A dependency relationship created by the AddClusterResourceDependency function affects how resources are moved from one node to another after a failure. It determines the order in which resources are taken offline and brought back online.

Resources in a dependency relationship must be moved together. The dependent resource must be brought online after the resource upon which it depends.

The two resources identified by hResource and hDependsOn must be in the same group. Also, if hResource is currently online, hDependsOn must also be currently online.

Do not call AddClusterResourceDependency from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterResource, CanResourceBeDependent, RemoveClusterResourceDependency, OpenCluster


AddClusterResourceNode

The AddClusterResourceNode function adds a node to the list of possible nodes that a resource can run on.

DWORD WINAPI AddClusterResourceNode(
  HRESOURCE hResource,
  HNODE hNode
);

Parameters

hResource
[in] Handle to a resource that will add a node to its possible owners list.
hNode
[in] Handle to the node to be added to the list of potential host nodes belonging to the resource identified by hResource.

Remarks

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, AddClusterResourceNode returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterResource, OpenClusterNode, RemoveClusterResourceNode


CanResourceBeDependent

The CanResourceBeDependent function determines if one resource can be dependent upon another resource.

BOOL WINAPI CanResourceBeDependent(
  HRESOURCE hResource,
  HRESOURCE hResourceDependent
);

Parameters

hResource
[in] Handle to the resource in question.
hResourceDependent
[in] Handle to the resource upon which the resource identified by hResource may depend.

Return Values

Value | Meaning
TRUE | The resource identified by hResource can depend on the resource identified by hResourceDependent.
FALSE | The resource identified by hResource cannot depend on the resource identified by hResourceDependent.

Remarks

With the CanResourceBeDependent function, for the resource identified by hResource to be dependent on the resource identified by hResourceDependent, the following must be true:

  • Both resources must be members of the same group.
  • The resource identified by hResourceDependent cannot depend on the resource identified by hResource, either directly or indirectly.

Do not call CanResourceBeDependent from any resource DLL entry point function. CanResourceBeDependent can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

AddClusterResourceDependency, OpenClusterResource, RemoveClusterResourceDependency


ChangeClusterResourceGroup

The ChangeClusterResourceGroup function moves a resource from one group to another.

DWORD WINAPI ChangeClusterResourceGroup(
  HRESOURCE hResource,
  HGROUP hGroup
);

Parameters

hResource
[in] Handle of the resource to be moved.
hGroup
[in] Handle of the group that should receive the resource identified by hResource.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ChangeClusterResourceGroup returns a Win32 error value.

Remarks

With the ChangeClusterResourceGroup function, both the group that a resource currently belongs to and its new group must be owned by the same node regardless of the resource's state.

Do not call ChangeClusterResourceGroup from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs. If the resource identified by hResource has dependencies, all of the resources in its dependency tree are moved to the group identified by hGroup. For example, in the situation shown in the following diagram, changing resource B to group 2 will move the entire dependency tree (resources A, X, and Y) .

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenCluster, OpenClusterGroup, OpenClusterResource


CloseClusterResource

The CloseClusterResource function closes a resource handle

BOOL WINAPI CloseClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource to be closed.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful. For information about the error, call the Win32 function GetLastError.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetLastError, CreateClusterResource, OpenClusterResource


ClusterResourceCloseEnum

The ClusterResourceCloseEnum function closes a resource enumeration handle.

DWORD WINAPI ClusterResourceCloseEnum(
  HRESENUM hResEnum
);

Parameters

hResEnum
[in] Resource enumeration handle to be closed.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterResourceCloseEnum returns a Win32 error value.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterResourceEnum, ClusterResourceOpenEnum


ClusterResourceEnum

The ClusterResourceEnum function enumerates a resource's dependent resources, nodes, or both. It returns the name of one cluster object with each call.

DWORD WINAPI ClusterResourceEnum(
  HRESENUM hResEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszName,
  LPDWORD lpcchName
);

Parameters

hResEnum
[in] Resource enumeration handle returned from ClusterResourceOpenEnum.
dwIndex
[in] Index of the resource or node object to return. This parameter should be zero for the first call to the ClusterResourceEnum function and then incremented for subsequent calls.
lpdwType
[out] Type of object returned by ClusterResourceEnum. The following are valid values.
Value | Object returned
CLUSTER_RESOURCE_ENUM_DEPENDS | The object is a resource that the resource identified by hResource directly depends on.
CLUSTER_RESOURCE_ENUM_PROVIDES | The object is a resource that depends on the resource identified by hResource.
CLUSTER_RESOURCE_ENUM_NODES | The object is a node that can host the resource identified by hResource.

lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the returned object.
lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more objects to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

If the operation was not successful due to a problem other than not having any more objects to return, ClusterResourceEnum returns a Win32 error value.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Do not call ClusterResourceEnum from any resource DLL entry point function. ClusterResourceEnum can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterResourceCloseEnum, ClusterResourceOpenEnum


ClusterResourceOpenEnum

The ClusterResourceOpenEnum function opens an enumerator for iterating through a resource's dependencies and nodes.

HRESENUM WINAPI ClusterResourceOpenEnum(
  HRESOURCE hResource,
  DWORD dwType
);

Parameters

hResource
[in] Handle to a resource.
dwType
[in] Bitmask describing the type of cluster objects to be enumerated. One or more of the following values are valid.
Value | Objects to be enumerated
CLUSTER_RESOURCE_ENUM_DEPENDS | The object is a resource that the resource identified by hResource directly depends on.
CLUSTER_RESOURCE_ENUM_PROVIDES | The object is a resource that depends on the resource identified by hResource.
CLUSTER_RESOURCE_ENUM_NODES | The object is a node that can host the resource identified by hResource.

Return Values

Value | Meaning
NULL | The operation was not successful. For information about the error, call the Win32 function GetLastError.

If the operation was successful and the returned handle can be passed to ClusterResourceEnum, ClusterResourceOpenEnum returns an enumeration handle.

Remarks

Do not call ClusterResourceOpenEnum from any resource DLL entry point function. ClusterResourceOpenEnum can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterResourceCloseEnum, ClusterResourceEnum


CreateClusterResource

The CreateClusterResource function creates a resource in a cluster.

HRESOURCE WINAPI CreateClusterResource(
  HGROUP hGroup,
  LPCWSTR lpszResourceName,
  LPCWSTR lpszResourceType,
  DWORD dwFlags
);

Parameters

hGroup
[in] Handle to the group that should receive the resource.
lpszResourceName
[in] Pointer to a null-terminated Unicode string containing the name of the new resource. The specified name must be unique within the cluster.
lpszResourceType
[in] Pointer to the type of new resource. The specified type must be installed in the cluster.
dwFlags
[in] Bitmask describing how the resource should be added to the cluster. The dwFlags parameter is optional. If set, the following value is valid:
CLUSTER_RESOURCE_SEPARATE_MONITOR
This resource should be created using a separate resource monitor instead of a resource monitor that is shared.

Return Values

Value | Meaning
NULL | The operation was not successful. For information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterResource returns a resource handle.

Remarks

Do not call CreateClusterResource from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

DeleteClusterResource, OpenClusterGroup


DeleteClusterResource

The DeleteClusterResource function removes an offline resource from a cluster.

DWORD WINAPI DeleteClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to an offline resource. You must close this handle separately.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_RESOURCE_NOT_OFFLINE | The resource identified by hResource is not offline currently.

If the operation was not successful, DeleteClusterResource can return a Win32 error value.

Remarks

DeleteClusterResource does not close the resource handle specified by hResource. To avoid memory leaks, be sure to close this handle with CloseClusterResource.

Do not call DeleteClusterResource from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CreateClusterResource, OpenClusterResource, CloseClusterResource


FailClusterResource

The FailClusterResource function initiates a resource failure.

DWORD WINAPI FailClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource that is the target of the failure.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, FailClusterResource returns a Win32 error value.

Remarks

The resource identified by hResource is treated as inoperable, causing the cluster to initiate the same failover process that would result if the resource had actually failed. Applications call the FailClusterResource function to test their policies for restarting resources and groups.

Do not call FailClusterResource from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterResource


GetClusterFromResource

The GetClusterFromResource function returns a handle to the cluster associated with a resource.

HCLUSTER WINAPI GetClusterFromResource(
  IN HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource.

Return Values

If the operation was successful, GetClusterFromResource returns a handle to the cluster that owns the resource. Otherwise, it returns the following error code.

Value | Meaning
NULL | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

For hResource to be a valid handle, there must necessarily be an open cluster handle (see OpenClusterResource). GetClusterFromResource returns another instance of the handle from which hResource was obtained.

Be sure to call CloseCluster on the handle returned from GetClusterFromResource before the handle goes out of scope. Closing this handle does not invalidate hResource or the cluster handle from which hResource was obtained.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

GetClusterFromGroup, GetClusterFromNetwork, GetClusterFromNetInterface, GetClusterFromNode, CloseCluster, OpenCluster, OpenClusterResource, CloseClusterResource


GetClusterResourceNetworkName

The GetClusterResourceNetworkName function retrieves the name of the Network Name resource on which a resource is dependent.

BOOL WINAPI GetClusterResourceNetworkName(
  HRESOURCE hResource,
  LPWSTR lpBuffer,
  LPDWORD nSize
);

Parameters

hResource
[in] Handle to the dependent resource.
lpBuffer
[out] Buffer containing a null-terminated Unicode string that contains the name of the Network Name resource on which the resource depends.
nSize
[in, out] On input, pointer to a count of characters in the buffer pointed to by lpBuffer. On output, pointer to a count of characters in the network name of the Network Name resource contained in the buffer pointed to by lpBuffer, excluding the null-terminating character.

Return Values

Value | Meaning
TRUE | The operation was successful.
FALSE | The operation was not successful.

Remarks

Do not call GetClusterResourceNetworkName from any resource DLL entry point function. GetClusterResourceNetworkName can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

OpenClusterResource


GetClusterResourceState

The GetClusterResourceState function returns the current state of a resource.

CLUSTER_RESOURCE_STATE WINAPI GetClusterResourceState(
  HRESOURCE hResource,
  LPWSTR lpszNodeName,
  LPDWORD lpcchNodeName,
  LPWSTR lpszGroupName,
  LPDWORD lpcchGroupName
);

Parameters

hResource
[in] Handle specifying the resource for which state information should be returned.
lpszNodeName
[out] Optional pointer to a buffer that receives the name of the specified resource's current owner node as a NULL-terminated Unicode string. Pass NULL if the node name is not required.
lpcchNodeName
[in, out] Pointer to the size of the lpszNodeName buffer as a count of characters. This pointer cannot be NULL unless lpszNodeName is also NULL. On input, specifies the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
lpszGroupName
[out] Pointer to a buffer that receives the name of the group that contains the specified resource. The name is returned as a NULL-terminated Unicode string. Pass NULL if the group name is not required.
lpcchGroupName
[in, out] Pointer to the size of the lpszGroupName buffer as a count of characters. This pointer cannot be NULL unless lpszNodeName is also NULL. On input, specifies the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

GetClusterResourceState returns the current state of the resource, which can be represented by one of the following values.

State | Description
ClusterResourceInitializing | The resource is performing initialization.
ClusterResourceOnline | The resource is operational and functioning normally.
ClusterResourceOffline | The resource is not operational.
ClusterResourceFailed | The resource has failed.
ClusterResourcePending | The resource is in the process of coming online or going offline.
ClusterResourceOnlinePending | The resource is in the process of coming online.
ClusterResourceOfflinePending | The resource is in the process of going offline.
ClusterResourceStateUnknown | The operation was not successful. For more information about the error, call the Win32 function GetLastError.

Remarks

Do not call GetClusterResourceState from any resource DLL entry point function. GetClusterResourceState can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Offline, OfflineClusterResource, Online, OnlineClusterResource, OpenClusterResource


OfflineClusterResource

The OfflineClusterResource function takes a resource offline.

DWORD WINAPI OfflineClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource to be taken offline.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_IO_PENDING | The resource or one of the resources it depends on has returned ERROR_IO_PENDING from its Offline entry point function.

If the operation was not successful, OfflineClusterResource can return a Win32 error value.

Remarks

Do not call OfflineClusterResource from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Offline, Online, OnlineClusterResource, OpenClusterResource


OnlineClusterResource

The OnlineClusterResource function brings an offline or failed resource online.

DWORD WINAPI OnlineClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource to be brought online.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_IO_PENDING | The resource or one of the resources it depends on has returned ERROR_IO_PENDING from its Online entry point function.

If the operation was not successful, OnlineClusterResource can return a Win32 error value.

Remarks

Do not call OnlineClusterResource from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Offline, OfflineClusterResource, Online, OpenClusterResource


OpenClusterResource

The OpenClusterResource function opens a resource and returns a handle to it.

HRESOURCE WINAPI OpenClusterResource(
  HCLUSTER hCluster,
  LPCWSTR lpszResourceName
);

Parameters

hCluster
[in] Handle to a cluster.
lpszResourceName
[in] Pointer to a null-terminated Unicode string containing the name of the resource to be opened.

Return Values

Value | Meaning
NULL | The operation was not successful. For information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterResource returns a handle to the opened resource.

Example

See Using Object Handles.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CloseClusterResource


RemoveClusterResourceDependency

The RemoveClusterResourceDependency function removes a dependency relationship between two resources.

DWORD WINAPI RemoveClusterResourceDependency(
  HRESOURCE hResource,
  HRESOURCE hDependsOn
);

Parameters

hResource
[in] Handle to the dependent resource.
hDependsOn
[in] Handle to the resource that the resource identified by hResource currently depends on.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, RemoveClusterResourceDependency returns a Win32 error value.

Remarks

Do not call RemoveClusterResourceDependency from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

AddClusterResourceDependency, CanResourceBeDependent, OpenCluster, OpenClusterResource


RemoveClusterResourceNode

The RemoveClusterResourceNode function removes a node from the list of nodes that can host a resource.

DWORD WINAPI RemoveClusterResourceNode(
  HRESOURCE hResource,
  HNODE hNode
);

Parameters

hResource
[in] Handle to the target resource.
hNode
[in] Handle to the node that should be removed from the list of potential host nodes belonging to the resource identified by hResource.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, RemoveClusterResourceNode returns a Win32 error value.

Remarks

Do not call RemoveClusterResourceNode from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Do not pass LPC and RPC handles to the same function call. Otherwise, the call will raise an RPC exception and can have additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

AddClusterResourceNode, OpenCluster, OpenClusterNode, OpenClusterResource


SetClusterResourceName

The SetClusterResourceName function sets the name for a resource.

DWORD WINAPI SetClusterResourceName(
  HRESOURCE hResource,
  LPCWSTR lpszResourceName
);

Parameters

hResource
[in] Handle to a resource to rename.
lpszResourceName
[in] Pointer to the new name for the resource identified by hResource.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, SetClusterResourceName returns a Win32 error value.

Remarks

SetClusterResourceName changes the Name common property of the resource identified by hResource. This is the only way that Name, a read-only property, can be changed.

Do not call SetClusterResourceName from a resource DLL. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

Name, OpenClusterResource


Resource Type Management Functions

The following functions manage cluster resource types.

Function | Description
ClusterResourceTypeCloseEnum | Closes a resource type enumeration handle.
ClusterResourceTypeEnum | Enumerates a resource type's possible owner nodes, returning the name of one cluster object with each call.
ClusterResourceTypeOpenEnum | Opens an enumeration handle.
CreateClusterResourceType | Creates a new resource type in a cluster.
DeleteClusterResourceType | Deletes a resource type from a cluster.


ClusterResourceTypeCloseEnum

The ClusterResourceTypeCloseEnum function closes a resource type enumeration handle.

DWORD WINAPI ClusterResourceTypeCloseEnum(
   HRESTYPEENUM hResTypeEnum
);

Parameters

hResTypeEnum
[in] Enumeration handle to be closed.

Return Value

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterResourceTypeCloseEnum returns a Win32 error value.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterResourceTypeEnum, ClusterResourceTypeOpenEnum


ClusterResourceTypeEnum

The ClusterResourceTypeEnum function enumerates a resource type's possible owner nodes, returning the name of one node per call.

DWORD WINAPI ClusterResourceTypeEnum(
 HRESTYPEENUM hResTypeEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszName,
  LPDWORD lpcchName
);

Parameters

hResTypeEnum
[in] Resource type enumeration handle returned from ClusterResourceTypeOpenEnum.
dwIndex
[in] Index of the resource or node object to return. This parameter should be zero for the first call to ClusterResourceTypeEnum and then incremented for subsequent calls.
lpdwType
[out] Type of object returned by ClusterResourceTypeEnum. Currently, the following is the only valid type:
CLUSTER_RESOURCE_TYPE_ENUM_NODES
The object is a node which can be a possible owner of the resource type.
lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the returned object.
lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more objects to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.

If the operation was not successful due to a problem other than not having any more objects to return, ClusterResourceTypeEnum returns a Win32 error value.

Remarks

Note that lpcchName refers to a count of characters and not a count of bytes, and that the returned size does not include the terminating NULL in the count. For more information on sizing buffers, see Data Size Conventions.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterResourceTypeOpenEnum, ClusterResourceTypeCloseEnum


ClusterResourceTypeOpenEnum

The ClusterResourceTypeOpenEnum function opens an enumerator for iterating through a resource type's possible owner nodes.

HRESTYPEENUM WINAPI ClusterResourceTypeOpenEnum(
  HCLUSTER hCluster,
  LPCWSTR lpszResourceTypeName,
  DWORD dwType
);

Parameters

hCluster
[in] Cluster handle.
lpszResourceTypeName
[in] A null-terminated Unicode string containing the name of the resource type.
dwType
[in] Bitmask describing the type of cluster objects to be enumerated. Currently, the only valid type is CLUSTER_RESOURCE_TYPE_ENUM_NODES.

Return Value

Value | Meaning
NULL | The operation was unsuccessful. For detailed information about the error, call the Win32 function GetLastError.

A successful call returns an enumeration handle which can be used in subsequent calls to ClusterResourceTypeEnum.

Example

See Enumerating Objects.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterResourceTypeEnum, ClusterResourceTypeCloseEnum


CreateClusterResourceType

The CreateClusterResourceType function creates a new resource type in a cluster.

DWORD WINAPI CreateClusterResourceType(
  HCLUSTER hCluster,
  LPCWSTR lpszResourceTypeName,
  LPCWSTR lpszDisplayName,
  LPCWSTR lpszResourceTypeDll,
  DWORD dwLooksAlivePollInterval,
  DWORD dwIsAlivePollInterval
);

Parameters

hCluster
[in] Handle to the cluster to receive the new resource type.
lpszResourceTypeName
[in] Pointer to a null-terminated Unicode string containing the name of the new resource type. The specified name must be unique within the cluster.
lpszDisplayName
[in] Pointer to the display name for the new resource type. While the content of lpszResourceTypeName should uniquely identify the resource type on all clusters, the content of lpszDisplayName should be a localized friendly name for the resource suitable for displaying to administrators.
lpszResourceTypeDll
[in] Pointer to the fully qualified name of the resource DLL for the new resource type.
dwLooksAlivePollInterval
[in] Default millisecond value to be used as the poll interval needed by the new resource type's LooksAlive function. The dwLooksAlivePollInterval parameter is used to set the resource type's LooksAlivePollInterval property.
dwIsAlivePollInterval
[in] Default millisecond value to be used as the poll interval needed by the new resource type's IsAlive function. The dwIsAlivePollInterval parameter is used to set the resource type's IsAlivePollInterval property.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, CreateClusterResourceType returns a Win32 error value.

Remarks

The CreateClusterResourceType function only defines the resource type in the cluster database and registers the resource type with the Cluster service. To complete the process of installing a new resource type in a cluster, developers must install the resource DLLs and Cluster Administrator extension DLLs for the new types on each node in the cluster. Also, if Cluster Administrator will be used on systems that are not member nodes, the extension DLLs must also be installed on those systems.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

IsAlive, IsAlivePollInterval, LooksAlive, LooksAlivePollInterval, DeleteClusterResourceType


DeleteClusterResourceType

The DeleteClusterResourceType function removes a resource type from a cluster.

DWORD WINAPI DeleteClusterResourceType(
  HCLUSTER hCluster,
  LPCWSTR lpszResourceTypeName
);

Parameters

hCluster
[in] Handle to the cluster containing the resource type to be removed.
lpszResourceTypeName
[in] Pointer to a null-terminated Unicode string containing the name of the resource type to be removed.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, DeleteClusterResourceType returns a Win32 error value.

Remarks

The DeleteClusterResourceType function only removes the resource type with the name pointed to by lpszResourceTypeName from the cluster database and then unregisters it with the Cluster service. The caller must delete the resource DLL for the resource type from each node in the cluster.

The caller must also delete any resources of this type before calling DeleteClusterResourceType to delete the type. If any resources of the specified type still exist when DeleteClusterResourceType is called, the function fails.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

CreateClusterResourceType


Cluster Utility Functions

The cluster utility functions support a wide range of functionality, from general purpose helper functions to thread and service management functions. In general, both cluster-aware applications and resource DLLs can use the cluster utility functions. However, some utility functions are intended only for use by resource DLLs. Cluster-aware applications should follow the standard order of preference before using utility functions intended for resource DLLs.

Most of the utility functions are part of the Resource API. The only exceptions are the backup and restore functions, which are part of the Cluster API.

The cluster utility functions are categorized by the type of work they do and are presented in the following sections.

Function subset | Description | Intended for
Backup and Restore Functions | Back up and restore the cluster configuration. | Cluster-aware applications
General Utility Functions | Perform common tasks such as duplicating strings and validating paths. | All
Property List Parsing Functions | Locate specific values or properties in a property list. | All
Property Structure Construction Functions | Build property lists, parameter blocks, and property tables. | All
Resource Utility Functions | Enumerate resources, retrieve dependency information, and check the equivalency of resources. | Resource DLLs
Service Utility Functions | Start, stop, and check the status of services. | Resource DLLs
Thread Management Utility Functions | Create and terminate worker threads. | Resource DLLs


Backup and Restore Functions

The following functions let you take a snapshot of the current cluster configuration and restore that configuration at a later time. This can provide manual or automatic recovery after upgrades, installs, or tests.

Function | Description
BackupClusterDatabase | Creates a backup of the cluster database and all registry checkpoints.
RestoreClusterDatabase | Restores the cluster database and restarts the Cluster service on the restoring node.


BackupClusterDatabase

The BackupClusterDatabase function creates a backup of the cluster database and all registry checkpoints.

DWORD WINAPI
BackupClusterDatabase(
  HCLUSTER hCluster,
  LPCWSTR lpszPathName
);

Parameters

hCluster
[in] Handle to the cluster to be backed up.
lpszPathName
[in] Null-terminated Unicode string specifying the path to where the backup should be created.

Return Values

BackupClusterDatabase returns one of the following values.

Value | Description
ERROR_SUCCESS | The operation was successful.
Win32 Error | The operation was not successful.

Remarks

Ideally, the specified path should be a path visible to all cluster nodes, such as a UNC path. At minimum, the path must be visible to the node that currently owns the quorum resource. Do not include a filename in the path or the function will fail, returning ERROR_DIRECTORY. The path can include a trailing backslash.

One way to ensure that an appropriate path exists is to create a temporary network share, as follows:

  • Call the Win32 function NetShareAdd to create a temporary network share. All cluster nodes must have write access to this share.
  • Call BackupClusterDatabase, specifying the temporary share in the lpszPathname parameter.
  • Copy the backup files (see below) to one or more safe storage locations.
  • Call the Win32 function NetShareDel to delete the share.

The backup contains the following files.

Path\File | Description
lpszPath\chk????.tmp | Snapshot files.
lpszPath\quolog.log | The quorum log file.
lpszPath\<GUID of resource>\*.CPT | The registry checkpoint files for the resource identified by GUID.
lpszPath\<GUID of resource>\*.CPR | The crypto checkpoint files for the resource identified by GUID.
lpszPath\Clusbackup.dat | Backup completion marker file (read-only, hidden, 0-byte file)

Subsequent BackupClusterDatabase operations that use the same lpszPath parameter will overwrite the existing backup files.

If possible, make multiple copies of the backup directory on different media and store these copies in separate locations.

Example Code

The following example illustrates a static backup routine. For a more complete example incorporating RestoreClusterDatabase, see Backing Up and Restoring the Cluster Configuration. This example uses the ClusDocEx.h header file defined in the Server Cluster documentation.

#include "ClusDocEx.h"

int main( void )
{
    HCLUSTER hCluster     = NULL;
    WCHAR szClusterName[] = L"CLUSTER_NAME";
    WCHAR szPath[]        = L"\\\\clusback\\19991215";
    DWORD dwResult        = ERROR_SUCCESS;

    if( ( hCluster = OpenCluster( szClusterName ) ) != NULL )
    {
        dwResult = BackupClusterDatabase( hCluster, szPath );
        CloseCluster( hCluster );
    }
    else
        dwResult = GetLastError();

    if( dwResult == ERROR_SUCCESS )
    {
        wprintf( L"\nDone. The cluster database has been backed up to %s. ", szPath );
        wprintf( L"The backup consists of the following files:\n    chk????.tmp\n    quolog.log\n    *.cpt\n    *.cpr\n\n" );
        return 0;
    }
    else
    {
        ErrorMsg( dwResult, L"The operation did not succeed" );
        return 1;
    }
}

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

RestoreClusterDatabase


RestoreClusterDatabase

The RestoreClusterDatabase function restores the cluster database and restarts the Cluster service on the node from which the function is called. This node is called the restoring node.

DWORD WINAPI
RestoreClusterDatabase(
  LPCWSTR lpszPathName,
  BOOL bForce,
  LPCWSTR lpszQuorumDriveLetter
);

Parameters

lpszPathName
[in] Null-terminated Unicode string specifying the path to the backup file.
bForce
[in] If FALSE, the restore operation will not be completed if either of the following circumstances applies:
  • Other nodes are currently active.
  • The partition layout of the current quorum resource is not identical to the partition layout of the quorum resource that was in place when the backup was made. (The term "partition layout" refers to the number of partitions on the disk and the offsets to each partition. The disk signature and drive letter assignments do not have to be identical.)

Setting bForce to TRUE causes the operation to proceed regardless of these preceding circumstances; however, the operation may still fail for other reasons.

lpszQuorumDriveLetter
[in] Optional. Identifies the drive letter of the quorum resource on which the cluster database will be restored. Use this parameter only if the quorum resource has been replaced since the backup was made. The string must be formatted as follows:
  • The first character must be alphabetic, that is, in the range 'a'-'z' or 'A'-'Z'.
  • The second character must be a colon (':').
  • The third character must be a terminating null ('\0').

Return Values

The RestoreClusterDatabase function returns one of the following values.

Value | Description
ERROR_SUCCESS | The operation was successful.
ERROR_CLUSTER_NODE_UP | The operation failed because other cluster nodes are currently active. If you call RestoreClusterDatabase again with bForce set to TRUE, the cluster will attempt to shut down the Cluster service on the other active nodes.
ERROR_QUORUM_DISK_NOT_FOUND | The operation failed because the quorum disk described in the backup does not match the current quorum disk. If you call RestoreClusterDatabase again with bForce set to TRUE, the cluster will attempt to change the signature and drive letter of the current quorum disk to the values stored in the backup.
Win32 Error | The operation was not successful.

Remarks

If the restore operation is successful, the restoring node forms a cluster according to the configuration data in the restored cluster database. As other nodes join the cluster, they update their cluster databases from the database on the restoring node.

Note that cluster disks other than the quorum resource that have added or changed since the backup was made will not be recognized by the restored cluster database and will remain offline even if the restore operation is successful. New resources must be created for these disks (see Creating a Physical Disk Resource).

The following general procedure is recommended for any cluster restore routine:

  1. Call RestoreClusterDatabase with bForce set to FALSE and no drive letter specified. This is the "gentlest" approach because, if successful, the operation does not have to force configuration changes.
  2. If the first call fails, let the user decide whether to force the procedure to continue or manually fix the problem. Be sure to communicate the implications of each decision.
Return value | Action if forced | Manual fix
ERROR_CLUSTER_NODE_UP | The restore operation will stop the Cluster service on all other nodes. | User manually shuts down the Cluster service on all other cluster nodes. The command "net stop clussvc" is sufficient; a complete power-down is unnecessary.
ERROR_QUORUM_DISK_NOT_FOUND | User must supply the drive letter of the quorum resource. The restore operation will change the disk's signature and drive letter to the values stored in the backup. | User repartitions the quorum disk so that the layout is identical to the layout stored in the backup.

  3. If the user agrees to force continuation, call RestoreClusterDatabase with bForce set to TRUE and the drive letter specified (if applicable). Forcing does not guarantee success. If the restore operation fails again, test the return value and respond appropriately.

Example Code

The following example illustrates the procedure described above. For a more complete example that includes BackupClusterDatabase, see the Backing Up and Restoring the Cluster Configuration.This example uses the ClusDocEx.h header file defined in the Server Cluster documentation.

#include "ClusDocEx.h"

int main( void )
{
    WCHAR szPath[] = L"c:\\clusback\\19991215";
    WCHAR szInput[3];
    BOOL bForce = FALSE;
    DWORD dwResult = ERROR_SUCCESS;

    // First try: no force
    dwResult = RestoreClusterDatabase( szPath, FALSE, NULL );

    // Allow user to force shutdown if necessary.
    if( dwResult == ERROR_CLUSTER_UP )
    {
        wprintf( L"The operation failed because other cluster nodes are currently active. The Cluster service must be shut down on all other nodes in order for this operation to succeed." );
        wprintf( L"Enter 'f' to force automatic shutdown, or any other key to exit for manual shutdown:  " );
        fgetws( szInput, 2, stdin );
        if( towupper( szInput[0] ) == L'F' )
            dwResult = RestoreClusterDatabase( szPath, TRUE, NULL );
    }

    // Allow user to locate quorum resource if necessary.
    if( dwResult == ERROR_QUORUM_DISK_NOT_FOUND )
    {
        wprintf( L"\n\nERROR: QUORUM DISK NOT FOUND\n" );
        wprintf( L"The restore routine cannot find a quorum resource with the same partition layout as the quorum resource described in the backup. " );
        wprintf( L"The existing quorum resource must have a layout (number of partitions and offsets to each partition) identical to the layout stored in the backup.\n" );
        wprintf( L"Enter the drive letter of the quorum resource to force continuation, or any non-letter key to exit:  " );
        fgetws( szInput, 3, stdin );
        if( iswalpha( szInput[0] ) )
        {
            szInput[1] = L':';
            szInput[2] = L'\0';
            dwResult = RestoreClusterDatabase( szPath, TRUE, szInput );
        }
    }

    // Only one force attempt per error, then report success or failure.
    if( dwResult == ERROR_SUCCESS )
    {
        wprintf( L"\n\nSUCCESS\n" );
        wprintf( L"The restore routine succeeded. Start the Cluster service on the other cluster nodes to complete the restore operation. As nodes join the cluster, they will update their cluster databases to match the restored configuration." );
        return 0;
    }
    else
    {
        ErrorMsg( dwResult, L"RestoreClusterDatabase failed" );
        return 1;
    }

}

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

BackupClusterDatabase


General Utility Functions

The general utility functions take care of implementing common tasks that are useful in a variety of situations.

Function | Description
ResUtilCreateDirectoryTree | Creates, as necessary, each directory specified in a path.
ResUtilDupString | Duplicates a character string.
ResUtilExpandEnvironmentStrings | Expands a string containing expandable references to environment variables.
ResUtilInitializeResourceStatus | Initializes a RESOURCE_STATUS structure.
ResUtilIsPathValid | Checks whether a path is syntactically valid.


ResUtilCreateDirectoryTree

The ResUtilCreateDirectoryTree function creates every directory specified in a path, skipping directories that already exist.

DWORD WINAPI ResUtilCreateDirectoryTree(
  LPCWSTR pszPath
);

Parameters

pszPath
[in] Pointer to a null-terminated Unicode string specifying a path. The string can end with a trailing backslash.

Return Values

ResUtilCreateDirectoryTree returns one of the following values.

Value | Description
ERROR_SUCCESS | The operation completed successfully.
Win32 Error | The operation was not successful. Note that this function will never return ERROR_ALREADY_EXISTS.

Remarks

If the path only contains a drive specification (L"c:\\"), ResUtilCreateDirectoryTree will return ERROR_SUCCESS but take no action.

Example Code

// BEFORE
//   C:
//   |--Program Files
//      |-- MyApp
//          |--Data
ResUtilCreateDirectoryTree( L"C:\\Program Files\\MyApp\\Startup\\Parameters\\Users" );

ResUtilCreateDirectoryTree( L"C:\\Program Files\\MyApp\\Data\\Archive\\" );

ResUtilCreateDirectoryTree( L"C:\\Program Files\\MyApp\\Bin" );

// This call will return ERROR_SUCCESS even though all directories
// in the path already exist.
ResUtilCreateDirectoryTree( L"C:\\Program Files\\MyApp\\Bin" );

// AFTER
//   C:
//   |--Program Files
//      |--MyApp
//         |--Bin
//         |--Data
//         |  |--Archive
//         |--Startup
//            |--Parameters
//               |--Users
//

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


ResUtilDupString

The ResUtilDupString utility function duplicates a null-terminated Unicode string.

LPWSTR WINAPI ResUtilDupString(
  LPCWSTR pszInString
);

Parameters

pszInString
[in] Pointer to the string to duplicate.

Return Values

ResUtilDupString returns one of the following values

Value | Description
Non-NULL | If the operation was successful, ResUtilDupString returns a pointer to a buffer containing the duplicate string.
NULL | If the operation was not successful, ResUtilDupString returns NULL. For more information, call the Win32 function GetLastError.

Remarks

With the ResUtilDupString utility function, after using the returned string, callers should deallocate the buffer by calling the Win32 function LocalFree.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

GetLastError, LocalFree


ResUtilExpandEnvironmentStrings

The ResUtilExpandEnvironmentStrings function expands strings containing unexpanded references to environment variables.

LPWSTR WINAPI ResUtilExpandEnvironmentStrings(
  LPCWSTR pszSrc
);

Parameters

pszSrc
[in] Pointer to a null-terminated Unicode string containing unexpanded references to environment variables (an expandable string).

Return Values

ResUtilExpandEnvironmentStrings returns one of the following values.

Value | Description
Non-NULL | If successful, ResUtilExpandEnvironmentStrings returns a pointer to the expanded string (an ExpandedSz string). The function allocates the necessary memory with LocalAlloc. To prevent memory leaks, be sure to release the memory with LocalFree.
NULL | The operation was not successful. Call GetLastError for the specific error message.

Example Code

The following example calls ResUtilExpandEnvironmentStrings to expand the %SystemRoot% environment variable. This example uses the ClusDocEx.h header file defined in the Server Cluster documentation.

#include "ClusDocEx.h"

int main( void )
{
    WCHAR  pszExpand[]  = L"%SystemRoot%";
    LPWSTR lpszExpanded = NULL;
    int    intStatus    = 0;

    // The function allocates the necessary memory.
    lpszExpanded = ResUtilExpandEnvironmentStrings( pszExpand );

    if( lpszExpanded != NULL )
    {
        wprintf( L"System root is: %ls\n", lpszExpanded );
    }
    else
    {
        ErrorMsg( GetLastError(), L"String expansion failed." ); // Declared in clushead.h
        intStatus = 1;
    }

    // Always
    LocalFree( lpszExpanded );

    return intStatus;
}

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetExpandSzValue, ResUtilFindExpandSzProperty, ResUtilGetEnvironmentWithNetName


ResUtilGetPropertyFormats

[This is preliminary documentation and subject to change.]

The ResUtilGetPropertyFormats control code returns a property format list describing the format of a specified set of properties.

DWORD WINAPI ResUtilGetPropertyFormats(
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID pOutPropertyFormatList,
  DWORD cbPropertyFormatListSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

pPropertyTable
[in] Pointer to a property table specifying the properties whose formats are to be retrieved.
pOutPropertyFormatList
[out] On input, pointer to a buffer. On a successful return, pointer to a property format list describing the format of each property specified by pPropertyTable.
cbPropertyFormatListSize
[in] Specifies the allocated size (in bytes) of the buffer pointed to by pOutPropertyFormatList.
pcbBytesReturned
[out] Pointer to the actual size (in bytes) of the property format list that results from the operation.
pcbRequired
[out] If the buffer pointed to by the pOutPropertyFormatList parameter is too small to hold the resulting data, pcbRequired points to the required buffer size (in bytes).

Return Values

Returns ERROR_SUCCESS if the operation was successful.

Requirements

Version: Requires Whistler.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUSCTL_CLUSTER_GET_COMMON_PROPERTY_FMTS,


ResUtilInitializeResourceStatus

The ResUtilInitializeResourceStatus utility function initializes a RESOURCE_STATUS structure.

VOID WINAPI ResUtilInitializeResourceStatus(
  PRESOURCE_STATUS ResourceStatus
);

Parameters

ResourceStatus
[in] Pointer to the RESOURCE_STATUS structure to initialize.

Return Values

This function has no return values.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESOURCE_STATUS


ResUtilIsPathValid

The ResUtilIsPathValid utility function is used to check whether a path is syntactically valid.

BOOL WINAPI ResUtilIsPathValid(
  LPCWSTR pszPath
);

Parameters

pszPath
[in] Pointer to the path to check.

Return Values

ResUtilIsPathValid returns one of the following values.

Value | Description
TRUE | The path pointed to by pszPath is valid.
FALSE | The path pointed to by pszPath is not valid.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


Property List Parsing Functions

The property list parsing functions locate specific values or properties in a property list.

Function | Description
ResUtilFindBinaryProperty | Locates a binary property in a property list.
ResUtilFindDwordProperty | Locates a numeric property in a property list.
ResUtilFindMultiSzProperty | Locates a multiple string property in a property list.
ResUtilFindSzProperty | Locates a string property in a property list.
ResUtilGetBinaryProperty | Retrieves a binary property from a property list and advances to the next property in the list.
ResUtilGetDwordProperty | Retrieves a DWORD property from a property list and advances to the next property in the list.
ResUtilGetExpandSzProperty | Retrieves an expandable string property from a property list and advances to the next property in the list.
ResUtilGetMultiSzProperty | Retrieves a multiple string property from a property list and advances to the next property in the list.
ResUtilGetSzProperty | Retrieves a string property from a property list and advances to the next property in the list.


ResUtilFindBinaryProperty

The ResUtilFindBinaryProperty utility function locates a specified binary property in a property list and can also return the value of the property.

DWORD WINAPI ResUtilFindBinaryProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPBYTE* ppbPropertyValue,
  LPDWORD pcbPropertyValueSize
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size, in bytes, of the property list specified by pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the property to locate.
ppbPropertyValue
[out] Pointer to a BYTE pointer to a buffer (allocated by the function) containing a copy of the property value. You must call LocalFree (on *ppbPropertyValue) to free the allocated memory. If no value is required, pass NULL for this parameter.
pcbPropertyValueSize
[out] Pointer to the size, in bytes, of the value returned. If no size is required, pass NULL for this parameter.

Return Values

ResUtilFindBinaryProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | The specified property was found in the property list.
ERROR_INVALID_DATA | The property list is incorrectly formatted.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate a buffer in which to return the property value.
ERROR_FILE_NOT_FOUND | The specified property could not be located in the property list.

Remarks

If ResUtilFindBinaryProperty is successful, *ppbPropertyValue points to a copy of the data stored in pPropertyList. Be sure to call LocalFree on *ppbPropertyValue to prevent memory leaks.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindDwordProperty, ResUtilFindExpandSzProperty, ResUtilFindExpandedSzProperty, ResUtilFindLongProperty, ResUtilFindMultiSzProperty, ResUtilFindSzProperty


ResUtilFindDwordProperty

The ResUtilFindDwordProperty utility function locates an unsigned long property value in a property list.

DWORD WINAPI ResUtilFindDwordProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPDWORD pdwPropertyValue
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size in bytes of the data included in pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the value to locate.
pdwPropertyValue
[out] Pointer to the actual value of the data stored in the property list buffer.

Return Values

ResUtilFindDwordProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_DATA | The data is in an incorrect format.
ERROR_FILE_NOT_FOUND | The property could not be located in the property list.

Remarks

If the operation is successful, pdwPropertyValue points directly into the property list buffer. Be careful not to disturb the formatting of the property list when using pdwPropertyValue.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindBinaryProperty, ResUtilFindExpandSzProperty, ResUtilFindExpandedSzProperty, ResUtilFindLongProperty, ResUtilFindMultiSzProperty, ResUtilFindSzProperty


ResUtilFindExpandSzProperty

The ResUtilFindExpandSzProperty utility function locates an expandable string property in a property list.

DWORD WINAPI ResUtilFindExpandSzProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPWSTR* ppszPropertyValue
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size in bytes of the data included in pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the value to locate.
ppszPropertyValue
[out] Pointer to a WCHAR pointer to a buffer (allocated by the function) containing a copy of the property value. You must call LocalFree (on *ppszPropertyValue) to free the allocated memory. If no value is required, pass NULL for this parameter.

Return Values

ResUtilFindExpandSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | The specified property was found in the property list.
ERROR_INVALID_DATA | The property list is incorrectly formatted.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate a buffer in which to return the property value.
ERROR_FILE_NOT_FOUND | The specified property could not be located in the property list.

Remarks

If ResUtilFindExpandSzProperty is successful, *ppszPropertyValue points to a copy of the data stored in pPropertyList. Be sure to call LocalFree on *ppszPropertyValue to prevent memory leaks.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindBinaryProperty, ResUtilFindDwordProperty, ResUtilFindExpandedSzProperty, ResUtilFindLongProperty, ResUtilFindMultiSzProperty, ResUtilFindSzProperty


ResUtilFindExpandedSzProperty

The ResUtilFindExpandedSzProperty utility function locates an expanded string property value in a property list.

DWORD WINAPI ResUtilFindExpandedSzProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPWSTR* ppszPropertyValue
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size in bytes of the data included in pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the value to locate.
ppszPropertyValue
[out] Pointer to a WCHAR pointer to a buffer (allocated by the function) containing a copy of the property value. You must call LocalFree (on *ppszPropertyValue) to free the allocated memory. If no value is required, pass NULL for this parameter.

Return Values

ResUtilFindExpandSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | The specified property was found in the property list.
ERROR_INVALID_DATA | The property list is incorrectly formatted.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate a buffer in which to return the property value.
ERROR_FILE_NOT_FOUND | The specified property could not be located in the property list.

Remarks

If ResUtilFindExpandSzProperty is successful, *ppszPropertyValue points to a copy of the data stored in pPropertyList. Be sure to call LocalFree on *ppszPropertyValue to prevent memory leaks.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindBinaryProperty, ResUtilFindDwordProperty, ResUtilFindExpandSzProperty, ResUtilFindLongProperty, ResUtilFindMultiSzProperty, ResUtilFindSzProperty


ResUtilFindLongProperty

The ResUtilFindLongProperty utility function locates a signed long property value in a property list.

DWORD WINAPI ResUtilFindLongProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPLONG plPropertyValue
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size in bytes of the data included in pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the value to locate.
plPropertyValue
[out] Pointer to the actual value of the data stored in the property list buffer.

Return Values

ResUtilFindLongProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_DATA | The data is in an incorrect format.
ERROR_FILE_NOT_FOUND | The property could not be located in the property list.

Remarks

If the operation is successful, plPropertyValue points directly into the property list buffer. Be careful not to disturb the formatting of the property list when using plPropertyValue.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindBinaryProperty, ResUtilFindDwordProperty, ResUtilFindExpandSzProperty, ResUtilFindExpandedSzProperty, ResUtilFindMultiSzProperty, ResUtilFindSzProperty


ResUtilFindMultiSzProperty

The ResUtilFindMultiSzProperty utility function locates a multiple string property in a property list.

DWORD WINAPI ResUtilFindMultiSzProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPWSTR* ppszPropertyValue,
  LPDWORD pcbPropertyValueSize
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size in bytes of the data included in pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the value to locate.
ppszPropertyValue
[out] Pointer to a WCHAR pointer to a buffer (allocated by the function) containing a copy of the property value. You must call LocalFree (on *ppszPropertyValue) to free the allocated memory. If no value is required, pass NULL for this parameter.
pcbPropertyValueSize
[out] Pointer to the size, in bytes, of the value returned. If no size is required, pass NULL for this parameter.

Return Values

ResUtilFindMultiSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | The specified property was found in the property list.
ERROR_INVALID_DATA | The property list is incorrectly formatted.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate a buffer in which to return the property value.
ERROR_FILE_NOT_FOUND | The specified property could not be located in the property list.

Remarks

If ResUtilFindMultiSzProperty is successful, *ppszPropertyValue points to a copy of the data stored in pPropertyList. Be sure to call LocalFree on *ppszPropertyValue to prevent memory leaks.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindBinaryProperty, ResUtilFindDwordProperty, ResUtilFindExpandSzProperty, ResUtilFindExpandedSzProperty, ResUtilFindLongProperty, ResUtilFindSzProperty


ResUtilFindSzProperty

The ResUtilFindSzProperty utility function locates a string property in a property list.

DWORD WINAPI ResUtilFindSzProperty(
  const PVOID pPropertyList,
  DWORD cbPropertyListSize,
  LPCWSTR pszPropertyName,
  LPWSTR* ppszPropertyValue
);

Parameters

pPropertyList
[in] Pointer to the property list in which to locate the value.
cbPropertyListSize
[in] Size in bytes of the data included in pPropertyList.
pszPropertyName
[in] Pointer to a null-terminated Unicode string containing the name of the value to locate.
ppszPropertyValue
[out] Pointer to a WCHAR pointer to a buffer (allocated by the function) containing a copy of the property value. You must call LocalFree (on *ppszPropertyValue) to free the allocated memory. If no value is required, pass NULL for this parameter.

Return Values

ResUtilFindSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | The specified property was found in the property list.
ERROR_INVALID_DATA | The property list is incorrectly formatted.
ERROR_NOT_ENOUGH_MEMORY | The function could not allocate a buffer in which to return the property value.
ERROR_FILE_NOT_FOUND | The specified property could not be located in the property list.

Remarks

If ResUtilFindSzProperty is successful, *ppszPropertyValue points to a copy of the data stored in pPropertyList. Be sure to call LocalFree on *ppszPropertyValue to prevent memory leaks.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindBinaryProperty, ResUtilFindDwordProperty, ResUtilFindExpandSzProperty, ResUtilFindExpandedSzProperty, ResUtilFindLongProperty, ResUtilFindMultiSzProperty


ResUtilGetBinaryProperty

The ResUtilGetBinaryProperty utility function retrieves a binary property from a property list and advances a pointer to the next property in the list.

DWORD WINAPI ResUtilGetBinaryProperty(
  LPBYTE* ppbOutValue,
  LPDWORD pcbOutValueSize,
  const PCLUSPROP_BINARY pValueStruct,
  const LPBYTE pbOldValue,
  DWORD cbOldValueSize,
  LPBYTE* ppPropertyList,
  LPDWORD pcbPropertyListSize
);

Parameters

ppbOutValue
[out] Address of a pointer in which the binary value from the property list will be returned.
pcbOutValueSize
[out] Pointer to the size of the output value.
pValueStruct
[in] Pointer to a CLUSPROP_BINARY structure specifying the binary value to retrieve from the property list.
pbOldValue
[in] Optional pointer to the previous value of the property.
cbOldValueSize
[in] Pointer to the length of the previous value of the property.
ppPropertyList
[out] Address of the pointer to the property list buffer containing the binary property. This pointer will be advanced to the beginning of the next property.
pcbPropertyListSize
[out] Pointer to the size of the property list buffer. The size will be decremented to account for the advance of the ppPropertyList pointer.

Return Values

ResUtilGetBinaryProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_PARAMETER | The data is formatted incorrectly.

If the operation was not successful, ResUtilGetBinaryProperty returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetDwordProperty, ResUtilGetExpandSzProperty, ResUtilGetMultiSzProperty, ResUtilGetSzProperty


ResUtilGetDwordProperty

The ResUtilGetDwordProperty utility function retrieves a DWORD property from a property list and advances a pointer to the next property in the list.

DWORD WINAPI ResUtilGetDwordProperty(
  LPDWORD pdwOutValue,
  const PCLUSPROP_DWORD pValueStruct,
  DWORD dwOldValue,
  DWORD dwMinimum,
  DWORD dwMaximum,
  LPBYTE* ppPropertyList,
  LPDWORD pcbPropertyListSize
);

Parameters

pdwOutValue
[out] Address of a pointer in which the DWORD value from the property list will be returned.
pValueStruct
[in] Pointer to a CLUSPROP_DWORD structure specifying the DWORD value to retrieve from the property list.
dwOldValue
[in] Specifies the previous value of the property.
dwMinimum
[in] Specifies the minimum value allowed for the property.
dwMaximum
[in] Specifies the maximum value allowed for the property.
ppPropertyList
[out] Address of the pointer to the property list buffer containing the DWORD property. This pointer will be advanced to the beginning of the next property.
pcbPropertyListSize
[out] Pointer to the size of the property list buffer. The size will be decremented to account for the advance of the ppPropertyList pointer.

Return Values

ResUtilGetDwordProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_PARAMETER | The data is formatted incorrectly.

If the operation was not successful, ResUtilGetDwordProperty returns a Win32 error value.

Remarks

The ResUtilGetDwordProperty utility function verifies that the value returned in pdwOutValue is within the range specified by dwMinimum and dwMaximum. If dwMinimum and dwMaximum are both set to 0, no range checking is done.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetBinaryProperty, ResUtilGetExpandSzProperty, ResUtilGetMultiSzProperty, ResUtilGetSzProperty


ResUtilGetExpandSzProperty

The ResUtilGetExpandSzProperty utility function retrieves an expandable string property from a property list and advances a pointer to the next property in the list.

DWORD WINAPI ResUtilGetExpandSzProperty(
  LPWSTR* ppszOutValue,
  LPDWORD pcbOutValueSize,
  const PCLUSPROP_SZ pValueStruct,
  const LPCWSTR pszOldValue,
  DWORD cbOldValueSize,
  LPBYTE* ppPropertyList,
  LPDWORD pcbPropertyListSize
);

Parameters

ppszOutValue
[out] Address of a pointer by which the expandable string value from the property list will be returned.
pcbOutValueSize
[out] Pointer to the size of the output value.
pValueStruct
[in] Pointer to a CLUSPROP_SZ structure specifying the expandable string value to retrieve from the property list.
pszOldValue
[in] Optional pointer to the previous value of the property.
cbOldValueSize
[in] Pointer to the length of the previous value of the property.
ppPropertyList
[out] Address of the pointer to the property list buffer containing the expandable string property. This pointer will be advanced to the beginning of the next property.
pcbPropertyListSize
[out] Pointer to the size of the property list buffer. The size will be decremented to account for the advance of the ppPropertyList pointer.

Return Values

ResUtilGetExpandSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_PARAMETER | The data is formatted incorrectly.

If the operation was not successful, ResUtilGetExpandSzProperty returns a Win32 error value.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetBinaryProperty, ResUtilGetDwordProperty, ResUtilGetMultiSzProperty, ResUtilGetSzProperty


ResUtilGetMultiSzProperty

The ResUtilGetMultiSzProperty utility function retrieves a multiple string property from a property list and advances a pointer to the next property in the list.

DWORD WINAPI ResUtilGetMultiSzProperty(
  LPWSTR* ppszOutValue,
  LPDWORD pcbOutValueSize,
  const PCLUSPROP_SZ pValueStruct,
  const LPCWSTR pszOldValue,
  DWORD cbOldValueSize,
  LPBYTE* ppPropertyList,
  LPDWORD pcbPropertyListSize
);

Parameters

ppszOutValue
[out] Address of a pointer in which the multiple string value from the property list will be returned.
pcbOutValueSize
[out] Pointer to the size of the output value.
pValueStruct
[in] Pointer to a CLUSPROP_MULTI_SZ structure specifying the multiple string value to retrieve from the property list.
pszOldValue
[in] Optional pointer to the previous value of the property.
cbOldValueSize
[in] Pointer to the length of the previous value of the property.
ppPropertyList
[out] Address of the pointer to the property list buffer containing the multiple string property. This pointer will be advanced to the beginning of the next property.
pcbPropertyListSize
[out] Pointer to the size of the property list buffer. The size will be decremented to account for the advance of the ppPropertyList pointer.

Return Values

ResUtilGetMultiSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_PARAMETER | The data is formatted incorrectly.

If the operation was not successful, ResUtilGetMultiSzProperty returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetBinaryProperty, ResUtilGetDwordProperty, ResUtilGetExpandSzProperty, ResUtilGetSzProperty


ResUtilGetSzProperty

The ResUtilGetSzProperty utility function retrieves a string property from a property list and advances a pointer to the next property in the list.

DWORD WINAPI ResUtilGetSzProperty(
  LPWSTR* ppszOutValue,
  LPDWORD pcbOutValueSize,
  const PCLUSPROP_SZ pValueStruct,
  const LPCWSTR pszOldValue,
  DWORD cbOldValueSize,
  LPBYTE* ppPropertyList,
  LPDWORD pcbPropertyListSize
);

Parameters

ppszOutValue
[out] Address of a pointer in which the string value from the property list will be returned.
pcbOutValueSize
[out] Pointer to the size of the output value.
pValueStruct
[in] Pointer to a CLUSPROP_SZ structure specifying the string value to retrieve from the property list.
pszOldValue
[in] Optional pointer to the previous value of the property.
cbOldValueSize
[in] Pointer to the length of the previous value of the property.
ppPropertyList
[out] Address of the pointer to the property list buffer containing the string property. This pointer will be advanced to the beginning of the next property.
pcbPropertyListSize
[out] Pointer to the size of the property list buffer. The size will be decremented to account for the advance of the ppPropertyList pointer.

Return Values

ResUtilGetSzProperty returns one of the following values.

Value | Description
ERROR_SUCCESS | A successful attempt was made to locate the value.
ERROR_INVALID_PARAMETER | The data is formatted incorrectly.

If the operation was not successful, ResUtilGetSzProperty returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetBinaryProperty, ResUtilGetDwordProperty, ResUtilGetExpandSzProperty, ResUtilGetMultiSzProperty


Property Structure Construction Functions

The property structure construction functions are used to build property lists, parameter blocks, and property tables.

Function | Description
ResUtilDupParameterBlock | Duplicates a parameter block.
ResUtilFreeParameterBlock | Frees a specified parameter block.
ResUtilPropertyListFromParameterBlock | Constructs a property list from a parameter block.
ResUtilVerifyPropertyTable | Validates properties for an object based on a property list from a property table.
ResUtilVerifyPrivatePropertyList | Validates private properties of an object.


ResUtilDupParameterBlock

The ResUtilDupParameterBlock utility function performs a member-wise copy of the data from one parameter block to another.

DWORD WINAPI ResUtilDupParameterBlock(
  LPBYTE pOutParams,
  const LPBYTE pInParams,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable
);

Parameters

pOutParams
[out] Pointer to the duplicated parameter block.
pInParams
[in] Pointer to the original parameter block.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing properties in the original parameter block.

Return Values

ResUtilDupParameterBlock returns one of the following values.

Value | Description
ERROR_SUCCESS | The parameter block was duplicated successfully.

If the operation was not successful, ResUtilDupParameterBlock returns a Win32 error value.

Remarks

ResUtilDupParameterBlock copies data only for parameter block members referenced in the pPropertyTable input parameter. If a variable in the input parameter block is a pointer, memory for the data is allocated with the Win32 function LocalAlloc. You should deallocate this memory by calling either LocalFree for each pointer variable in the output parameter block or ResUtilFreeParameterBlock. Make sure that you deallocate memory whether ResUtilDupParameterBlock succeeds or fails. For more information, see Using Parameter Blocks and Using Lists and Tables.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFreeParameterBlock, RESUTIL_PROPERTY_ITEM


ResUtilFreeParameterBlock

The ResUtilFreeParameterBlock utility function deallocates memory that has been allocated for a parameter block by ResUtilDupParameterBlock.

void WINAPI ResUtilFreeParameterBlock(
  LPBYTE pOutParams,
  const LPBYTE pInParams,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable
);

Parameters

pOutParams
[in, out] Pointer to the parameter block to deallocate.
pInParams
[in] Pointer to the parameter block to use as a reference.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties in the input parameter block.

Return Values

This function has no return values.

Remarks

The ResUtilFreeParameterBlock utility function deallocates any memory allocated to each member of pOutParams, subject to the following limitations:

  • It will only deallocate memory for members referenced in the pPropertyTable input parameter.
  • It will not deallocate memory that is pointed to by any member of pInParams.

Do not use this function with parameter blocks that have not been allocated with ResUtilDupParameterBlock.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilDupParameterBlock, RESUTIL_PROPERTY_ITEM


ResUtilPropertyListFromParameterBlock

The ResUtilPropertyListFromParameterBlock utility function constructs a property list from a property table and a parameter block.

DWORD WINAPI ResUtilPropertyListFromParameterBlock(
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID pOutPropertyList,
  LPDWORD pcbOutPropertyListSize,
  const LPBYTE pInParams,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

pPropertyTable
[in] Pointer to a property table describing the properties that will be included in the resulting property list.
pOutPropertyList
[out] Pointer to an output buffer that receives the property list.
pcbOutPropertyListSize
[in, out] Pointer to the size of the output buffer in bytes.
pInParams
[in] Pointer to the parameter block in which the property values are stored.
pcbBytesReturned
[out] If the function returns ERROR_SUCCESS, pcbBytesReturned points to the acutal byte size of the property list pointed to by pOutPropertyList. If the function does not return ERROR_SUCCESS, pcbBytesReturned points to a value of zero.
pcbRequired
[out] If the function returns ERROR_MORE_DATA, pcbRequired points to the byte size required to contain the property list. If the function does not return ERROR_MORE_DATA, pcbBytesReturned points to a value of zero.

Return Values

ResUtilPropertyListFromParameterBlock returns one of the following values.

Value | Description
ERROR_SUCCESS | The properties were returned successfully.
ERROR_MORE_DATA | The output buffer is too small to contain the resulting property list.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.

If the operation was not successful, ResUtilPropertyListFromParameterBlock returns a Win32 error value.

Remarks

In this function, the property table determines the order in which the properties appear in the property list, as well as the name and format of each property. The function reads the property table to determine the name and format of each property.

The parameter block provides the property values.

Example Code

The following example defines three properties (Protocol, PortNumber, and ConnectionName). It uses the ResUtilPropertyListFromParameterBlock function to create a property list. This example uses the ClusDocEx.h header file defined in the Server Cluster documentation.

//////////////////////////////////////////////////////////////////////

//  Be sure to create the following file before you compile.
//  For a code listing, see "ClusDocEx.h".
    #include "ClusDocEx.h"

//////////////////////////////////////////////////////////////////////

//  This example defines three fictional properties:
//      Protocol (DWORD)
//      PortNumber (DWORD)
//      ConnectionName (PWSTR)
//  These properties are not associated with any cluster object.
//  They are used only to demonstrate the
//  ResUtilPropertyListFromParameterBlock function.

//  Protocol property constants
    #define PROP_NAME__PROTOCOL       L"Protocol"
    typedef enum PROTOCOLS{
        PROTOCOL_NONE = 0,
        PROTOCOL_BOTH = 1,
        PROTOCOL_TCP  = 2,
        PROTOCOL_UDP  = 3
    };
    #define PROP_MIN__PROTOCOL       (PROTOCOL_NONE)
    #define PROP_MAX__PROTOCOL       (PROTOCOL_UDP)
    #define PROP_DEFAULT__PROTOCOL   (PROTOCOL_BOTH)

//  PortNumber property
    #define PROP_NAME__PORTNUMBER     L"PortNumber"
    #define PROP_MIN__PORTNUMBER      (0)
    #define PROP_MAX__PORTNUMBER      (65536)
    #define PROP_DEFAULT__PORTNUMBER  (80)

//  ConnectionName property
    #define PROP_NAME__CONNECTIONNAME L"ConnectionName"

//  Parameter block
    typedef struct _PARAMBLOCK{
        DWORD dwProtocol;
        DWORD dwPortNumber;
        PWSTR pszConnectionName;
    } PARAMBLOCK;

//  Property table
    RESUTIL_PROPERTY_ITEM
    pPropTable[] =
    {
        {   PROP_NAME__PROTOCOL,
            NULL,
            CLUSPROP_FORMAT_DWORD,
            PROP_DEFAULT__PROTOCOL,
            PROP_MIN__PROTOCOL,
            PROP_MAX__PROTOCOL,
            RESUTIL_PROPITEM_REQUIRED,
            FIELD_OFFSET( _PARAMBLOCK, dwProtocol )        },

        {   PROP_NAME__PORTNUMBER,
            NULL,
            CLUSPROP_FORMAT_DWORD,
            PROP_DEFAULT__PORTNUMBER,
            PROP_MIN__PORTNUMBER,
            PROP_MAX__PORTNUMBER,
            RESUTIL_PROPITEM_REQUIRED,
            FIELD_OFFSET( _PARAMBLOCK, dwPortNumber )      },

        {   PROP_NAME__CONNECTIONNAME,
            NULL,
            CLUSPROP_FORMAT_SZ,
                0, 0, 0, 0,
            FIELD_OFFSET( _PARAMBLOCK, pszConnectionName ) },

        { 0 }
    };

    int main()
    {
        DWORD nResult    = ERROR_SUCCESS,
              cbBufSize  = 1024,
              cbReturned = 0,
              cbRequired = 0;

        PVOID pPropList = LocalAlloc( LPTR, cbBufSize );

    //  Values for the property list
        PARAMBLOCK NewParams = { PROTOCOL_TCP, 21, L"FTP" };

        nResult = ResUtilPropertyListFromParameterBlock(
                      pPropTable,
                      pPropList,
                      &cbBufSize,
                      (LPBYTE) &NewParams,
                      &cbReturned,
                      &cbRequired );

        if( nResult == ERROR_MORE_DATA )
        {
            LocalFree( pPropList );

            cbBufSize = cbRequired;

            pPropList = LocalAlloc( LPTR, cbBufSize );

            nResult = ResUtilPropertyListFromParameterBlock(
                          pPropTable,
                          pPropList,
                          &cbBufSize,
                          (PBYTE) &NewParams,
                          &cbReturned,
                          &cbRequired );
        }

        ClusDocEx_DebugPrint( L"Results:", nResult );

        if( nResult == ERROR_SUCCESS )
            ClusDocEx_ShowBuffer( pPropList, cbReturned );

        LocalFree( pPropList );

        return (int)( nResult != ERROR_SUCCESS );
    }

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM


ResUtilVerifyPrivatePropertyList

The ResUtilVerifyPrivatePropertyList utility function verifies that a property list is correctly formatted.

DWORD WINAPI ResUtilVerifyPrivatePropertyList(
  const PVOID pInPropertyList,
  DWORD cbInPropertyListSize
);

Parameters

pInPropertyList
[in] Pointer to an input buffer containing the property list to verify.
cbInPropertyListSize
[in] Size of the input buffer pointed to by pInPropertyList.

Return Values

ResUtilVerifyPrivatePropertyList returns one of the following values.

Value | Description
ERROR_SUCCESS | The property list was successfully verified.

If the operation was not successful, ResUtilVerifyPrivatePropertyList returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilSetPrivatePropertyList


ResUtilVerifyPropertyTable

The ResUtilVerifyPropertyTable utility function uses a property table to verify that a property list is correctly formatted.

DWORD WINAPI ResUtilVerifyPropertyTable(
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID Reserved,
  BOOL bAllowUnknownProperties,
  const PVOID pInPropertyList,
  DWORD cbInPropertyListSize,
  OPTIONAL LPBYTE pOutParams
);

Parameters

pPropertyTable
[in] Pointer to a property table describing the properties that will be validated in the property list.
Reserved
[in] This parameter is reserved for future use.
bAllowUnknownProperties
[in] If TRUE, the function ignores all properties in the property list that are not included in the property table. If FALSE, any property in the property list that is not included in the property table causes the function to return ERROR_INVALID_PARAMETER.
pInPropertyList
[in] Pointer to the input buffer containing the property list to validate.
cbInPropertyListSize
[in] Size in bytes of the input buffer pointed to by pInPropertyList.
pOutParams
[out] Optional pointer to a parameter block.

Return Values

ResUtilVerifyPropertyTable returns one of the following values.

Value | Description
ERROR_INSUFFICIENT_BUFFER | The property list buffer is larger than reported by the cbInPropertyListSize parameter.
ERROR_INVALID_DATA | No property list buffer was specified, or the property list is formatted incorrectly
ERROR_INVALID_PARAMETER | The property list is formatted incorrectly. If bAllowUnknownProperties is set to FALSE, the property list may contain properties that are not present in the property table.
ERROR_SUCCESS | The property list is formatted correctly.

ResUtilVerifyPropertyTable can return other Win32 error values.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM


Resource Utility Functions

The resource utility functions allow applications and resource DLLs to enumerate resources, retrieve information about dependencies, and determine whether two resources or resource types are equal.

Function | Description
ResUtilEnumResources | Enumerates cluster resources and initiates an operation on each resource.
ResUtilFindDependentDiskResourceDriveLetter | Retrieves the drive letter associated with a Physical Disk dependency of a resource.
ResUtilGetResourceDependentIPAddressProps | Retrieves the private properties of the first IP Address dependency found for a specified resource.
ResUtilGetResourceDependency | Returns a handle to a dependent resource of a specified type.
ResUtilGetResourceNameDependency | Returns a handle to a dependent resource of a specified name and type.
ResUtilIsResourceClassEqual | Determines whether a the resource class of specified resource is equal to a specified resource class.
ResUtilResourcesEqual | Determines whether two resource handles refer to the same resource.
ResUtilResourceTypesEqual | Determines whether the resource type of a resource matches a specified resource type name.


ResUtilEnumResources

The ResUtilEnumResources utility function enumerates all of the resources in the local cluster and initiates a user-defined operation for each resource.

DWORD WINAPI ResUtilEnumResources(
  HRESOURCE hSelf,
  LPCWSTR lpszResTypeName,
  LPRESOURCE_CALLBACK pResCallBack,
  PVOID pParameter
);

Parameters

hSelf
[in] Optional handle to a cluster resource. The callback function is not invoked for a resource identified by hSelf.
lpszResTypeName
[in] Optional pointer to a name of a resource type that narrows the scope of resources to enumerate. If lpszResTypeName is specified, only resources of the specified type are enumerated.
pResCallBack
[in] Pointer to a user-defined function which will be called for each enumerated resource. This function must conform to the definition of LPRESOURCE_CALLBACK (note that parameter names are not part of the definition; they have been added here for clarity):
DWORD (*LPRESOURCE_CALLBACK)(
  HRESOURCE hSelf,
  HRESOURCE hEnum,
  PVOID pParameter
);
hSelf
[in] The hSelf parameter passed to ResUtilEnumResources. Note that the callback function is never called when hSelf and hEnum refer to the same resource.
hEnum
[in] Handle to the resource currently being enumerated. ResUtilEnumResources opens and closes this handle automatically.
pParameter
[in] A generic buffer that allows you to pass any kind of data to the callback function.
pParameter
[in] A generic buffer that allows you to pass any kind of data to the callback function. ResUtilEnumResources does not use this parameter at all, it merely passes the pointer to the callback function. Whether or not you can pass NULL for the parameter depends on how the callback function is implemented.

Return Values

ResUtilEnumResources returns one of the following values.

Value | Description
ERROR_SUCCESS | The resources were successfully enumerated, and all calls to the callback function were successful.

If the operation was not successful, ResUtilEnumResources returns a Win32 error. If the callback function returns any value other than ERROR_SUCCESS, ResUtilEnumResources immediately halts the enumeration and returns the value returned by the callback function.

Remarks

ResUtilEnumResources is a convenient and easy-to-use alternative to the ClusterResourceEnum function.

ResUtilEnumResources must be run on a cluster node because it only connects to the local cluster. The ResUtilEnumResourcesEx function allows you to specify a remote cluster.

Example

The following example uses ResUtilEnumResources to list the names and states of all resources in the cluster.

//////////////////////////////////////////////////////////////////////
//  ClusDocEx_EnumDemo.cpp
//
//  Uses the ResUtilEnumResources function to list the names and
//  states of all cluster resources.
//
//  To compile and run this example you will need two other examples
//  from the documentation:  ClusDocEx.h (see "ClusDocEx.h") and
//  ClusDocEx_GetControlCodeOutput.cpp (see "Getting Information with
//  Control Codes").
//
//////////////////////////////////////////////////////////////////////
#include "ClusDocEx.h"
#include "ClusDocEx_GetControlCodeOutput.cpp"

DWORD
MyCallbackFunction(
    HRESOURCE hSelf,
    HRESOURCE hCurrentEnum,
    PVOID pData );

LPRESOURCE_CALLBACK g_pMyCallbackFunction = &MyCallbackFunction;

int main( void )
{
    wprintf( L"\n\nResource (State)\n----------------\n" );
    DWORD dwResult = ResUtilEnumResources(
                         NULL,
                         NULL,
                         pMyCallbackFunction,
                         NULL );
    if( dwResult != ERROR_SUCCESS )
    {
        ClusDocEx_DebugPrint( L"ResUtilEnumResources returned an error.", dwResult );
        return 1;
    }
    else
        return 0;
}

DWORD
MyCallbackFunction(
    HRESOURCE hSelf,
    HRESOURCE hCurrentEnum,
    PVOID pData )
{
    DWORD dwResult           = ERROR_SUCCESS,
          cbNameSize         = 0,
          dwState            = 0;

    WCHAR* pszState    = NULL;
    WCHAR* pszEnumName = ClusDocEx_ResGetControlCodeOutput(
                            hCurrentEnum,
                            NULL,
                            CLUSCTL_RESOURCE_GET_NAME,
                            &cbNameSize );
    if( pszEnumName == NULL )
    {
        dwResult = GetLastError();
        goto EndFunc;
    }

    dwState = GetClusterResourceState(
                  hCurrentEnum,
                  NULL,
                  NULL,
                  NULL,
                  NULL );
    switch( dwState )
    {
    case ClusterResourceOnline:
        pszState = L"Online";
        break;
    case ClusterResourceOffline:
        pszState = L"Offline";
        break;
    case ClusterResourcePending:
        pszState = L"Pending";
        break;
    case ClusterResourceOnlinePending:
        pszState = L"OnlinePending";
        break;
    case ClusterResourceOfflinePending:
        pszState = L"OfflinePending";
        break;
    case ClusterResourceFailed:
        pszState = L"Failed";
        break;
    case ClusterResourceInitializing:
        pszState = L"Initializing";
        break;
    default:
        pszState = L"Unknown";
        break;
    }
    wprintf( L"%ls (%ls)\n", pszEnumName, pszState );

EndFunc:
    LocalFree( pszEnumName );
    return dwResult;
}

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

OpenCluster, ClusterOpenEnum


ResUtilEnumResourcesEx

[This is preliminary documentation and subject to change.]

The ResUtilEnumResourcesEx utility function enumerates all of the resources in a specified cluster and initiates a user-defined operation for each resource.

DWORD WINAPI ResUtilEnumResourcesEx(
  HCLUSTER hCluster,
  HRESOURCE hSelf,
  LPCWSTR lpszResTypeName,
  LPRESOURCE_CALLBACK_EX pResCallBackEx,
  PVOID pParameter
);

Parameters

hCluster
[in] Handle to the cluster containing the resources to enumerate.
hSelf
[in] Optional handle to a cluster resource. The callback function is not invoked for a resource identified by hSelf.
lpszResTypeName
[in] Optional pointer to a name of a resource type that narrows the scope of resources to enumerate. If lpszResTypeName is specified, only resources of the specified type are enumerated.
pResCallBackEx
[in] Pointer to a user-defined function which will be called for each enumerated resource. This function must conform to the definition of LPRESOURCE_CALLBACK (note that parameter names are not part of the definition; they have been added here for clarity):
DWORD (*LPRESOURCE_CALLBACK_EX)(
  HRESOURCE hSelf,
  HRESOURCE hEnum,
  PVOID pParameter
);
hSelf
[in] The hSelf parameter passed to ResUtilEnumResourcesEx. Note that the callback function is never called when hSelf and hEnum refer to the same resource.
hEnum
[in] Handle to the resource currently being enumerated. ResUtilEnumResourcesEx opens and closes this handle automatically.
pParameter
[in] A generic buffer that allows you to pass any kind of data to the callback function.
pParameter
[in] A generic buffer that allows you to pass any kind of data to the callback function. ResUtilEnumResourcesEx does not use this parameter at all, it merely passes the pointer to the callback function. Whether or not you can pass NULL for the parameter depends on how the callback function is implemented.

Return Values

ResUtilEnumResourcesEx returns one of the following values.

Value | Description
ERROR_SUCCESS | The resources were successfully enumerated, and all calls to the callback function were successful.

If the operation was not successful, ResUtilEnumResourcesEx returns a Win32 error. If the callback function returns any value other than ERROR_SUCCESS, ResUtilEnumResourcesEx immediately halts the enumeration and returns the value returned by the callback function.

Remarks

ResUtilEnumResourcesEx is a convenient and easy-to-use alternative to the ClusterResourceEnum function.

Example

See the example for ResUtilEnumResources.

Requirements

Version: Requires Whistler.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterResourceEnum, ResUtilEnumResources


ResUtilFindDependentDiskResourceDriveLetter

The ResUtilFindDependentDiskResourceDriveLetter utility function retrieves the drive letter associated with a Physical Disk dependency of a resource.

DWORD WINAPI ResUtilFindDependentDiskResourceDriveLetter(
  HCLUSTER hCluster,
  HRESOURCE hResource,
  LPWSTR pszDriveLetter,
  DWORD* pcchDriveLetter
);

Parameters

hCluster
[in] Cluster handle.
hResource
[in] Handle to the resource to query for dependencies.
pszDriveLetter
[in] Buffer in which to store the drive letter.
pcchDriveLetter
[in out] On input, specifies the size of the pszDriveLetter buffer as a count of WCHARs. On output, specifies the size of the resulting data as a count of WCHARs that includes the terminating NULL.

Return Value

The ResUtilFindDependentDiskResourceDriveLetter function returns the following values.

Value | Description
ERROR_SUCCESS | The function completed successfully.
ERROR_NO_MORE_ITEMS | No Physical Disk dependency was found in the specified resource's list of dependencies.
ERROR_RESOURCE_NOT_PRESENT | No drive letter could be returned.
ERROR_MORE_DATA | The buffer passed in was too small. The pcchDriveLetter parameter specifies the required size.
Win32 error code | Other possible failures.

Remarks

Do not call this function from a resource DLL. It will cause a deadlock. You should have your resource extension call this function and write the results out as a private property that your resource DLL can then read.

If the resource identified by hResource depends on more than one Physical Disk resource, ResUtilFindDependentDiskResourceDriveLetter returns the drive letter of the first Physical Disk dependency that is enumerated for the resource.

Example Code

The following example takes a resource name as a command line argument and displays the drive letter associated with the resource's Physical Disk dependency (if any). This example uses the ClusDocEx.h header file defined in the Server Cluster documentation.

//////////////////////////////////////////////////////////////////////

#include "ClusDocEx.h"

int main( int argc, char argv[] )
{
    HCLUSTER hCluster = NULL;
    HRESOURCE hRes = NULL;
    DWORD dw;
    DWORD cchResDrive = ClusDocEx_DEFAULT_CCH;
    DWORD cchResName = ClusDocEx_DEFAULT_CCH;
    WCHAR* pszResDrive = new WCHAR[cchResDrive];
    WCHAR* pszResName = new WCHAR[cchResName];

    dw = ClusDocEx_ConvertArg( argv[1], pszResName, cchResName )

    if( dw == ERROR_SUCCESS )
    {
        hCluster = ClusDocEx_OpenLocalClusterWithName();
        if( hCluster != NULL )
        {
            hRes = OpenClusterResource( hCluster, pszResName );
            if( hRes != NULL )
            {
                dw = ResUtilFindDependentResourceDiskDriveLetter(
                          hCluster,
                          hRes,
                          pszResDrive,
                          &cchResDrive );

                if( dw == ERROR_MORE_DATA )
                {
                    delete [] pszResName;
                    pszResName = new WCHAR[cchResDrive];
                    dw = ResUtilFindDependentResourceDiskDriveLetter(
                             hCluster,
                             hRes,
                             pszResDrive,
                             &cchResDrive );
                }

               switch( dw )
               {
               case ERROR_SUCCESS:
                   wprintf( L"%ls depends on drive %ls.\n",
                            pszResName,
                            pszResDrive );
                   break;
               case ERROR_NO_MORE_ITEMS:
               case ERROR_RESOURCE_NOT_PRESENT:
                   wprintf( L"No Physical Disk dependency found for %ls.\n",
                            pszResName );
                   break;
               default:
                   ClusDocEx_DebugPrint( L"Could not obtain drive information", dw );
                   break;
               }
               CloseClusterResource( hRes );
           }
           else // if hRes == NULL
           {
               ClusDocEx_DebugPrint( L"Could not open a resource handle", GetLastError() );
           }
           CloseCluster( hCluster );
       }
       else // if hCluster == NULL
       {
           ClusDocEx_DebugPrint( L"Could not open a cluster handle", GetLastError() );
       }

    }
    delete [] pszResName;
    delete [] pszResDrive;
    return 0;
}

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetResourceDependency, ResUtilGetResourceDependencyByClass, ResUtilGetResourceDependencyByName, ResUtilGetResourceDependentIPAddressProps, ResUtilGetResourceNameDependency


ResUtilGetResourceDependency

The ResUtilGetResourceDependency function enumerates the dependencies of a specified resource and returns a handle to a dependency of a specified type.

HRESOURCE WINAPI ResUtilGetResourceDependency(
  HANDLE hSelf,
  LPCWSTR lpszResourceType
);

Parameters

hSelf
[in] Handle to the dependent resource. This resource depends on one or more resources.
lpszResourceType
[in] Null-terminated Unicode string specifying the resource type of the dependency to return.

Return Values

ResUtilGetResourceDependency returns one of the following values.

Value | Description
HRESOURCE | If the operation is successful, ResUtilGetResourceDependency returns a handle to one of the resources on which the resource specified by hSelf depends. The caller is responsible for closing the handle by calling CloseClusterResource.
NULL | The operation was not successful. For more information, call the Win32 function GetLastError.

Remarks

The ResUtilGetResourceDependency, ResUtilGetResourceDependencyByName, and ResUtilGetResourceNameDependency functions are very similar in that they all provide access to dependencies of a particular resource type. The following table summarizes the differences between the functions.

Function | How the dependent resource is specified | Requires cluster handle
ResUtilGetResourceDependency | Resource handle | No
ResUtilGetResourceDependencyByName | Resource handle | Yes
ResUtilGetResourceNameDependency | Resource name | No

Do not call ResUtilGetResourceDependency from any resource DLL entry point function. ResUtilGetResourceDependency can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example Code

As the following example illustrates, if you know that resource A depends on a Physical Disk resource, you can use ResUtilGetResourceDependency to obtain a handle to the dependency.

// String initialization and error checking omitted.

HCLUSTER hCluster = OpenCluster( lpszClusterName );

//
// Resource A depends on a Physical Disk resource.
// Get a handle to that resource.
//
HRESOURCE hResA = OpenClusterResource( hCluster, lpszResName );

HRESOURCE hResD = ResUtilGetResourceDependency{
                        hResA,
                        L"Physical Disk" };

// Close handles and free memory.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CloseClusterResource, GetLastError, ResUtilFindDependentDiskResourceDriveLetter, ResUtilGetResourceDependencyByClass, ResUtilGetResourceDependencyByName, ResUtilGetResourceDependentIPAddressProps, ResUtilGetResourceNameDependency


ResUtilGetResourceDependencyByClass

The ResUtilGetResourceDependencyByClass function enumerates the dependencies of a specified resource in a specified cluster and returns a handle to a dependency that matches a specified resource class.

HRESOURCE WINAPI ResUtilGetResourceDependencyByClass(
  HCLUSTER hCluster,
  HANDLE hSelf,
  PCLUS_RESOURCE_CLASS_INFO prci
  BOOL bRecurse
);

Parameters

hCluster
[in] Handle to the cluster to which the resource belongs.
hSelf
[in] Handle to the dependent resource. This resource depends on one or more resources.
prci
[in] Pointer to a CLUS_RESOURCE_CLASS_INFO structure describing the resource class of the dependency to return.
bRecurse
[in] Determines the scope of the search. If TRUE, the function checks the entire dependency tree under the dependent resource. If FALSE, the function checks only the resources on which the dependent resource directly depends.

Return Values

ResUtilGetResourceDependencyByClass returns one of the following values.

Value | Description
HRESOURCE | If the operation is successful, ResUtilGetResourceDependencyByClass returns a handle to one of the resources on which the resource specified by hSelf depends. The caller is responsible for closing the handle by calling CloseClusterResource.
NULL | The operation was not successful. For more information, call the Win32 function GetLastError.

Remarks

Do not call ResUtilGetResourceDependencyByClass from any resource DLL entry point function. ResUtilGetResourceDependencyByClass can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example Code

As the following example illustrates, if you know that resource A depends on a storage class resource, you can use ResUtilGetResourceDependencyByClass to obtain a handle to the storage class resource without knowing anything else about it.

// String initialization and error checking omitted.

HCLUSTER hCluster = OpenCluster( lpszClusterName );

//
// Resource A depends on a storage class resource.
// Get a handle to that resource.
//
HRESOURCE hResA = OpenClusterResource( hCluster, lpszResName );

PCLUS_STORAGE_CLASS_INFO pClassInfo;

pClassInfo->rc = CLUS_RESCLASS_STORAGE;

//
// Returns a handle to the storage class resource on which resource A depends.
// Can now perform a variety of operations on the dependency.
//
HRESOURCE hResD = ResUtilGetResourceDependencyByClass{
                        hCluster,
                        hResA,
                        pClassInfo };

// Close handles and free memory.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CloseClusterResource, GetLastError, ResUtilFindDependentDiskResourceDriveLetter, ResUtilGetResourceDependency, ResUtilGetResourceDependencyByName, ResUtilGetResourceDependentIPAddressProps, ResUtilGetResourceNameDependency


ResUtilGetResourceDependencyByName

The ResUtilGetResourceDependencyByName function enumerates the dependencies of a specified resource in a specified cluster and returns a handle to a dependency of a specified type.

HRESOURCE WINAPI ResUtilGetResourceDependencyByName(
  HCLUSTER hCluster,
  HANDLE hSelf,
  LPCWSTR lpszResourceType,
  BOOL bRecurse
);

Parameters

hCluster
[in] Handle to the cluster to which the resource belongs.
hSelf
[in] Handle to the dependent resource. This resource depends on one or more resources.
lpszResourceType
[in] NULL-terminated Unicode string specifying the resource type of the dependency to return.
bRecurse
[in] Determines the scope of the search. If TRUE, the function checks the entire dependency tree under the dependent resource. If FALSE, the function checks only the resources on which the dependent resource directly depends.

Return Values

ResUtilGetResourceDependencyByName returns one of the following values.

Value | Description
HRESOURCE | If the operation is successful, ResUtilGetResourceDependencyByName returns a handle to one of the resources on which the resource specified by hSelf depends. The caller is responsible for closing the handle by calling CloseClusterResource.
NULL | The operation was not successful. For more information, call the Win32 function GetLastError.

Remarks

The ResUtilGetResourceDependencyByName, ResUtilGetResourceDependency, and ResUtilGetResourceNameDependency functions are very similar in that they all provide access to dependencies of a particular resource type. The following table summarizes the differences between the functions.

Function | How the dependent resource is specified | Requires cluster handle
ResUtilGetResourceDependency | Resource handle | No
ResUtilGetResourceDependencyByName | Resource handle | Yes
ResUtilGetResourceNameDependency | Resource name | No

Remarks

Do not call ResUtilGetResourceDependencyByName from any resource DLL entry point function. ResUtilGetResourceDependencyByName can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example Code

As the following example illustrates, if you know that resource A depends on a Physical Disk resource, you can use ResUtilGetResourceDependencyByName to obtain a handle to the dependency.

// String initialization and error checking omitted.

HCLUSTER hCluster = OpenCluster( lpszClusterName );

//
// Resource A depends on a storage class resource.
// Get a handle to that resource.
//
HRESOURCE hResA = OpenClusterResource( hCluster, lpszResName );

HRESOURCE hResD = ResUtilGetResourceDependencyByName{
                        hCluster,
                        hResA,
                        L"Physical Disk" };

// Close handles and free memory.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CloseClusterResource, GetLastError, ResUtilFindDependentDiskResourceDriveLetter, ResUtilGetResourceDependency, ResUtilGetResourceDependencyByClass, ResUtilGetResourceDependentIPAddressProps, ResUtilGetResourceNameDependency


ResUtilGetResourceDependentIPAddressProps

The ResUtilGetResourceDependentIPAddressProps utility function retrieves the private properties of the first IP Address dependency found for a specified resource.

DWORD WINAPI ResUtilGetResourceDependentIPAddressProps(
  HRESOURCE hResource,
  LPWSTR pszAddress,
  DWORD* pcchAddress,
  LPWSTR pszSubnetMask,
  DWORD* pcchSubnetMask,
  LPWSTR pszNetwork,
  DWORD* pcchNetwork
);

Parameters

hResource
[in] Handle to the resource to query for dependencies.
pszAddress
[out] Output buffer for returning the value of the Address private property.
pcchAddress
[in out] On input, specifies the size of the pszAddress buffer as a count of WCHARs. On output, specifies the size of the resulting data as a count of WCHARs that includes the terminating NULL.
pszSubnetMask
[out] Output buffer for returning the value of the SubnetMask private property.
pcchSubnetMask
[in out] On input, specifies the size of the pszSubnetMask buffer as a count of WCHARs. On output, specifies the size of the resulting data as a count of WCHARs that includes the terminating NULL.
pszNetwork
[out] Output buffer for returning the value of the Network private property.
pcchNetwork
[in out] On input, specifies the size of the pszNetwork buffer as a count of WCHARs. On output, specifies the size of the resulting data as a count of WCHARs that includes the terminating NULL.

Return Value

ResUtilGetResourceDependentIPAddressProps returns the following values.

Value | Description
ERROR_SUCCESS | The function completed successfully.
ERROR_NO_MORE_ITEMS | No IP Address dependency was found in the specified resource's list of dependencies.
ERROR_NO_MORE_ITEMS, ERROR_RESOURCE_NOT_PRESENT | No IP Address dependency was found.
ERROR_MORE_DATA | The size of one of the buffers was too small to hold the resulting data.
Win32 error code | Other possible failures.

Remarks

Do not call ResUtilGetResourceDependentIPAddressProps from any resource DLL entry point function. ResUtilGetResourceDependentIPAddressProps can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilFindDependentDiskResourceDriveLetter, ResUtilGetResourceDependency, ResUtilGetResourceDependencyByClass, ResUtilGetResourceDependencyByName, ResUtilGetResourceNameDependency


ResUtilGetResourceNameDependency

The ResUtilGetResourceNameDependency function enumerates the dependencies of a specified resource in the local cluster and returns a handle to a dependency of a specified resource type.

HRESOURCE WINAPI ResUtilGetResourceNameDependency(
  LPCWSTR lpszResourceName,
  LPCWSTR lpszResourceType
);

Parameters

lpszResourceName
[in] Null-terminated Unicode string specifying the name of the dependent resource. This resource depends on one or more resources.
lpszResourceType
[in] Null-terminated Unicode string specifying the resource type of the dependency to return.

Return Values

ResUtilGetResourceNameDependency returns one of the following values.

Value | Description
HRESOURCE | If the operation is successful, ResUtilGetResourceNameDependency returns a handle to one of the resources on which the resource specified by lpszResourceName depends. The caller is responsible for closing the handle by calling CloseClusterResource.
NULL | The operation was not successful. For more information, call the Win32 function GetLastError.

Remarks

The ResUtilGetResourceNameDependency, ResUtilGetResourceDependency, and ResUtilGetResourceDependencyByName functions are very similar in that they all provide access to dependencies of a particular resource type. The following table summarizes the differences between the functions.

Function | How the dependent resource is specified | Requires cluster handle
ResUtilGetResourceDependency | Resource handle | No
ResUtilGetResourceDependencyByName | Resource handle | Yes
ResUtilGetResourceNameDependency | Resource name | No

Do not call ResUtilGetResourceNameDependency from any resource DLL entry point function. ResUtilGetResourceNameDependency can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Example Code

As the following example illustrates, if you know that resource A depends on a Physical Disk resource, you can use ResUtilGetResourceNameDependency to obtain a handle to the dependency.

// String initialization and error checking omitted.

HRESOURCE hResD = ResUtilGetResourceNameDependency{
                        L"Resource_A_Name",
                        L"Physical Disk" };

// Close handles and free memory.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CloseClusterResource, GetLastError, ResUtilFindDependentDiskResourceDriveLetter, ResUtilGetResourceDependency, ResUtilGetResourceDependencyByClass, ResUtilGetResourceDependencyByName, ResUtilGetResourceDependentIPAddressProps


ResUtilIsResourceClassEqual

The ResUtilIsResourceClassEqual function tests whether the resource class of a specified resource is equal to a specified resource class.

BOOL WINAPI ResUtilIsResourceClassEqual(
  PCLUS_RESOURCE_CLASS_INFO prci,
  HRESOURCE hResource
);

Parameters

prci
[in] Pointer to a CLUS_RESOURCE_CLASS_INFO structure describing the resource class.
hResource
[in] Handle to the resource whose class is to be compared to prci.

Return Value

ResUtilIsResourceClassEqual returns one of the following values.

Value | Description
TRUE | The resource class of hResource is equal to the resource class described by prci.
FALSE | The resource classes are not equal.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilResourcesEqual


ResUtilResourcesEqual

The ResUtilResourcesEqual utility function tests whether two resource handles represent the same resource.

BOOL WINAPI ResUtilResourcesEqual(
  HRESOURCE hSelf,
  HRESOURCE hResource
);

Parameters

hSelf
[in] Handle to one of the resources.
hResource
[in] Handle to the other resource.

Return Values

ResUtilResourcesEqual returns one of the following values.

Value | Description
TRUE | The resources are equal.
FALSE | The resources are not equal.

Remarks

The ResUtilResourcesEqual utility function compares the two resources by retrieving their names. To retrieve the names, ResUtilResourcesEqual passes the CLUSCTL_RESOURCE_GET_NAME control code to the ClusterResourceControl function. If the names are the same, the resources are equal.

Do not pass LPC and RPC handles in the same function call. If you do, the call will raise an RPC exception and can result in additional destructive effects. For information on how LPC and RPC handles are created, see Using Object Handles and OpenCluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUSCTL_RESOURCE_GET_NAME, ClusterResourceControl


ResUtilResourceTypesEqual

The ResUtilResourceTypesEqual utility function tests whether a resource type matches the resource type name of a specified resource.

BOOL WINAPI ResUtilResourceTypesEqual(
  LPCWSTR lpszResourceTypeName,
  HRESOURCE hResource
);

Parameters

lpszResourceTypeName
[in] Pointer to the resource type name to test.
hResource
[in] Handle of the resource to test.

Return Values

ResUtilResourceTypesEqual returns one of the following values.

Value | Description
TRUE | The resource types are equal.
FALSE | The resource types are not equal.

Remarks

The ResUtilResourceTypesEqual utility function compares the resource type name pointed to by lpszResourceTypeName with the resource type name of the resource identified by hResource. To perform the comparison, ResUtilResourceTypesEqual passes the CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code to the ClusterResourceControl function to retrieve the resource type. If the two resource type names are the same, the resource types are equal. Note that ResUtilResourceTypesEqual compares the resource type name and not the resource type display name.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUSCTL_RESOURCE_GET_RESOURCE_TYPE, ClusterResourceControl


Service Utility Functions

The service utility functions start and stop a service and verify if a service is up and running. The service utility functions follow.

Function | Description
ResUtilFreeEnvironment | Deletes an environment block created by ResUtilGetEnvironmentWithNetName
ResUtilGetEnvironmentWithNetName | Adjusts the environment to allow a resource to be located by a cluster network name.
ResUtilSetResourceServiceEnvironment | Used by a resource DLL to create an environment block for a service.
ResUtilSetResourceServiceStartParameters | Used by a resource DLL to adjust the start parameters of a service so that it will operate correctly as a cluster resource.
ResUtilStartResourceService | Starts a service.
ResUtilStopResourceService | Stops a named service.
ResUtilStopService | Stops a service identified by a handle.
ResUtilVerifyResourceService | Checks if a named service is operational.
ResUtilVerifyService | Checks if a service identified by a handle is operational.


ResUtilFreeEnvironment

The ResUtilFreeEnvironment function destroys the environment variable block created with ResUtilGetEnvironmentWithNetName.

DWORD WINAPI ResUtilFreeEnvironment(
  LPVOID lpEnvironment
);

Parameters

lpEnvironment
[in] Pointer to the environment variable block returned from ResUtilGetEnvironmentWithNetName.

Return Values

This function has no return values.

SeeAlso

ResUtilGetEnvironmentWithNetName

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


ResUtilGetEnvironmentWithNetName

The ResUtilGetEnvironmentWithNetName function adjusts environment data for a resource so that the resource uses a cluster network name to identify its location. The resource must be dependent on a Network Name resource.

LPVOID WINAPI ResUtilGetEnvironmentWithNetName(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to a resource that depends on a Network Name resource.

Return Values

ResUtilGetEnvironmentWithNetName returns one of the following values.

Value | Description
Non-NULL | If the operation was successful, ResUtilGetEnvironmentWithNetName returns a pointer to the new environment block.
NULL | The operation was not successful. For more information, call the Win32 function GetLastError.

Remarks

The ResUtilGetEnvironmentWithNetName function appends environment variables to the current environment block. Pass the returned environment block to CreateProcess when starting the resource to achieve the following effects:

  • Clients and the cluster can locate the resource by using the name of the Network Name resource.
  • If the resource calls GetComputerName, GetComputerNameEx, or GetHostByName, the network name will be returned regardless of which node is currently hosting the resource.

If the resource identified by hResource is not dependent on a Network Name resource, ResUtilGetEnvironmentWithNetName returns NULL.

Use ResUtilFreeEnvironment to destroy the environment block.

Do not call ResUtilGetEnvironmentWithNetName from any resource DLL entry point function. ResUtilGetEnvironmentWithNetName can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilSetResourceServiceEnvironment, CreateProcess, GetLastError


ResUtilSetResourceServiceEnvironment

The ResUtilSetResourceServiceEnvironment function adjusts the environment data for a service so that the service uses a cluster network name to identify its location. This function must be called from a resource DLL.

DWORD WINAPI ResUtilSetResourceServiceEnvironment(
  LPCWSTR pszServiceName,
  HRESOURCE hResource,
  PLOG_EVENT_ROUTINE pfnLogEvent,
  RESOURCE_HANDLE hResourceHandle
);

Parameters

pszServiceName
[in] Pointer a null-terminated Unicode string containing the name of the service.
hResource
[in] Resource handle for the service obtained from OpenClusterResource.
pfnLogEvent
[in] Pointer to the LogEvent entry point function of the resource DLL managing the service.
hResourceHandle
[in] Resource handle required by the LogEvent entry point function. Use the handle passed to the DLL in the Open entry point function.

Return Values

ResUtilSetResourceServiceEnvironment returns one of the following values.

Value | Description
ERROR_SUCCESS | The operation was successful.
Win32 Error | The operation was not successful.

Remarks

ResUtilSetResourceServiceEnvironment calls ResUtilGetEnvironmentWithNetName and stores the resulting environment block in a registry entry for the service. For more information about the effects of the environment block, see ResUtilGetEnvironmentWithNetName.

If your resource DLL manages a service, create a worker thread and use ResUtilSetResourceServiceStartParameters and ResUtilSetResourceServiceEnvironment when bringing the service online.

Do not call ResUtilSetResourceServiceEnvironment from any resource DLL entry point function. ResUtilSetResourceServiceEnvironment can safely be called from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetEnvironmentWithNetName


ResUtilSetResourceServiceStartParameters

The ResUtilSetResourceServiceStartParameters function adjusts the start parameters of a specified service so that it will operate correctly as a cluster resource. It must be called from a resource DLL.

DWORD WINAPI ResUtilSetResourceServiceStartParameters(
  LPCWSTR pszServiceName,
  SC_HANDLE schSCMHandle,
  LPSC_HANDLE phService,
  PLOG_EVENT_ROUTINE pfnLogEvent,
  RESOURCE_HANDLE hResourceHandle
);

Parameters

pszServiceName
[in] Pointer to a null-terminated Unicode string specifying the name of the service.
schSCMHandle
[in] Handle to the Service Control Manager (SCM) or NULL. If NULL, the function will attempt to open a handle to the SCM.
phService
[in out] On input, a NULL service handle. On output, handle to the specified service if the call was successful, otherwise NULL.
pfnLogEvent
[in] Pointer to the LogEvent entry point function of the resource DLL managing the service.
hResourceHandle
[in] Resource handle required by the LogEvent entry point function. Use the handle passed to the DLL in the Open entry point function.

Return Values

ResUtilSetResourceServiceStartParameters returns one of the following values.

Value | Description
ERROR_SUCCESS | The operation was successful.
Win32 Error | The operation was not successful.

Remarks

ResUtilSetResourceServiceStartParameters verifies that the service is not disabled, changes the service configuration to manual start and prevents the service from restarting in response to failure. This allows the cluster and the resource DLL to control the service.

If your resource DLL manages a service, use ResUtilSetResourceServiceStartParameters and ResUtilSetResourceServiceEnvironment before bringing the service online.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilSetResourceServiceEnvironment, Online, LogEvent, Open


ResUtilStartResourceService

The ResUtilStartResourceService utility function starts a service.

DWORD WINAPI ResUtilStartResourceService(
  LPWTSTR pszServiceName,
  LPSC_HANDLE phServiceHandle
);

Parameters

pszServiceName
[in] Null-terminated Unicode string containing the name of the service to start.
phServiceHandle
[out] Optional pointer to a handle in which the handle to the started service is returned. This handle must be closed either by a call to the cluster utility function ResUtilStopService or the Win32 function CloseServiceHandle.

Return Values

ResUtilStartResourceService returns one of the following values.

Value | Description
ERROR_SUCCESS | The service was successfully started.
ERROR_SERVICE_NEVER_STARTED | The service was not started.

If the operation was not successful, ResUtilStartResourceService can return a Win32 error value.

Remarks

The ResUtilStartResourceService utility function encapsulates the necessary calls to the service control manager, providing a convenient way to start services in the cluster. Using ResUtilStartResourceService is optional. If the service to be started requires specific access restrictions or other special handling, the Win32 service control manager functions can be used instead.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilStopService, CloseServiceHandle


ResUtilStopResourceService

The ResUtilStopResourceService utility function stops a named service.

DWORD WINAPI ResUtilStopResourceService(
  LPCWSTR pszServiceName
);

Parameters

pszServiceName
[in] Null-terminated Unicode string containing the name of the service to stop.

Return Values

ResUtilStopResourceService returns one of the following values.

Value |  | Description
ERROR_SUCCESS | The service was successfully stopped.
ERROR_TIMEOUT | Service did not stop after a reasonable number of retries.

If the operation was not successful, ResUtilStopResourceService can return a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilStartResourceService


ResUtilStopService

The ResUtilStopService utility function stops a service identified by a handle.

DWORD WINAPI ResUtilStopService(
  SC_HANDLE hServiceHandle
);

Parameters

hServiceHandle
[in] Handle of the service to stop.

Return Values

ResUtilStopService returns one of the following values.

Value |  | Description
ERROR_SUCCESS | The service was successfully stopped.
ERROR_TIMEOUT | Service did not stop after a reasonable number of retries.

If the operation was not successful, ResUtilStopService can return a Win32 error value.

Remarks

The ResUtilStopService utility function closes the handle specified in ServiceHandle when it stops the service.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


ResUtilTerminateServiceProcessFromResDll

[This is preliminary documentation and subject to change.]

The ResUtilTerminateServiceProcessFromResDll function attempts to terminate the process of a service being managed as a cluster resource by a resource DLL.

DWORD WINAPI ResUtilTerminateServiceProcessFromResDll(
    IN DWORD dwServicePid,
    IN BOOL bOffline,
    OUT PDWORD pdwResourceState,
    IN PLOG_EVENT_ROUTINE pfnLogEvent,
    IN RESOURCE_HANDLE hResourceHandle
);

Paremeters

dwServicePid
[in] The process ID of the service process to terminate.
bOffline
[in] Indicates whether the resource is being taken offline or is being terminated. Specify TRUE if calling from the Offline entry point or from a worker thread created to take the resource offline. Otherwise specify FALSE and the function will assume you are terminating the resource.
pdwResourceState
[out] Optional pointer to a DWORD which returns the resulting state of the resource, which will be either ClusterResourceFailed or ClusterResourceOffline (for a complete list of resource states see GetClusterResourceState). Pass NULL if you don't need this information.
pfnLogEvent
[out] Pointer to the LogEvent function used by your resource DLL. This pointer is passed to your resource DLL in the Startup entry point.
hResourceHandle
[in] The Resource Monitor's handle to the resource. This handle is passed to your resource DLL in the Open entry point and must be saved as part of the resource's instance data.

Return Values

ResUtilTerminateServiceProcessFromResDll returns ERROR_SUCCESS if the service process was successfully terminated. Other return values indicate failure. Note that ResUtilTerminateServiceProcessFromResDll uses pfnLogEvent and hResourceHandle to write to your resource DLL's event log, which may help troubleshoot failures.

Remarks

You should only call ResUtilTerminateServiceProcessFromResDll when terminating a resource or when taking a resource offline.

Requirements

Version: Requires Whistler.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


ResUtilVerifyResourceService

The ResUtilVerifyResourceService utility function verifies that a named service is starting or currently running.

DWORD WINAPI ResUtilVerifyResourceService(
  LPWTSTR pszServiceName
);

Parameters

pszServiceName
[in] Null-terminated Unicode string containing the name of the service to verify.

Return Values

ResUtilVerifyResourceService returns one of the following values.

Value |  | Description
ERROR_SUCCESS | The service is operational; it is either starting or currently running.
ERROR_SERVICE_NOT_ACTIVE | The service is not operational.

If ResUtilVerifyResourceService cannot determine whether the service is starting or currently running, it returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


ResUtilVerifyService

The ResUtilVerifyService utility function checks if a service identified by a handle is starting or currently running.

DWORD WINAPI ResUtilVerifyService(
  SC_HANDLE hServiceHandle
);

Parameters

hServiceHandle
[in] Handle of the service to verify.

Return Values

ResUtilVerifyService returns one of the following values.

Value |  | Description
ERROR_SUCCESS | The service is operational; it is either starting or currently running.
ERROR_SERVICE_NOT_ACTIVE | The service is not operational.

If ResUtilVerifyService cannot determine whether the service is starting or currently running, it returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.


Thread Management Utility Functions

The thread management utility functions create and start a worker thread and allow a pending operation to be canceled with correct synchronization. The thread management utility functions follow.

Function | Description
ClusWorkerCheckTerminate | Determines whether a worker thread should exit as soon as possible.
ClusWorkerCreate | Creates a worker thread.
ClusWorkerTerminate | Terminates a worker thread.


ClusWorkerCheckTerminate

The ClusWorkerCheckTerminate utility function determines whether a worker thread should exit as soon as possible.

BOOL WINAPI ClusWorkerCheckTerminate(
  PCLUS_WORKER Worker
);

Parameters

Worker
[in] Pointer to a CLUS_WORKER structure describing the thread to check.

Return Values

ClusWorkerCheckTerminate returns one of the following values.

Value | Description
TRUE | The thread should terminate.
FALSE | The thread should not terminate.

Remarks

The ClusWorkerCheckTerminate utility function checks the Terminate member of the CLUS_WORKER structure to determine whether the thread pointed to by Worker should exit. The Terminate member is used to prevent a race condition from occurring when multiple threads call ClusWorkerTerminate on the same worker thread.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUS_WORKER, ClusWorkerCreate, ClusWorkerTerminate


ClusWorkerCreate

The ClusWorkerCreate utility function creates a worker thread.

DWORD WINAPI ClusWorkerCreate(
  PCLUS_WORKER Worker,
  PWORKER_START_ROUTINE lpStartAddress,
  PVOID lpParameter
);

Parameters

Worker
[out] Pointer to a CLUS_WORKER structure that is filled in with a handle to the created thread and a flag that indicates whether the handle should be terminated. The caller should never need to refer to or change the members of this structure.
lpStartAddress
[in] Pointer to the address of a function that should be called by the worker thread.
lpParameter
[in] A parameter to pass to the function whose address is pointed to by lpStartAddress.

Return Values

ClusWorkerCreate returns one of the following values.

Value |  | Description
ERROR_SUCCESS | The thread was created successfully.

If the operation was not successful, ClusWorkerCreate returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUS_WORKER, ClusWorkerCheckTerminate, ClusWorkerTerminate


ClusWorkerTerminate

The ClusWorkerTerminate utility function terminates a worker thread.

VOID WINAPI ClusWorkerTerminate(
  PCLUS_WORKER Worker
);

Parameters

Worker
[in] Pointer to a CLUS_WORKER structure describing the thread to check.

Return Values

This function has no return values.

Remarks

The ClusWorkerTerminate utility function checks the hThread and Terminate members of the CLUS_WORKER structure pointed to by Worker. If hThread is non-NULL and Terminate is set to FALSE, indicating that this is your first call to ClusWorkerTerminate, the function waits for the thread to exit before returning. Otherwise, if you have called ClusWorkerTerminate previously, indicated by Terminate being set to TRUE, the function may return before the thread has terminated.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUS_WORKER, ClusWorkerCreate, ClusWorkerCheckTerminate


Resource DLL Functions

The Resource DLL functions allow the Cluster service to manage resources indirectly through a Resource Monitor and a resource DLL. The Cluster service initiates requests with a Resource Monitor, and the Resource Monitor passes the requests to the resource DLL. Status and event information are passed back from the resource DLL through the Resource Monitor to the Cluster service.

Refer to the following sections.

Function Subset | Description
Resource DLL Entry Point Functions | Functions that you must implement in your resource DLL to provide a resource management interface for the Cluster service.
Resource DLL Callback Functions | Implemented by Resource Monitors. Resource DLLs invoke callback functions to report resource status and event information.
Cluster Database Access Functions | Provide resource DLLs the direct access to the cluster database they need in order to define and initialize properties.

The cluster utility functions are also essential to resource DLL operation, especially the following subsets:

Resource Utility Functions

Service Utility Functions

Thread Management Utility Functions

For more information on the process of creating a resource DLL, see Creating Resource Types.


Resource DLL Entry Point Functions

To initiate an operation on a resource, the Cluster service invokes (by means of a Resource Monitor) the appropriate resource DLL entry point function in the resource DLL supporting the resource. The resource DLL either performs the operation, signals the Resource Monitor to apply default processing (if any), or both. The developer of the DLL is responsible for providing entry point implementations that serve the needs of the resources supported by the DLL.

Some entry point functions should be handled by the resource DLL; others should be handled by the Resource Monitor. When and how an entry point function should be supported often depends on the resources managed by the DLL. For example, the Arbitrate and Release entry point functions must be implemented for resources that can act as the cluster's quorum resource and must not be implemented for non-quorum capable resources.

The Resource API defines the following resource DLL entry point functions for managing resources:

Entry point function | Description
Arbitrate | Allows a node to attempt to regain ownership of a quorum resource.
Close | Removes a resource instance from the cluster.
IsAlive | Determines if a resource is actually operational.
LooksAlive | Determines if a resource appears to be available for use.
Offline | Performs a graceful shutdown of the resource.
Online | Starts the resource and makes it available to the cluster.
Open | Creates a new resource instance.
Release | Releases a quorum resource from arbitration.
ResourceControl | Supports resource control codes.
ResourceTypeControl | Supports resource type control codes.
Startup | Receives the LogEvent and SetResourceStatus callbacks and returns a function table.
Terminate | Performs an immediate shutdown of the resource.


Arbitrate

The Arbitrate entry point function allows a node to attempt to regain ownership of a quorum resource.

DWORD WINAPI Arbitrate(
  RESID ResourceId,
  PQUORUM_RESOURCE_LOST LostQuorumResource
);

Parameters

ResourceId
[in] Resource identifier for the quorum resource to be owned.
LostQuorumResource
[in] Pointer to a callback function that should be called if control of the quorum resource is lost after being successfully gained.

Return Values

Value | Meaning
ERROR_SUCCESS | The arbitration was successful and the quorum resource remains defended.
Win32 error code | The arbitration was not successful.

Remarks

The Arbitrate entry point function is implemented for quorum resources only. Expect this entry point function to be called only after both Startup and Open have been called.

Implementations of Arbitrate should take less than 300 milliseconds to complete.

If Arbitrate is successful, make sure that only the current node can successfully arbitrate for the quorum resource represented by ResourceId. For example, a disk resource can implement a defense by continually replacing the reservation made on it once per second.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


Close

The Close entry point function closes a resource.

VOID WINAPI Close(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier of the resource to close.

Return Values

None. Call the Win32 function SetLastError to specify that an error has occurred.

Remarks

For effective implementation strategies of the Close entry point function, see Implementing Close.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions, SetLastError


IsAlive

The IsAlive entry point function determines if a resource is available for use.

BOOL WINAPI IsAlive(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the resource to poll.

Return Values

Value | Meaning
TRUE | The resource is online and functioning properly.
FALSE | The resource is not functioning properly.

Remarks

For effective implementation strategies of the IsAlive entry point function, see Implementing IsAlive.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions, NetShareGetInfo


LooksAlive

The LooksAlive entry point function determines if a resource appears to be available for use.

BOOL WINAPI LooksAlive(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the resource to poll.

Return Values

Value | Meaning
TRUE | The resource is probably online and available for use.
FALSE | The resource may not be functioning properly.

Remarks

For effective implementation strategies of the LooksAlive entry point function, see Implementing LooksAlive.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


Offline

The Offline entry point function marks a resource as unavailable for use after cleanup processing is complete.

DWORD WINAPI Offline(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the resource to be taken offline.

Return Values

Value | Meaning
ERROR_SUCCESS | The request completed successfully, and the resource is offline.
ERROR_IO_PENDING | The request is still pending, and a thread has been activated to process the offline request.

If the operation was not successful for other reasons, Offline should return a Win32 error value.

Remarks

If the Offline entry point function returns a Win32 error value other than ERROR_IO_PENDING, the Resource Monitor logs an event and calls the Terminate entry point.

For effective implementation strategies of the Offline entry point function, see Implementing Offline.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions, NetShareDel


Online

The Online entry point function marks a resource as available for use.

DWORD WINAPI Online(
  RESID ResourceId,
  PHANDLE EventHandle
);

Parameters

ResourceId
[in] Resource identifier for the resource to be made available.
EventHandle
[in, out] On input, EventHandle is NULL. On output, EventHandle contains a handle to a nonsignaled synchronization object. The resource DLL can signal this handle at any time to report a resource failure to the Resource Monitor. EventHandle can also be set to NULL on output, indicating that the resource does not support asynchronous event notification.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful, and the resource is now online.
ERROR_RESOURCE_NOT_AVAILABLE | The resource was arbitrated with some other systems, and one of the other systems won the arbitration. Only quorum-capable resources return this value.
ERROR_IO_PENDING | The request is pending, and a thread has been activated to process the online request.

If the operation was not successful for other reasons, Online should return a Win32 error value.

Remarks

If the Online entry point function returns a Win32 error value other than ERROR_IO_PENDING, the Resource Monitor logs an event and calls the Terminate entry point.

Returning a valid EventHandle yields the following benefits:

  • The Resource Monitor will not perform LooksAlive polling. Avoiding this overhead is often useful, particularly when your DLL supports multiple resource instances.
  • You can report resource failure at any time by signaling the handle. The Resource Monitor will immediately call IsAlive to verify that the resource has failed..

For effective implementation strategies of the Online entry point function, see Implementing Online.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions, NetShareAdd


Open

The Open entry point function opens a resource.

RESID WINAPI Open(
  LPCWSTR ResourceName,
  HKEY ResourceKey,
  RESOURCE_HANDLE ResourceHandle
);

Parameters

ResourceName
[in] Name of the resource to open.
ResourceKey
[in] Cluster database key for the cluster that includes the resource represented by ResourceName.
ResourceHandle
[in] Handle to be passed to the SetResourceStatus callback function in the Startup entry point function.

Return Values

If the operation was successful, Open returns a resource identifier (RESID).

If the operation was not successful, Open returns NULL. Call the Win32 function SetLastError to specify that an error has occurred.

Remarks

The Open entry point function opens a resource with the name identified by the ResourceName parameter and returns its resource identifier. The resource identifier can be used in future calls to other Resource API entry points to identify the resource.

Never close the handle represented by the ResourceHandle parameter or use it for any purpose other than passing it to the Resource Monitor through either the LogEvent callback function or the SetResourceStatus callback function.

For effective implementation strategies of the Open entry point function, see Implementing Open.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions, LogEvent, SetLastError, SetResourceStatus


Release

The Release entry point function releases the quorum resource from arbitration.

DWORD WINAPI Release(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the quorum resource to be released.

Return Values

Value | Meaning
ERROR_SUCCESS | The quorum resource was successfully released and is no longer being defended.
ERROR_HOST_NODE_NOT_OWNER | The quorum resource was not being previously arbitrated.
Win32 error code | The quorum resource was not successfully released.

Remarks

The Release entry point function is implemented for quorum resources only. A quorum resource might have to be released when the Cluster service is shut down or when the quorum resource has to be physically moved to a different node in the cluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


ResourceControl

The ResourceControl entry point function performs an operation that applies to a resource.

DWORD WINAPI ResourceControl(
  RESID ResourceId,
  DWORD ControlCode,
  LPVOID InBuffer,
  DWORD InBufferSize,
  LPVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned
);

Parameters

ResourceId
[in] Resource identifier of the affected resource.
ControlCode
[in] Control code that represents the operation to be performed. Refer to the following topics for information on supporting specific control codes:

CLUSCTL_RESOURCE_ADD_DEPENDENCY

CLUSCTL_RESOURCE_ADD_OWNER

CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT

CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED

CLUSCTL_RESOURCE_CLUSTER_VERSION_CHANGED

CLUSCTL_RESOURCE_DELETE

CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT

CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES

CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES

CLUSCTL_RESOURCE_EVICT_NODE

CLUSCTL_RESOURCE_GET_CHARACTERISTICS

CLUSCTL_RESOURCE_GET_CLASS_INFO

CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

CLUSCTL_RESOURCE_GET_FLAGS

CLUSCTL_RESOURCE_GET_NAME

CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS

CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES

CLUSCTL_RESOURCE_GET_RESOURCE_TYPE

CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES

CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES

CLUSCTL_RESOURCE_INSTALL_NODE

CLUSCTL_RESOURCE_REMOVE_DEPENDENCY

CLUSCTL_RESOURCE_REMOVE_OWNER

CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES

CLUSCTL_RESOURCE_SET_NAME

CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES

CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO

CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID

CLUSCTL_RESOURCE_UNKNOWN

CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES

CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES

InBuffer
[in] Pointer to a buffer containing data to be used in the operation. InBuffer can be NULL if no data is required.
InBufferSize
[in] Size, in bytes, of the buffer pointed to by InBuffer.
OutBuffer
[out] Pointer to a buffer containing data resulting from the operation. OutBuffer can be NULL if the operation does not need to return data.
OutBufferSize
[in] Size, in bytes, of the available space pointed to by OutBuffer.
BytesReturned
[out] Actual size, in bytes, of the data resulting from the operation.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation associated with ControlCode was completed successfully.
ERROR_INVALID_FUNCTION | The resource DLL requested that the Resource Monitor perform default processing (if any) for Control Code in addition to processing supplied by the DLL (if any).
ERROR_MORE_DATA | The allocated size of OutBuffer was too small to hold the requested data. BytesReturned indicates the required size. Always include the terminating NULL when calculating the byte sizes of strings.
ERROR_RESOURCE_PROPERTIES_STORED | Indicates that new property values for a resource have been set in the cluster database, but the properties have not yet taken effect. The new property values will be applied after the resource is taken offline and brought online.
Win32 Error | The operation was unsuccessful.

Remarks

Some control codes should be handled by the resource DLL, while others should be left to the Resource Monitor. For effective implementation strategies of the ResourceControl entry point function, see Implementing ResourceControl.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


ResourceTypeControl

The ResourceTypeControl entry point function performs an operation that applies to a resource type.

DWORD WINAPI ResourceTypeControl(
  LPCWSTR ResourceTypeName,
  DWORD ControlCode,
  LPVOID InBuffer,
  DWORD InBufferSize,
  LPVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned
);

Parameters

ResourceTypeName
[in] Type of resource to be affected by the operation.
ControlCode
[in] Control code that represents the operation to be performed. For a list of all valid values for the ControlCode parameter, see Resource Type Control Codes.
InBuffer
[in] Pointer to a buffer containing data to be used in the operation. InBuffer can be NULL if the operation does not require data.
InBufferSize
[in] Size, in bytes, of the buffer pointed to by InBuffer.
OutBuffer
[out] Pointer to a buffer containing data resulting from the operation. OutBuffer can be NULL if the operation returns no data.
OutBufferSize
[in] Size, in bytes, of the available space pointed to by OutBuffer.
BytesReturned
[out] Number of bytes in the buffer pointed to by OutBuffer that actually contain data.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation indicated by ControlCode was completed successfully.
ERROR_INVALID_FUNCTION | The resource DLL requested that the Resource Monitor perform default processing (if any) for Control Code in addition to processing supplied by the DLL (if any).

If the operation was not successful, ResourceTypeControl should return a Win32 error value.

Remarks

Some control codes should be handled by the resource DLL, while others should be left to the Resource Monitor. For effective implementation strategies of the ResourceTypeControl entry point function, see Implementing ResourceTypeControl.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


Startup

The Startup entry point function loads a resource DLL, returning a structure containing a function table and a version number.

DWORD WINAPI Startup(
  LPCWSTR ResourceType,
  DWORD MinVersionSupported,
  DWORD MaxVersionSupported,
  PSET_RESOURCE_STATUS_ROUTINE SetResourceStatus,
  PLOG_EVENT_ROUTINE LogEvent,
  PCLRES_FUNCTION_TABLE *FunctionTable
);

Parameters

ResourceType
[in] Type of resource being started.
MinVersionSupported
[in] Minimum version of the Resource API supported by the Cluster service.
MaxVersionSupported
[in] Maximum version of the Resource API supported by the Cluster service.
SetResourceStatus
[in] Pointer to a callback function that the resource DLL should call to update its status after returning ERROR_IO_PENDING from Online or Offline.
LogEvent
[in] Pointer to a callback function that the resource DLL should call to report events for the resource.
FunctionTable
[out] Pointer to a CLRES_FUNCTION_TABLE structure that describes the Resource API version and the specific names for the entry points.

Return Values

Value | Meaning
ERROR_SUCCESS | The request was successful.
ERROR_REVISION_MISMATCH | The resource DLL does not support a version that falls in the range identified by the MinVersionSupported and MaxVersionSupported parameters.

If the operation was not successful, Startup should return a Win32 error value.

Remarks

The Startup entry point function returns a function table that describes both the supported interface version of the Resource API and the entry points for all other functions required by the supported version of the Resource API.

At present, only Resource API version 1.0 is supported.

If your resource supports more than one version of the Resource API, return a function table for the latest version. The version number should be less than or equal to the MaxVersionSupported parameter. If the version of the function table pointed to by the FunctionTable parameter is not within range, your resource cannot be loaded successfully.

For more information see Implementing Startup.

Example

See Implementing Startup.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


Terminate

The Terminate entry point function immediately marks a resource as unavailable for use without waiting for cleanup processing to be completed.

VOID WINAPI Terminate(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the resource to be made unavailable.

Return Values

This function has no return values.

Remarks

The Terminate entry point function instantly marks a resource as unavailable for use. If there is a thread processing an Online or Offline request for the resource, these requests are canceled and the resource is taken offline immediately.

For effective implementation strategies of the Terminate entry point function, see Implementing Terminate.

Example

See Resource DLL Examples.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Resource DLL Entry Point Functions


Resource DLL Callback Functions

The resource DLL callback functions allow a resource DLL to report status and event information back to a Resource Monitor, making the information available to the Cluster service.

The following resource DLL callback functions allow a resource DLL to report status and event information.

Callback function | Description
LogEvent | Records an event in the cluster log.
QuorumResourceLost | Reports that control of the quorum resource has been lost.
SetResourceStatus | Updates the status of a resource.


LogEvent

The LogEvent callback function records an event in the cluster log.

VOID WINAPI LogEvent(
  RESOURCE_HANDLE ResourceHandle,
  LOG_LEVEL LogLevel,
  LPCWSTR FormatString
  [, arguments]...);

Parameters

ResourceHandle
[in] Handle identifying the resource recording the event. The value for ResourceHandle should be the handle passed in during the Open call for this resource.
LogLevel
[in] Constant that represents the log level of the event and that is for information only. The following valid values are shown in order from least to most severe.
LogLevel value | Type of event
LOG_INFORMATION | The event is informational.
LOG_WARNING | The event is reporting a failure that might have happened, but it is uncertain whether a failure really did occur.
LOG_ERROR | The event affects a single component, but other components are not affected and the integrity of the rest of the node is not compromised.
LOG_SEVERE | The event is reporting a severe failure that affects multiple components, or the integrity of the entire system is compromised or believed to be compromised.

FormatString
[in] Null-terminated Unicode string that includes the information to be recorded. This string must be in the same format as that passed to the Win32 function FormatMessage.
arguments
[in] Arguments to be passed to FormatMessage along with FormatString. Any number of arguments may be specified as long as they work with FormatString to satisfy the syntax requirements of FormatMessage. Arguments must be separated by commas.

Return Values

This function has no return values.

Remarks

The LogEvent callback function is implemented by the Resource Monitor and is called by a resource DLL to report events and errors to the cluster log. Resource DLLs receive a pointer to the LogEvent callback function as an input parameter to their Startup entry point function.

For more information on the cluster log, see Windows 2000 Help.

LogEvent does not write entries to the Windows NT/Windows 2000 event log. To report events in the Windows NT/Windows 2000 event log, a resource DLL must call the Win32 function ReportEvent.

The format of the logged message appears as follows:

ResourceTypeName <specific resource name>: message

ResourceTypeName is the resource type, such as Generic Application. The specific resource name is the user-friendly name for the specific resource, and message is the message delivered by the resource DLL to the Resource Monitor.

Example

The following example is based on code generated by the Cluster Resource Type Wizard. For additional examples, see Resource DLL Examples.

//  The following parameters are assumed to be already defined:
//  g_pfnLogEvent   Stores the address of the LogEvent callback
//                  function passed to the DLL in the
//                  Startup entry point.
//  pResourceEntry  Stores resource instance data.
//  MY_SVCNAME      Stores the name of a service.
//  nStatus         Win32 result

//  Log the fact that an attempt to start a service has failed.

//  Basic message
    (g_pfnLogEvent)(
        pResourceEntry->hResourceHandle,
        LOG_ERROR,
        L"Failed to start the specified service.\n" );

//  Message w/string argument
    (g_pfnLogEvent)(
        pResourceEntry->hResourceHandle,
        LOG_ERROR,
        L"OnlineThread: Failed to start the '%1' service.\n",
        MY_SVCNAME );

//  Message w/multiple arguments
    (g_pfnLogEvent)(
        pResourceEntry->hResourceHandle,
        LOG_ERROR,
        L"OnlineThread: Failed to start the '%1' service. Error: %2!u!.\n",
        MY_SVCNAME,
        nStatus );

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

FormatMessage, Open, ReportEvent, Startup


QuorumResourceLost

The QuorumResourceLost callback function is called when control of the quorum resource has been lost.

VOID WINAPI QuorumResourceLost(
  RESOURCE_HANDLE ResourceHandle
);

Parameters

ResourceHandle
[in] Handle identifying the resource to which this callback applies. The value for ResourceHandle should be the handle passed in during the Open call for this resource.

Return Values

This function has no return values.

Remarks

The QuorumResourceLost callback function is called by a resource DLL to notify the Resource Monitor that control of the quorum resource has been lost after arbitration. A pointer to the Resource Monitor's QuorumResourceLost callback function is passed to a quorum resource DLL in the call to Arbitrate.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Arbitrate, Open


SetResourceStatus

The SetResourceStatus callback function is called to update the status of a resource.

DWORD WINAPI SetResourceStatus(
  RESOURCE_HANDLE ResourceHandle,
  PRESOURCE_STATUS ResourceStatus
);

Parameters

ResourceHandle
[in] Handle identifying the resource to be updated. The ResourceHandle parameter should contain the same handle used for the ResourceHandle parameter in the Open entry point for this resource.
ResourceStatus
[in] Pointer to a RESOURCE_STATUS structure that contains information about the resource's state.

Return Values

SetResourceStatus returns one of the following values.

Value | Description
ResourceExitStateContinue | The resource has not been terminated. Worker threads may continue Online and Offline operations for the resource.
ResourceExitStateTerminate | The resource has been terminated. Callers should end Online or Offline operations and immediately terminate all worker threads assigned to the resource.

Remarks

Resource DLLs call the SetResourceStatus callback function to update the status of a resource after their Online or Offline entry point function has returned ERROR_IO_PENDING. It should not be called at any other time. A pointer to the function is passed to the resource's implementation of Startup.

SetResourceStatus is implemented by the Resource Monitor and is similar to the SetServiceStatus function for Win32 services.

Update the current state of a resource whenever necessary after you have returned ERROR_IO_PENDING. If the resource is in one of the pending states, increment the values for the CheckPoint and WaitHint members of the RESOURCE_STATUS structure and set the ResourceState member to ClusterResourceOnlinePending or ClusterResourceOfflinePending before you begin calling SetResourceStatus. Call SetResourceStatus until one of the following situations occurs:

  • The resource is placed in either the ClusterResourceOnline or ClusterResourceOffline state.
  • The time limit stored in the resource's PendingTimeout property has been exceeded.

There is no need to call SetResourceStatus to set the state of a resource to a pending state because the Resource Monitor automatically sets it to the appropriate pending state whenever Online or Offline returns ERROR_IO_PENDING.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Offline, Online, RESOURCE_STATUS, SetServiceStatus, Startup, Open, Terminate, ClusWorkerTerminate


Cluster Database Access Functions

The cluster database access functions are intended to allow resource DLLs to create and initialize private properties and perform other configuration tasks. Cluster-aware applications should not use these functions if at all possible, preferring the standard order of preference when choosing between APIs.

The cluster database access functions include the following two types.

Function subset | Description
Cluster Registry Access Functions | Functions to directly manipulate registry keys in the cluster database.
Property Access Utility Functions | Utility functions for moving property data between property lists, property tables, and the cluster database.


Cluster Registry Access Functions

Resource DLLs can use the following functions to access and update keys in the cluster database.

Cluster-aware applications should not use these functions if at all possible, preferring the standard order of preference when choosing between API elements.

Function | Description
ClusterRegCloseKey | Releases the handle of a cluster database key.
ClusterRegCreateKey | Creates a specified cluster database key. If the key already exists in the database, ClusterRegCreateKey opens it without making changes.
ClusterRegDeleteKey | Deletes a cluster database key.
ClusterRegDeleteValue | Removes a named value from a cluster database key.
ClusterRegEnumKey | Enumerates the subkeys of an open cluster database key.
ClusterRegEnumValue | Enumerates the values of an open cluster database key.
ClusterRegGetKeySecurity | Returns a copy of the security descriptor protecting the specified cluster database key.
ClusterRegOpenKey | Opens a cluster database key.
ClusterRegQueryInfoKey | Returns information about a cluster database key.
ClusterRegQueryValue | Returns the name, type, and data components associated with a value for an open cluster database key.
ClusterRegSetKeySecurity | Sets the security attributes for a cluster database key.
ClusterRegSetValue | Sets a value for a cluster database key.
GetClusterGroupKey | Opens the root of the cluster database subtree for a group.
GetClusterKey | Opens the root of the cluster database subtree for a cluster.
GetClusterNetInterfaceKey | Opens the root of the cluster database subtree for a network interface object.
GetClusterNetworkKey | Opens the root of the cluster database subtree for a network.
GetClusterNodeKey | Opens the root of the cluster database subtree for a node.
GetClusterResourceKey | Opens the root of the cluster database subtree for a resource.
GetClusterResourceTypeKey | Opens the root of the cluster database subtree for a resource type.


ClusterRegCloseKey

The ClusterRegCloseKey function releases the handle of a cluster database key.

LONG WINAPI ClusterRegCloseKey(
  HKEY hKey
);

Parameters

hKey
[in] Handle to the cluster database key to be closed.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegCloseKey returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegCreateKey

The ClusterRegCreateKey function creates a specified cluster database key. If the key already exists in the database, ClusterRegCreateKey opens it without making changes.

LONG WINAPI ClusterRegCreateKey(
  HKEY hKey,
  LPCWSTR lpszSubKey,
  DWORD dwOptions,
  REGSAM samDesired,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  PHKEY phkResult,
  LPDWORD lpdwDisposition
);

Parameters

hKey
[in] Handle to an open cluster database key. This parameter cannot be NULL.
lpszSubKey
[in] Pointer to a null-terminated Unicode string specifying the name of the subkey to be created or opened. The lpszSubKey parameter must point to a subkey that:
  • Is a child key of the key identified by hKey.
  • Must not begin with the backslash character ( \ ).
  • Must not be NULL.

The lpszSubKey parameter can point to an empty string, causing ClusterRegCreateKey to return a handle to the database key represented by hKey.

dwOptions
[in] Specifies special options for this key. Currently, dwOptions can be set to the following value.
Value | Description
REG_OPTION_NON_VOLATILE | The opened or created key is not volatile; the information is preserved when the system is restarted.

samDesired
[in] Access mask that specifies the needed security access for the new key. The following values are valid.
Value | Security access
KEY_ALL_ACCESS | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
KEY_CREATE_LINK | Permission to create a symbolic link.
KEY_ENUMERATE_SUB_KEYS | Permission to enumerate subkeys.
KEY_EXECUTE | Permission for read access.
KEY_NOTIFY | Permission for change notification.
KEY_QUERY_VALUE | Permission to query subkey data.
KEY_READ | Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
KEY_SET_VALUE | Permission to change subkey data.
KEY_WRITE | Combination of KEY_SET_VALUE and KEY_CREATE_SUB_KEY access.

lpSecurityAttributes
[in] Pointer to a SECURITY_ATTRIBUTES structure that contains the security descriptor for the new key in the content of the lpSecurityDescriptor member, or NULL. If lpSecurityAttributes is NULL, the key gets a default security descriptor. Since cluster database handles are not inheritable, the bInheritHandle member of the SECURITY_ATTRIBUTES structure must be FALSE.
phkResult
[out] Pointer to the handle of the opened or created key.
lpdwDisposition
[out] Pointer to a value that describes whether the key pointed to by lpszSubKey was opened or created. The following values are valid.
Value | Disposition
REG_CREATED_NEW_KEY | The key did not exist and was created.
REG_OPENED_EXISTING_KEY | The key existed and was opened.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegCreateKey returns a Win32 error value.

Remarks

Callers should call ClusterRegCloseKey to close the key handle created by the ClusterRegCreateKey function when they are done with it.

Do not call ClusterRegCreateKey from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ClusterRegCreateKey can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, ClusterRegDeleteKey, ClusterRegOpenKey


ClusterRegDeleteKey

The ClusterRegDeleteKey function deletes a cluster database key.

LONG WINAPI ClusterRegDeleteKey(
  HKEY hKey,
  LPCWSTR lpszSubKey
);

Parameters

hKey
[in] Handle to a currently open key.
lpszSubKey
[in] Pointer to a null-terminated Unicode string specifying the name of the key to delete. The key pointed to by lpszSubKey cannot have subkeys; ClusterRegDeleteKey can only delete keys without subkeys. This parameter cannot be NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegDeleteKey returns a Win32 error value.

Remarks

The ClusterRegDeleteKey function cannot delete a key that has one or more subkeys.

Do not call ClusterRegDeleteKey from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ClusterRegDeleteKey can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCreateKey


ClusterRegDeleteValue

The ClusterRegDeleteValue function removes a named value from a cluster database key.

DWORD WINAPI ClusterRegDeleteValue(
  HKEY hKey,
  LPCWSTR lpszValueName
);

Parameters

hKey
[in] Handle to a currently open key.
lpszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to be removed.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegDeleteValue returns a Win32 error value.

Remarks

Do not call ClusterRegDeleteValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ClusterRegDeleteValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegEnumKey

The ClusterRegEnumKey function enumerates the subkeys of an open cluster database key.

LONG WINAPI ClusterRegEnumKey(
  HKEY hKey,
  DWORD dwIndex,
  LPWSTR lpszName,
  LPDWORD lpcchName,
  PFILETIME lpftLastWriteTime
);

Parameters

hKey
[in] HKEY specifying a currently open key.
dwIndex
[in] Index used to identify the next subkey to be enumerated. This parameter should be zero for the first call to ClusterRegEnumKey and then incremented for subsequent calls.

Because subkeys are not ordered, any new subkey has an arbitrary index. This means that ClusterRegEnumKey may return subkeys in any order.

lpszName
[out] Pointer to a buffer that receives the name of the subkey, including the null-terminating character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.
lpcchName
[in, out] Pointer to the size of the lpszName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
lpftLastWriteTime
[out] Pointer to the last time the enumerated subkey was modified.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more subkeys to be returned.
ERROR_MORE_DATA | The buffer pointed to by lpszName is not big enough to hold the result. The lpcchName parameter returns the number of characters in the result, excluding the terminating NULL.
Win32 error | The operation was not successful.

Remarks

The ClusterRegEnumKey function retrieves information about one subkey each time it is called.

Because ClusterRegEnumKey enumerates keys from the root of the database on the node on which the application is running when hKey is set to NULL, ClusterRegEnumKey fails if the node is not part of a cluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegEnumValue

The ClusterRegEnumValue function enumerates the values of an open cluster database key.

DWORD WINAPI ClusterRegEnumValue(
  HKEY hKey,
  DWORD dwIndex,
  LPWSTR lpszValueName,
  LPDWORD lpcchValueName,
  LPDWORD lpdwType,
  LPBYTE lpbData,
  LPDWORD lpcbData
);

Parameters

hKey
[in] Handle of the cluster database key to enumerate.
dwIndex
[in] Index used to identify the next value to be enumerated. This parameter should be zero for the first call to ClusterRegEnumValue and then incremented for subsequent calls.

Because values are not ordered, any new value has an arbitrary index. This means that ClusterRegEnumValue may return values in any order.

lpszValueName
[out] Pointer to a null-terminated Unicode string containing the name of the returned value.
lpcchValueName
[in, out] Pointer to the size of the lpszValueName buffer as a count of characters. On input, specify the maximum number of characters the buffer can hold, including the terminating NULL. On output, specifies the number of characters in the resulting name, excluding the terminating NULL.
lpdwType
[out] Pointer to the type code for the value entry, or NULL if the type code is not required. The type code can be one of the following values.
Value | Type
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_EXPAND_SZ | A null-terminated Unicode string that contains unexpanded references to environment variables (for example, "%PATH%").
REG_MULTI_SZ | An array of null-terminated Unicode strings terminated by two NULL characters.
REG_NONE | No defined value type.
REG_SZ | A null-terminated Unicode string.

lpbData
[out] Pointer to the data for the value entry. This parameter can be NULL if the data is not required.
lpcbData
[in, out] On input, pointer to a count of bytes in the buffer pointed to by the lpbData parameter. On output, pointer to a count of bytes resulting from the operation. This parameter can be NULL only if lpbData is NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_NO_MORE_ITEMS | There are no more values to be returned.
ERROR_MORE_DATA | One of the output buffers (lpszValueName or lpbData) is too small to hold the resulting data. The lpcchValueName and the lpcbData parameters indicate the required size (note that lpcchValueName does not include the terminating NULL in the character count).
Win32 error | The operation was not successful.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegGetKeySecurity

The ClusterRegGetKeySecurity function returns a copy of the security descriptor protecting the specified cluster database key.

LONG WINAPI ClusterRegGetKeySecurity(
  HKEY hKey,
  SECURITY_INFORMATION SecurityInformation,
  PSECURITY_DESCRIPTOR pSecurityDescriptor,
  LPDWORD lpcbSecurityDescriptor
);

Parameters

hKey
[in] Handle to a cluster database key.
SecurityInformation
[in] A SECURITY_INFORMATION structure that indicates the requested security descriptor.
pSecurityDescriptor
[out] Pointer to a SECURITY_DESCRIPTOR structure containing a copy of the requested security descriptor.
lpcbSecurityDescriptor
[in, out] On input, pointer to a count of the number of bytes in the buffer pointed to by pSecurityDescriptor. On output, pointer to a count of the number of bytes written to the buffer.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegGetKeySecurity returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegOpenKey

The ClusterRegOpenKey function opens an existing cluster database key.

LONG WINAPI ClusterRegOpenKey(
  HKEY hKey,
  LPCWSTR lpszSubKey,
  REGSAM samDesired,
  PHKEY phkResult
);

Parameters

hKey
[in] Handle to a currently open key. This parameter cannot be NULL.
lpszSubKey
[in] Pointer to a null-terminated Unicode string specifying the name of the subkey to be created or opened. The lpszSubKey parameter must point to a subkey that:
  • Is a child key of the key identified by hKey.
  • Must not begin with the backslash character ( \ ).
  • Must not be NULL.

The lpszSubKey parameter can point to an empty string, causing ClusterRegCreateKey to return a handle to the database key represented by hKey.

samDesired
[in] Access mask that specifies the security access needed for the new key.
phkResult
[out] Pointer to a handle to the opened or created key.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegOpenKey returns a Win32 error value.

Remarks

Callers should call ClusterRegCloseKey to close the key handle opened by ClusterRegOpenKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, ClusterRegCreateKey


ClusterRegQueryInfoKey

The ClusterRegQueryInfoKey function returns information about a cluster database key.

LONG WINAPI ClusterRegQueryInfoKey(
  HKEY hKey,
  LPDWORD lpcSubKeys,
  LPDWORD lpcchMaxSubKeylen,
  LPDWORD lpcValues,
  LPDWORD lpcchMaxValueNameLen,
  LPDWORD lpcbMaxValueLen,
  LPDWORD lpcbSecurityDescriptor,
  PFILETIME lpftLastWriteTime
);

Parameters

hKey
[in] Handle to a cluster database key. All subsequent parameters describe the contents of the key.
lpcSubKeys
[out] If not NULL, pointer to the number of subkeys in the specified key.
lpcchMaxSubKeylen
[out] If not NULL, pointer to the number of characters in the longest subkey name in the specified key. The number does not include the terminating NULL.
lpcValues
[out] If not NULL, pointer to the number of values in the specified key.
lpcchMaxValueNameLen
[out] If not NULL, pointer to the number of characters in the longest value name in the specified key. The number does not include the terminating NULL.
lpcbMaxValueLen
[out] If not NULL, pointer to the byte size of the largest data value in the specified key.
lpcbSecurityDescriptor
[out] If not NULL, pointer to the byte size of the specified key's security descriptor.
lpftLastWriteTime
[out] If not NULL, pointer to the time of the most recent modification to the specified key or any of its contents.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegQueryInfoKey returns a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegQueryValue

The ClusterRegQueryValue function returns the name, type, and data components associated with a value for an open cluster database key.

LONG WINAPI ClusterRegQueryValue(
  HKEY hKey,
  LPCWSTR lpszValueName,
  LPDWORD lpdwValueType,
  LPBYTE lpbData,
  LPDWORD lpcbData
);

Parameters

hKey
[in] Handle of the cluster database key to query.
lpszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to be queried.
lpdwValueType
[out] Pointer to the key's value type. This parameter can be NULL if the type is not required; otherwise, the value returned through this parameter is one of the following.
Value | Type
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_EXPAND_SZ | A null-terminated Unicode string that contains unexpanded references to environment variables (for example, "%PATH%").
REG_MULTI_SZ | An array of null-terminated Unicode strings terminated by two NULL characters.
REG_NONE | No defined value type.
REG_SZ | A null-terminated Unicode string.

lpbData
[out] Pointer to the value's data. This parameter can be NULL if the data is not required.
lpcbData
[in, out] On input, pointer to the count of bytes in the buffer pointed to by the lpbData parameter. On output, pointer to the count of bytes in the value's data, which is placed in the content of lpbData if the caller passes in a valid pointer.

The lpcbData parameter can be NULL only if lpbData is also NULL.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.
ERROR_MORE_DATA | The buffer pointed to by lpbData is not large enough to hold the data for the value. ClusterRegQueryValue stores the required size in the content of lpcbData.
ERROR_NO_MORE_ITEMS | There are no more values.

Remarks

If lpbData is NULL, the ClusterRegQueryValue function returns ERROR_SUCCESS and stores the size of the value's data in the content of lpcbData. This information allows the caller to correctly allocate a buffer to hold the data.

If lpdwValueType is set to REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ, then lpbData also includes a NULL terminator.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegSetKeySecurity

The ClusterRegSetKeySecurity function sets the security attributes for a cluster database key.

LONG WINAPI ClusterRegSetKeySecurity(
  HKEY hKey,
  SECURITY_INFORMATION SecurityInformation,
  PSECURITY_DESCRIPTOR pSecurityDescriptor
);

Parameters

hKey
[in] Handle to a cluster database key.
SecurityInformation
[in] A SECURITY_INFORMATION structure that indicates the content of the security descriptor pointed to by pSecurityDescriptor.
pSecurityDescriptor
[in] Pointer to a SECURITY_DESCRIPTOR structure that describes the security attributes to set for the key corresponding to hKey.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegSetKeySecurity returns a Win32 error value.

Remarks

The ClusterRegSetKeySecurity function generates a CLUSTER_CHANGE_REGISTRY_ATTRIBUTES event for all registered notification ports.

Do not call ClusterRegSetKeySecurity from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ClusterRegSetKeySecurity can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey


ClusterRegSetValue

The ClusterRegSetValue function sets a value for a cluster database key.

DWORD WINAPI ClusterRegSetValue(
  HKEY hKey,
  LPCWSTR lpszValueName,
  DWORD dwType,
  CONST BYTE *lpbData,
  DWORD cbData
);

Parameters

hKey
[in] Handle to a cluster database key.
lpszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to set. If a value with this name is not already present in the resource, ClusterRegSetValue adds it to the resource.
dwType
[in] Type of information to be stored as the value's data. This parameter can be one of the following values.
Value | Type
REG_BINARY | Binary data in any form.
REG_DWORD | A 32-bit number.
REG_EXPAND_SZ | A null-terminated Unicode string that contains unexpanded references to environment variables (for example, "%PATH%").
REG_MULTI_SZ | An array of null-terminated Unicode strings terminated by two NULL characters.
REG_NONE | No defined value type.
REG_SZ | A null-terminated Unicode string.

lpbData
[in] Pointer to the data to be stored with the name pointed to by lpszValueName.
cbData
[in] Count of bytes in the data pointed to by the lpbData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ, cbData must include the size of the null-terminating character.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation was successful.

If the operation was not successful, ClusterRegSetValue returns a Win32 error value. For information about the error, call the Win32 function GetLastError.

Remarks

Do not call ClusterRegSetValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ClusterRegSetValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegOpenKey, GetLastError


GetClusterGroupKey

The GetClusterGroupKey function opens the root of the cluster database subtree for a group.

HKEY WINAPI GetClusterGroupKey(
  HGROUP hGroup,
  REGSAM samDesired
);

Parameters

hGroup
[in] Handle to a group.
samDesired
[in] Access mask that describes the security access needed for the key.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, see the Win32 function GetLastError.

If the operation was successful, GetClusterGroupKey returns a database key handle for the group.

Remarks

The GetClusterGroupKey function returns a handle to a cluster database key representing the subtree root for the group identified by hGroup. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterGroupKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenClusterGroup


GetClusterKey

The GetClusterKey function opens the root of the cluster database subtree for a cluster.

HKEY WINAPI GetClusterKey(
  HCLUSTER hCluster,
  REGSAM samDesired
);

Parameters

hCluster
[in] Handle to a cluster.
samDesired
[in] Access mask that describes the security access needed for the new key.

Return Values

Value | Meaning
NULL | The operation was not successful. For information about the error, call the Win32 function GetLastError.

If the operation was successful, GetClusterKey returns a database key handle for the cluster.

Remarks

The GetClusterKey function returns a handle to a cluster database key representing the cluster database subtree root for the cluster identified by hCluster. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenCluster


GetClusterNetInterfaceKey

The GetClusterNetInterfaceKey function opens the root of the cluster database subtree for a network interface object.

HKEY WINAPI GetClusterNetInterfaceKey(
  HNETINTERFACE hNetInterface,
  REGSAM samDesired
);

Parameters

hNetInterface
[in] Handle to a network interface.
samDesired
[in] Access mask that describes the security access needed for the key.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, see the Win32 function GetLastError.

If the operation was successful, GetClusterNetInterfaceKey returns a registry key handle for the network interface.

Remarks

The GetClusterNetInterfaceKey function returns a handle to a cluster database key representing the subtree root for the network interface identified by hNetInterface. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterNetInterfaceKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenClusterNetInterface


GetClusterNetworkKey

The GetClusterNetworkKey function opens the root of the cluster database subtree for a network.

HKEY WINAPI GetClusterNetworkKey(
  HNETWORK hNetwork,
  REGSAM samDesired
);

Parameters

hNetwork
[in] Handle to a network.
samDesired
[in] Access mask that describes the security access needed for the new key.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, see the Win32 function GetLastError.

If the operation was successful, GetClusterNetworkKey returns a registry key handle for the network.

Remarks

The GetClusterNetworkKey function returns a handle to a cluster database key representing the subtree root for the network identified by hNetwork. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterNetworkKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenClusterNetwork


GetClusterNodeKey

The GetClusterNodeKey function opens the root of the cluster database subtree for a node.

HKEY WINAPI GetClusterNodeKey(
  HNODE hNode,
  REGSAM samDesired
);

Parameters

hNode
[in] Handle to a node.
samDesired
[in] Access mask that describes the security access needed for the key.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, see the Win32 function GetLastError.

If the operation was successful, GetClusterNodeKey returns a registry key handle for the node.

Remarks

The GetClusterNodeKey function returns a handle to a cluster database key representing the subtree root for the node identified by hNode. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterNodeKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenClusterNode


GetClusterResourceKey

The GetClusterResourceKey function opens the root of the cluster database subtree for a resource.

HKEY WINAPI GetClusterResourceKey(
  HRESOURCE hResource,
  REGSAM samDesired
);

Parameters

hResource
[in] Handle to a resource.
samDesired
[in] Access mask that describes the security access needed for the opened key.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, see the Win32 function GetLastError.

If the operation was successful, GetClusterResourceKey returns a registry key handle for the resource.

Remarks

The GetClusterResourceKey function returns a handle to a cluster database key representing the subtree root for the resource identified by hResource. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterResourceKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenClusterResource


GetClusterResourceTypeKey

The GetClusterResourceTypeKey function opens the root of the cluster database subtree for a resource type.

HKEY WINAPI GetClusterResourceTypeKey(
  HCLUSTER hCluster,
  LPCWSTR lpszTypeName,
  REGSAM samDesired
);

Parameters

hCluster
[in] Handle to a cluster.
lpszTypeName
[in] Pointer to a NULL-terminated Unicode string specifying the name of a resource type (the registered type name, not the display name).
samDesired
[in] Access mask that describes the security access needed for the opened key.

Return Values

Value | Meaning
NULL | The operation was not successful. For more information about the error, see the Win32 function GetLastError.

If the operation was successful, GetClusterResourceTypeKey returns a registry key handle for the resource type.

Remarks

The GetClusterResourceTypeKey function returns a handle to a cluster database key representing the subtree root for the resource type pointed to by lpszTypeName in the cluster identified by hCluster. Callers should call ClusterRegCloseKey to close the key handle retrieved by GetClusterResourceTypeKey when they are done with it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.
Library: Use Clusapi.lib.

See Also

ClusterRegCloseKey, GetLastError, OpenCluster


Property Access Utility Functions

The property access utility functions allow resource DLLs to directly access the cluster database and move property data into and out of property lists, parameter blocks, and property tables.

Cluster-aware applications should not use these functions if at all possible, preferring the standard order of preference when choosing between APIs.

Function grouping | Use
Get Property Utility Functions | Retrieve single or multiple properties from the cluster database.
Get Value Utility Functions | Retrieve single values directly from the cluster database.
Set Property Utility Functions | Write single or multiple properties to the cluster database.
Set Value Utility Functions | Write single values directly to the cluster database.


Get Property Utility Functions

The get property utility functions obtain properties directly from the cluster database and return them in the form of a property list, a parameter block, or a property table.

Function | Description
ResUtilAddUnknownProperties | Retrieves unknown properties from the cluster database and appends them to a property list.
ResUtilEnumPrivateProperties | Enumerates the names of an object's private properties.
ResUtilEnumProperties | Enumerates the names of an object's common properties.
ResUtilGetAllProperties | Returns all of the default and unknown properties for an object in a property list.
ResUtilGetPrivateProperties | Returns the private properties of a cluster object in a property list. .
ResUtilGetProperties | Returns specified properties for an object in a property list.
ResUtilGetPropertiesToParameterBlock | Returns specified properties for an object in a parameter block.
ResUtilGetProperty | Returns a single property.
ResUtilGetPropertySize | Returns the byte size of a specified property.


ResUtilAddUnknownProperties

The ResUtilAddUnknownProperties utility function retrieves a set of unknown properties from the cluster database and appends them to the end of a property list.

DWORD WINAPI ResUtilAddUnknownProperties(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID pOutPropertyList,
  DWORD cbOutPropertyListSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

hkeyClusterKey
[in] Pointer to the cluster database key that identifies the location for the properties to read.
pPropertyTable
[in] Pointer to a property table describing the common and private properties of an object. Any properties found in the cluster database that are not in this property table are added to the property list.
pOutPropertyList
[in, out] Pointer to a buffer in which to receive the returned properties. On input, the buffer can contain an existing property list, or it can be empty. On output, the retrieved properties will be appended to the end of the existing list, or, if the buffer is empty, will return as a new property list.
cbOutPropertyListSize
[in] Total byte size of the buffer pointed to by pOutPropertyList. The size of the buffer must be large enough to contain the existing property list and the property list to be returned.
pcbBytesReturned
[in, out] On input, pointer to the byte size of the property list contained by the pOutPropertyList buffer. On output, pointer to the total number of bytes in the property list pointed to by pOutPropertyList.
pcbRequired
[in, out] On output, points to the total number of bytes required to hold the returned property list. If the pOutPropertyList buffer was too small, it can be reallocated to the required size.

Return Values

Value | Meaning
ERROR_SUCCESS | The unknown properties were added successfully.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.

If the operation was not successful, ResUtilAddUnknownProperties can return a Win32 error value.

Remarks

The relationships between the input and output parameters of ResUtilAddUnknownProperties are illustrated in the following diagram:

The ResUtilAddUnknownProperties utility function enumerates the properties stored in the cluster database (under hkeyClusterKey) and looks for corresponding properties in the property table (pPropertyTable). Each property that is listed in the cluster database but not listed in the property table is added to the property list (pOutPropertyList).

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM, ResUtilSetUnknownProperties


ResUtilEnumPrivateProperties

The ResUtilEnumPrivateProperties utility function retrieves the names of a cluster object's private properties.

DWORD WINAPI ResUtilEnumPrivateProperties(
  HKEY hkeyClusterKey,
  LPWSTR pszOutProperties,
  DWORD cbOutPropertiesSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the private properties in the cluster database.
pszOutProperties
[out] Pointer to an output buffer in which to receive the names of the enumerated properties.
cbOutPropertiesSize
[in] Size of the output buffer pointed to by pszOutProperties.
pcbBytesReturned
[out] Pointer to the total number of bytes returned in the output buffer.
pcbRequired
[out] Pointer to the required number of bytes if the output buffer is too small to hold all of the enumerated properties.

Return Values

Value | Meaning
ERROR_SUCCESS | The requested properties were returned successfully.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.
ERROR_MORE_DATA | The size of the output buffer is too small to hold the resulting data. The pcbRequired parameter points to the correct size.
Other Win32 error | The operation was not successful.

ResUtilEnumPrivateProperties can also return a Win32 error.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilEnumProperties


ResUtilEnumProperties

The ResUtilEnumProperties utility function enumerates the property names of a cluster object.

DWORD WINAPI ResUtilEnumProperties(
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  LPWSTR pszOutProperties,
  DWORD cbOutPropertiesSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing properties to enumerate.
pszOutProperties
[out] Pointer to the output buffer in which to return the names of all of the properties in multiple string format. Each property name is stored as a null-terminated Unicode string. The last property name is followed by a final null-terminating character.
cbOutPropertiesSize
[in] Size in bytes of the output buffer pointed to by pszOutProperties.
pcbBytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by pszOutProperties.
pcbRequired
[out] Number of bytes required if the output buffer is too small.

Return Values

Value | Meaning
ERROR_SUCCESS | The requested properties were returned successfully.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.
ERROR_MORE_DATA | The size of the output buffer is too small to hold the resulting data. The pcbRequired parameter points to the correct size.
Other Win32 error | The operation was not successful.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilEnumProperties, RESUTIL_PROPERTY_ITEM


ResUtilGetAllProperties

The ResUtilGetAllProperties utility function returns a property list that includes all of the default and unknown properties for a cluster object.

DWORD WINAPI ResUtilGetAllProperties(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID pOutPropertyList,
  DWORD cbOutPropertyListSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

hkeyClusterKey
[in] Pointer to the cluster database key that identifies the location of the properties to retrieve.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describe the properties to retrieve.
pOutPropertyList
[out] Pointer to an output buffer in which to return the property list.
cbOutPropertyListSize
[in] Size in bytes of the output buffer pointed to by OutBuffer.
pcbBytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by OutBuffer.
pcbRequired
[out] Pointer to the number of bytes that is required if OutBuffer is too small.

Return Values

Value | Meaning
ERROR_SUCCESS | The requested properties were returned successfully.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.
ERROR_MORE_DATA | The size of the output buffer is too small to hold the resulting data. The pcbRequired parameter points to the correct size.
Other Win32 error | The operation was not successful.

Remarks

The ResUtilGetAllProperties utility function makes an entry in the property list for each property that is:

  • Included in the property table.
  • Included in the cluster database below the key identified by the ClusterKey parameter, regardless of whether the property is included in the property table.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM


ResUtilGetPrivateProperties

The ResUtilGetPrivateProperties utility function returns private properties for a cluster object.

DWORD WINAPI ResUtilGetPrivateProperties(
  HKEY hkeyClusterKey,
  PVOID pOutPropertyList,
  DWORD cbOutPropertyListSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

hkeyClusterKey
[in] Pointer to the cluster database key that identifies the location of the private properties to retrieve.
pOutPropertyList
[out] Pointer to an output buffer in which a property list with the names and values of the private properties is returned.
cbOutPropertyListSize
[in] Size of the output buffer pointed to by pOutPropertyList.
pcbBytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by pOutPropertyList.
pcbRequired
[out] Pointer to the number of bytes that is required if pOutPropertyList is too small to hold all of the private properties.

Return Values

Value | Meaning
ERROR_SUCCESS | The requested properties were returned successfully.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.
ERROR_MORE_DATA | The size of the output buffer is too small to hold the resulting data. The pcbRequired parameter points to the correct size.
Other Win32 error | The operation was not successful.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetProperties


ResUtilGetProperties

The ResUtilGetProperties utility function retrieves properties specified by a property table from the cluster database and returns them in a property list.

DWORD WINAPI ResUtilGetProperties(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID pOutPropertyList,
  DWORD cbOutPropertyListSize,
  LPDWORD pcbBytesReturned,
  LPDWORD pcbRequired
);

Parameters

hkeyClusterKey
[in] Pointer to the cluster database key that identifies the location of the properties to retrieve.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describe the properties to retrieve.
pOutPropertyList
[out] Pointer to an output buffer in which to return the property list.
cbOutPropertyListSize
[in] Size in bytes of the output buffer pointed to by pOutPropertyList.
pcbBytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by pOutPropertyList.
pcbRequired
[out] Pointer to the number of bytes that is required if pOutPropertyList is too small.

Return Values

Value | Meaning
ERROR_SUCCESS | The requested properties were returned successfully.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_MORE_DATA | The output buffer was too small to contain the resulting data. The pcbRequired parameter indicates the required size.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.

If the operation was not successful, ResUtilGetProperties can return a Win32 error value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilGetPrivateProperties


ResUtilGetPropertiesToParameterBlock

The ResUtilGetPropertiesToParameterBlock utility function retrieves properties specified by a property table from the cluster database and returns them in a parameter block.

DWORD WINAPI ResUtilGetPropertiesToParameterBlock(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  LPBYTES pOutParams,
  BOOL bCheckForRequiredProperties,
  LPWSTR *ppszNameOfPropInError
);

Parameters

hkeyClusterKey
[in] Pointer to the cluster database key that identifies the location of the properties to retrieve.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describes the properties to process.
pOutParams
[out] Pointer to the output parameter block to fill.
bCheckForRequiredProperties
[in] Specifies whether an error should be generated if required properties are missing.
ppszNameOfPropInError
[out] Address of the string pointer in which to return the name of the error generated by a missing required property. The ppszNameOfPropInError property is optional.

Return Values

Value | Meaning
ERROR_SUCCESS | Properties were successfully stored in the parameter block.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory.

If the operation was not successful, ResUtilGetPropertiesToParameterBlock can return a Win32 error value.

Remarks

With the ResUtilGetPropertiesToParameterBlock utility function, the property table pointed to by pPropertyTable can include default values.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM


ResUtilGetProperty

The ResUtilGetProperty utility function returns a specified property from the cluster database.

DWORD WINAPI ResUtilGetProperty(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTableItem,
  PVOID *pOutPropertyItem,
  LPDWORD pOutPropertyItemSize
);

Parameters

hkeyClusterKey
[in] Pointer to the cluster database key identifying the location of the property to retrieve.
pPropertyTableItem
[in] Pointer to a RESUTIL_PROPERTY_ITEM structure that describes the property to retrieve.
pOutPropertyItem
[out] Pointer to an output buffer in which to return the requested property. It is assumed that the buffer is part of a property list.
pOutPropertyItemSize
[in, out] Pointer to the size in bytes of the output buffer pointed to by pOutPropertyItem.

Return Values

Value | Meaning
ERROR_SUCCESS | The property was successfully retrieved.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
Other Win32 error | The operation was not successful.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM


ResUtilGetPropertySize

The ResUtilGetPropertySize utility function returns the total number of bytes required for a specified property.

DWORD WINAPI ResUtilGetPropertySize(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTableItem,
  LPDWORD pcbOutPropertyListSize,
  LPDWORD pnPropertyCount
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location of the property to size.
pPropertyTableItem
[in] Pointer to a RESUTIL_PROPERTY_ITEM structure describing the property to size.
pcbOutPropertyListSize
[in, out] Pointer to the total number of bytes required for the property value, which includes the CLUSPROP_VALUE structure and the data.
pnPropertyCount
[in, out] Pointer to the total number of properties. This value is incremented to include this property if ResUtilGetPropertySize is successful.

Return Values

Value | Meaning
ERROR_SUCCESS | The size of the property was successfully retrieved.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_INVALID_PARAMETER | The data type of a property specified in the property table does not match the data type of the same-named property stored in the cluster database.
Other Win32 error | The operation was not successful.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

CLUSPROP_VALUE, RESUTIL_PROPERTY_ITEM


Get Value Utility Functions

The get value utility functions retrieve individual values of specific types directly from the cluster database.

Function | Description
ResUtilGetBinaryValue | Retrieves a binary value from the cluster database.
ResUtilGetDwordValue | Retrieves a DWORD value from the cluster database.
ResUtilGetExpandSzValue, | Retrieves an expandable string value from the cluster database.
ResUtilGetMultiSzValue | Retrieves a multiple string value from the cluster database.
ResUtilGetSzValue | Retrieves a string or expandable string value from the cluster database.


ResUtilGetBinaryValue

The ResUtilGetBinaryValue utility function returns a binary value from the cluster database.

DWORD WINAPI ResUtilGetBinaryValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  LPBYTE *ppbOutValue,
  DWORD *pcbOutValueSize
);

Parameters

hkeyClusterKey
[in] Key in the cluster database that identifies the location of the value to retrieve.
pszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to retrieve.
ppbOutValue
[out] Address of the pointer to the retrieved value.
pcbOutValueSize
[out] Pointer to a DWORD in which the size in bytes of the buffer pointed to by ppbOutValue is returned.

Return Values

Value | Meaning
ERROR_SUCCESS | The value was returned successfully from the cluster database.
ERROR_NOT_ENOUGH_MEMORY | There was an error allocating memory for the value.

ResUtilGetBinaryValue can return Win32 error codes that are returned by ClusterRegQueryValue.

Remarks

The ResUtilGetBinaryValue utility function takes care of allocating the necessary memory for the value and then calls the Cluster API function ClusterRegQueryValue. When you are finished with the allocated memory, you must call the Win32 function LocalFree to release it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegQueryValue, ResUtilGetDwordValue, ResUtilGetExpandSzValue, ResUtilGetMultiSzValue, ResUtilGetSzValue,


ResUtilGetDwordValue

The ResUtilGetDwordValue utility function returns a numeric value from the cluster database.

DWORD WINAPI ResUtilGetDwordValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  LPDWORD pdwOutValue,
  DWORD dwDefaultValue
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the numeric value in the cluster database.
pszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to retrieve.
pdwOutValue
[out] Pointer to the retrieved value.
dwDefaultValue
[in] Value to return if the value pointed to by pszValueName is not found.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.
ERROR_INVALID_PARAMETER | The value pointed to by ValueName is not a numeric value.

ResUtilGetDwordValue can return Win32 error codes that are returned by ClusterRegQueryValue.

Remarks

The ResUtilGetDwordValue utility function calls the Cluster API function ClusterRegQueryValue to retrieve the value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegQueryValue, ResUtilGetBinaryValue, ResUtilGetExpandSzValue, ResUtilGetMultiSzValue, ResUtilGetSzValue


ResUtilGetExpandSzValue

The ResUtilGetExpandSzValue utility function returns a expandable string value from the cluster database.

LPWSTR WINAPI ResUtilGetExpandSzValue(
  IN HKEY hkeyClusterKey,
  IN LPCWSTR pszValueName,
  IN BOOL bExpand
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the expandable string value in the cluster database.
pszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to retrieve.
bExpand
[in] If TRUE, the function expands the string before returning. If FALSE, the string is returned in an expandable form.

Return Values

Value | Meaning
LPWSTR | Pointer to a null-terminated Unicode string containing a copy of the specified value. Callers must call LocalFree on the returned pointer.
ERROR_INVALID_PARAMETER | The specified value is not a string data type.

ResUtilGetExpandSzValue can also return Win32 error codes that are returned by ClusterRegQueryValue.

Remarks

When you are finished with the memory allocated for the value returned by the ResUtilGetExpandSzValue utility function, you must call the Win32 function LocalFree to release it.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegQueryValue, ResUtilGetBinaryValue, ResUtilGetDwordValue, ResUtilGetMultiSZValue, ResUtilGetSzValue


ResUtilGetMultiSzValue

The ResUtilGetMultiSzValue utility function returns a multiple string value from the cluster database.

DWORD WINAPI ResUtilGetMultiSzValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  LPBYTE *ppszOutValue,
  DWORD *pcbOutValueSize
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the multiple string value in the cluster database.
pszValueName
[in] Pointer to a null-terminated Unicode string containing the name of the value to retrieve.
ppszOutValue
[out] Address of the pointer to the retrieved value.
pcbOutValueSize
[out] Pointer to a DWORD in which the size in bytes of the buffer pointed to by ppszOutValue is returned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY | An error occurred during memory allocation.

ResUtilGetMultiSzValue can return Win32 error codes that are returned by ClusterRegQueryValue.

Remarks

When you are finished with the memory allocated for the value returned by the ResUtilGetMultiSzValue utility function, you must call the Win32 function LocalFree to release it.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegQueryValue, ResUtilGetBinaryValue, ResUtilGetDwordValue, ResUtilGetExpandSzValue, ResUtilGetSzValue


ResUtilGetSzValue

The ResUtilGetSzValue utility function returns a string value from the cluster database.

LPWSTR WINAPI ResUtilGetSzValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the value in the cluster database.
pszValueName
[in] null-terminated Unicode string containing the name of the value to retrieve.

Return Values

If the operation was successful, ResUtilGetSzValue returns a pointer to a buffer containing the string value.

If the operation was not successful, ResUtilGetSzValue returns NULL. For more information, call the Win32 function GetLastError.

Remarks

The ResUtilGetSzValue utility function allocates the necessary memory for the string parameter value before calling the Cluster API function ClusterRegQueryValue to access the cluster database. When you are finished with this memory, you must call the Win32 function LocalFree to release it.

ResUtilGetSzValue also supports expandable and multiple string formats.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegQueryValue, ResUtilGetBinaryValue, ResUtilGetDwordValue, ResUtilGetExpandSzValue, ResUtilGetMultiSzValue


Set Property Utility Functions

The set property utility functions use the contents of a property list, parameter block, or property table to change one or more properties in the cluster database.

Function | Description
ResUtilSetPrivatePropertyList | Writes private properties to the cluster database based on the contents of a property list.
ResUtilSetPropertyParameterBlock | Conditionally writes properties to the cluster database based on the contents of a parameter block.
ResUtilSetPropertyParameterBlockEx | Force writes properties to the cluster database based on the contents of a parameter block.
ResUtilSetPropertyTable | Conditionally writes properties to the cluster database based on the contents of a property table.
ResUtilSetPropertyTableEx | Force writes properties to the cluster database based on the contents of a property table.
ResUtilSetUnknownProperties | Sets unknown properties based on the contents of a property table.


ResUtilSetPrivatePropertyList

The ResUtilSetPrivatePropertyList utility function sets the private properties of a cluster object.

DWORD WINAPI ResUtilSetPrivatePropertyList(
  HKEY hkeyClusterKey,
  const PVOID pInPropertyList,
  DWORD cbInPropertyListSize
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location of the properties to set.
pInPropertyList
[in] Pointer to an input buffer containing a property list with the names and values of the properties to set.
cbInPropertyListSize
[in] Pointer to the size in bytes of the input buffer pointed to by pInPropertyList.

Return Values

Value | Meaning
ERROR_SUCCESS | The properties were updated successfully.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_INVALID_DATA | There was a problem with the length of a property's data.
ERROR_INSUFFICIENT_BUFFER | The input buffer pointed to by pInPropertyList was NULL.
ERROR_INVALID_PARAMETER | The syntax of a property name was invalid.

Remarks

The properties that are set in the ResUtilSetPrivatePropertyList utility function are placed in the portion of the cluster database below the specified key for the object exactly as specified by the names in the property list. If the name of a property contains backslash characters (\), each string preceding a backslash character is interpreted as a subkey name, and the last string following the last backslash character is interpreted as the value name.

Do not call ResUtilSetPrivatePropertyList from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetPrivatePropertyList can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilVerifyPrivatePropertyList


ResUtilSetPropertyParameterBlock

The ResUtilSetPropertyParameterBlock utility function is used to set properties in the cluster database from a parameter block.

DWORD WINAPI ResUtilSetPropertyParameterBlock(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID Reserved,
  const LPBYTE pInParams,
  const LPVOID pInPropertyList,
  DWORD cbInPropertyListSize,
  LPBYTE pOutParams
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location for the properties to set.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties to set.
Reserved
[in] Reserved
pInParams
[in] Pointer to an input parameter block containing the data for the properties described in the property table pointed to by pPropertyTable.
pInPropertyList
[in] Pointer to the input buffer containing a property list or NULL. If pInPropertyList is not NULL, any properties listed in the property list that are not listed in the property table are also set in the cluster database.
cbInPropertyListSize
[in] Size in bytes of the input buffer pointed to by pInPropertyList.
pOutParams
[out] Optional pointer to a parameter block to receive data copied from the pInParams parameter.

Return Values

Value | Meaning
ERROR_SUCCESS | The properties were successfully set.
ERROR_INVALID_PARAMETER | The syntax, format, or type of a property in the property table pointed to by pPropertyTable is incorrect, or a property is read-only and cannot be updated.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.

Remarks

If a value specified in the parameter block already exists in the cluster database, the value is not written. To force all values to be written, see ResUtilSetPropertyParameterBlockEx.

Do not call ResUtilSetPropertyParameterBlock from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetPropertyParameterBlock can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM


ResUtilSetPropertyParameterBlockEx

The ResUtilSetPropertyParameterBlockEx utility function is used to set properties in the cluster database from a parameter block.

DWORD WINAPI ResUtilSetPropertyParameterBlockEx(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID Reserved,
  const LPBYTE pInParams,
  const LPVOID pInPropertyList,
  DWORD cbInPropertyListSize,
  BOOL bForceWrite
  LPBYTE pOutParams
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location for the properties to set.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties to set.
Reserved
[in] Reserved
pInParams
[in] Pointer to an input parameter block containing the data for the properties described in the property table pointed to by pPropertyTable.
pInPropertyList
[in] Pointer to the input buffer containing a property list or NULL. If pInPropertyList is not NULL, any properties listed in the property list that are not listed in the property table are also set in the cluster database.
cbInPropertyListSize
[in] Size in bytes of the input buffer pointed to by pInPropertyList.
bForceWrite
[in] Forces the property values to be written to the cluster database even if the new values are identical to the existing values
pOutParams
[out] Optional pointer to a parameter block to receive data copied from the pInParams parameter.

Return Values

Value | Meaning
ERROR_SUCCESS | The properties were successfully set.
ERROR_INVALID_PARAMETER | The syntax, format, or type of a property in the property table pointed to by pPropertyTable is incorrect, or a property is read-only and cannot be updated.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.

If the operation was not successful, ResUtilSetPropertyParameterBlockEx can return a Win32 error value.

Remarks

Do not call ResUtilSetPropertyParameterBlockEx from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetPropertyParameterBlockEx can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM, ResUtilSetPropertyParameterBlock


ResUtilSetPropertyTable

The ResUtilSetPropertyTable utility function is used to set properties in the cluster database based on a property list from a property table..

DWORD WINAPI ResUtilSetPropertyTable(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID Reserved,
  BOOL bAllowUnknownProperties,
  const PVOID pInPropertyList,
  DWORD cbInPropertyListSize,
  OPTIONAL LPBYTE pOutParams
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location of the properties to set.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties to set.
Reserved
[in] Reserved
bAllowUnknownProperties
[in] Indicates whether unknown properties should be accepted. This parameter is set to TRUE if they should be accepted, and FALSE if not.
pInPropertyList
[in] Pointer to the input buffer containing a property list.
cbInPropertyListSize
[in] Size in bytes of the input buffer pointed to by pInPropertyList.
pOutParams
[out] Optional pointer to a parameter block to hold returned data. If specified, parameters are only written if they differ from those in the input buffer.

Return Values

Value | Meaning
ERROR_SUCCESS | The properties were successfully set.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_INSUFFICIENT_BUFFER | The size of the input buffer specified in cbInPropertyListSize is too small.
ERROR_INVALID_DATA | The input buffer pointed to by pInPropertyList is NULL, a property name is not valid, or a property value is too small.
ERROR_INVALID_PARAMETER | The syntax, format, or type of a property in the property table pointed to by pPropertyTable is incorrect, or a property is read-only and cannot be set.

If the operation was not successful, ResUtilSetPropertyTable can return a Win32 error value.

Remarks

If a value specified in the property table already exists in the cluster database, the value is not written. For information on forcing all values to be written, see ResUtilSetPropertyTableEx.

Do not call ResUtilSetPropertyTable from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetPropertyTable can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM, ResUtilSetPropertyTableEx


ResUtilSetPropertyTableEx

The ResUtilSetPropertyTableEx utility function is used to set properties in the cluster database based on a property list from a property table.

DWORD WINAPI ResUtilSetPropertyTableEx(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  PVOID Reserved,
  BOOL bAllowUnknownProperties,
  const PVOID pInPropertyList,
  DWORD cbInPropertyListSize,
  BOOL bForceWrite
  OPTIONAL LPBYTE pOutParams
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location of the properties to set.
pPropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties to set.
Reserved
[in] Reserved
bAllowUnknownProperties
[in] Indicates whether unknown properties should be accepted. This parameter is set to TRUE if they should be accepted and FALSE if not.
pInPropertyList
[in] Pointer to the input buffer containing a property list.
cbInPropertyListSize
[in] Size in bytes of the input buffer pointed to by pInPropertyList.
bForceWrite
[in] Forces the property values to be written to the cluster database even if the new values are identical to the existing values
pOutParams
[out] Optional pointer to a parameter block to hold returned data. When this is pointer is specified, only parameters that differ from those in the input buffer are written to the parameter block.

Return Values

Value | Meaning
ERROR_SUCCESS | The properties were successfully set.
ERROR_BAD_ARGUMENTS | One or more of the input parameters were invalid.
ERROR_INSUFFICIENT_BUFFER | The size of the input buffer specified in cbInPropertyListSize is too small.
ERROR_INVALID_DATA | The input buffer pointed to by pInPropertyList is NULL, a property name is not valid, or a property value is too small.
ERROR_INVALID_PARAMETER | The syntax, format, or type of a property in the property table pointed to by pPropertyTable is incorrect, or a property is read-only and cannot be set.

If the operation was not successful, ResUtilSetPropertyTableEx can return a Win32 error value.

Remarks

Do not call ResUtilSetPropertyTableEx from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetPropertyTableEx can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

RESUTIL_PROPERTY_ITEM, ResUtilSetPropertyTable


ResUtilSetUnknownProperties

The ResUtilSetUnknownProperties utility function stores a cluster object's unknown properties in the cluster database.

DWORD WINAPI ResUtilSetPrivatePropertyList(
  HKEY hkeyClusterKey,
  const PRESUTIL_PROPERTY_ITEM pPropertyTable,
  const PVOID pInPropertyList,
  DWORD cbInPropertyListSize
);

Parameters

hkeyClusterKey
[in] Cluster database key identifying the location of the properties to set.
pPropertyTable
[in] Pointer to a property table specifying properties that should NOT be set by this function.
pInPropertyList
[in] Pointer to a property list. Any properties that appear in this list and that do NOT appear in pPropertyTable are set.
cbInPropertyListSize
[in] Pointer to the size in bytes of the input buffer pointed to by pInPropertyList.

Return Values

Value | Meaning
ERROR_SUCCESS | The properties were updated successfully.
Win32 Error | The operation was not successful.

Remarks

ResUtilSetUnknownProperties only sets the properties listed in pInPropertyList that are NOT listed in pPropertyTable.

Use the ResUtilAddUnknownProperties to create the property list and ResUtilGetAllProperties to retrieve unknown properties.

Do not call ResUtilSetUnknownProperties from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetUnknownProperties can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ResUtilAddUnknownProperties, ResUtilGetAllProperties


Set Value Utility Functions

The set value utility functions write values directly to the cluster database.

Function | Description
ResUtilSetBinaryValue | Sets a binary value in the cluster database.
ResUtilSetDwordValue | Sets a DWORD value in the cluster database.
ResUtilSetExpandSzValue | Sets an expandable string value in the cluster database.
ResUtilSetMultiSzValue | Sets a multiple string value in the cluster database.
ResUtilSetSzValue | Sets a string value in the cluster database.


ResUtilSetBinaryValue

The ResUtilSetBinaryValue utility function sets a binary value in the cluster database.

DWORD WINAPI ResUtilSetBinaryValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  const LPBYTE pbNewValue,
  DWORD cbNewValueSize,
  LPBYTE *ppbOutValue,
  LPDWORD pcbOutValueSize
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the binary value in the cluster database.
pszValueName
[in] A null-terminated Unicode string containing the name of the value to update.
pbNewValue
[in] Pointer to the new binary value.
cbNewValueSize
[in] Size of the new binary value.
ppbOutValue
[in, out] Optional. Address of a pointer to the new binary value.
pcbOutValueSize
[in, out] Optional. Pointer to a DWORD in which the size in bytes of the value pointed to by ppbOutValue is returned.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY | An error occurred during memory allocation.

ResUtilSetBinaryValue can return Win32 error codes that are returned by ClusterRegSetValue.

Remarks

The ResUtilSetBinaryValue utility function allocates memory for the ppbOutValue pointer using the Win32 function LocalAlloc, calls the Cluster API function ClusterRegSetValue, and then copies the new value to this buffer. If the pointer is not NULL, ResUtilSetBinaryValue also deallocates it. As callers of this function, you are responsible for deallocating the buffer using the Win32 function LocalFree.

Do not call ResUtilSetBinaryValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetBinaryValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegSetValue, ResUtilSetExpandSzValue, ResUtilSetDwordValue, ResUtilSetMultiSzValue, ResUtilSetSzValue


ResUtilSetDwordValue

The ResUtilSetDwordValue utility function sets a numeric value in the cluster database.

DWORD WINAPI ResUtilSetDwordValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  DWORD dwNewValue,
  LPDWORD pdwOutValue
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the numeric value in the cluster database.
pszValueName
[in] A null-terminated Unicode string containing the name of the value to update.
dwNewValue
[in] New DWORD value.
pdwOutValue
[in, out] Optional. Pointer to where the updated value should be copied.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.

If the operation was not successful, ResUtilSetDwordValue returns a Win32 error value.

Remarks

The ResUtilSetDwordValue utility function updates the cluster database by calling the Cluster API function ClusterRegSetValue.

Do not call ResUtilSetDwordValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetDwordValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegSetValue, ResUtilSetBinaryValue, ResUtilSetExpandSzValue, ResUtilSetMultiSzValue, ResUtilSetSzValue


ResUtilSetExpandSzValue

The ResUtilSetExpandSzValue utility function sets an expandable string value in the cluster database.

DWORD WINAPI ResUtilSetExpandSzValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  LPCWSTR pszNewValue,
  LPWSTR *ppszOutValue
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the expandable string value in the cluster database.
pszValueName
[in] null-terminated Unicode string containing the name of the value to update.
pszNewValue
[in] Pointer to the new expandable string value.
ppszOutValue
[in, out] Optional pointer to a string pointer that receives a copy of the updated value. If used, callers must call LocalFree on *ppszOutValue.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY | An error occurred while attempting to allocate memory.

ResUtilSetExpandSzValue can return Win32 error codes that are returned by ClusterRegSetValue.

Remarks

The ResUtilSetExpandSzValue utility function allocates memory for the new value and calls the Cluster API function ClusterRegSetValue.

An expandable string value contains data that represents a null-terminated Unicode string containing unexpanded references to environment variables such as "%SystemRoot%".

Be sure to call LocalFree on *ppszOutValue to avoid memory leaks.

Do not call ResUtilSetExpandSzValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetExpandSzValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegSetValue, ResUtilSetBinaryValue, ResUtilSetDwordValue, ResUtilSetMultiSzValue, ResUtilSetSzValue


ResUtilSetMultiSzValue

The ResUtilSetMultiSzValue utility function sets a multiple string value in the cluster database.

DWORD WINAPI ResUtilSetMultiSzValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  LPCWSTR pszNewValue,
  DWORD cbNewValueSize,
  LPWSTR *ppszOutValue,
  LPDWORD pcbOutValueSize
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the multiple string value in the cluster database.
pszValueName
[in] Null-terminated Unicode string containing the name of the value to update.
pszNewValue
[in] Pointer to the new multiple string value.
cbNewValueSize
[in] Size of the new value.
ppszOutValue
[in, out] Optional pointer to a string pointer that receives a copy of the updated value. If used, callers must call LocalFree on *ppszOutValue.
pcbOutValueSize
[in, out] Optional pointer that receives the size of the new value.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY | An error occurred while attempting to allocate memory.

ResUtilSetMultiSzValue can return Win32 error codes that are returned by ClusterRegSetValue.

Remarks

The ResUtilSetMultiSzValue utility function allocates memory for the new value and calls the Cluster API function ClusterRegSetValue.

A multiple string value is a large string containing smaller, contiguous, null-terminated Unicode strings and ending with an extra NULL after the last string.

Be sure to call LocalFree on *ppszOutValue to avoid memory leaks.

Do not call ResUtilSetMultiSzValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetMultiSzValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegSetValue, ResUtilSetBinaryValue, ResUtilSetDwordValue, ResUtilSetExpandSzValue, ResUtilSetSzValue


ResUtilSetSzValue

The ResUtilSetSzValue utility function sets a string value in the cluster database.

DWORD WINAPI ResUtilSetSzValue(
  HKEY hkeyClusterKey,
  LPCWSTR pszValueName,
  LPCWSTR pszNewValue,
  LPWSTR *ppszOutValue
);

Parameters

hkeyClusterKey
[in] Key identifying the location of the string value in the cluster database.
pszValueName
[in] Null-terminated Unicode string containing the name of the value to update.
pszNewValue
[in] Pointer to the new string value.
ppszOutValue
[in, out] Optional pointer to a string pointer that receives a copy of the updated value. If used, callers must call LocalFree on *ppszOutValue.

Return Values

Value | Meaning
ERROR_SUCCESS | The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY | An error occurred while attempting to allocate memory.

ResUtilSetSzValue can return Win32 error codes that are returned by ClusterRegSetValue.

Remarks

The ResUtilSetSzValue utility function allocates memory for the new value and calls the Cluster API function ClusterRegSetValue. If necessary, a previous value is deallocated. The new value is copied to the content of ppszOutValue.

Be sure to call LocalFree on *ppszOutValue to avoid memory leaks.

Do not call ResUtilSetSzValue from the following resource DLL entry point functions:

  • Close
  • Offline
  • Online
  • Open
  • Terminate

ResUtilSetSzValue can be safely called from any other resource DLL entry point function or from a worker thread. For more information, see Function Calls to Avoid in Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.
Library: Use Resutils.lib.

See Also

ClusterRegSetValue, ResUtilSetBinaryValue, ResUtilSetDwordValue, ResUtilSetExpandSzValue, ResUtilSetMultiSzValue


Cluster Administrator Extension Functions

The Cluster Administrator extension functions allow you to create your own context menus, property sheets, and wizard pages for any type of cluster object and add them to the Cluster Administrator user interface. This allows you to implement configuration and management procedures in an environment that is familiar to most administrators.

The Cluster Administrator extension functions must be implemented in an extension DLL. For more information, see Implementing Extension DLLs.

The following table lists the sections in which the Cluster Administrator extension functions are described.

Section | Description
Cluster Administrator Extension Interfaces | COM interfaces that you must implement in your extension to create context menu items, property sheet pages, and Wizard pages that support a cluster object (referred to as the extended object).
Cluster Administrator Callback Interfaces | COM interfaces that your extension calls to add context menu items, property sheet pages, and Wizard pages to the Cluster Administrator user interface.
Cluster Administrator Information Interfaces | COM interfaces that your extension calls to get information about the extended object from Cluster Administator.
Cluster Administrator Extension Registration Functions | Functions used to register the extension DLL.


Cluster Administrator Extension Interfaces

The Cluster Administrator extension interfaces allow you to create custom property pages, wizard pages, and context menu items for the Cluster Administrator user interface.

Interface | Description
IWEExtendContextMenu | Allows you to create context menu items and add them to a Cluster Administrator context menu.
IWEExtendPropertySheet | Allows you to create property sheet pages and add them to the Cluster Administrator user interface.
IWEExtendWizard | Allows you to create custom Cluster Administrator wizard pages.
IWEInvokeCommand | Allows you to respond when users select your context menu items.


IWEExtendContextMenu

Implement the IWEExtendContextMenu interface to extend a Cluster Administrator context menu for a cluster object.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWEExtendContextMenu Method | Description
AddContextMenuItems | Allows you to create context menu items for a cluster object and add them to a Cluster Administrator context menu.

Remarks

To add code that executes when your context menu items are selected, implement the IWEInvokeCommand interface.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEInvokeCommand


IWEExtendContextMenu::AddContextMenuItems

The AddContextMenuItems method allows you to create context menu items for a cluster object and add the items to a Cluster Administrator context menu.

HRESULT AddContextMenuItems(
  IUnknown *piData,
  IWCContextMenuCallback *piCallback
);

Parameters

piData
[in] IUnknown interface pointer for retrieving information relating to the new menu item. By calling IUnknown::QueryInterface with the piData pointer, the following interfaces are available:
  • IGetClusterUIInfo
  • IGetClusterDataInfo
  • IGetClusterObjectInfo

Depending on the type of cluster object for which the context menu is being created, one of the following interfaces may also be available:

  • IGetClusterNodeInfo, if the menu item relates to a node.
  • IGetClusterGroupInfo, if the menu item relates to a group.
  • IGetClusterNetworkInfo, if the menu item relates to a network.
  • IGetClusterNetInterfaceInfo, if the menu item relates to a network interface.
  • IGetClusterResourceInfo, if the menu item relates to a resource.
piCallback
[in] Pointer to an IWCContextMenuCallback interface implementation for adding new items to the Cluster Administrator context menu.

Return Values

Return one of the following values or any HRESULT that describes the results of the operation.

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | At least one of the parameters is invalid.
E_NOTIMPL | The extension does not support adding context menu items.

Remarks

To implement AddContextMenuItems

  1. Call the IUnknown::QueryInterface method pointed to by piData to retrieve a pointer to an interface that can provide information about the object associated with the menu item.
  2. Call IWCContextMenuCallback::AddExtensionMenuItem using the piCallback pointer to add the item to the menu.

To add code that executes when your context menu items are selected, implement the IWEInvokeCommand::InvokeCommand method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo, IGetClusterGroupInfo, IGetClusterObjectInfo, IGetClusterNetworkInfo, IGetClusterNetInterfaceInfo, IGetClusterNodeInfo, IGetClusterResourceInfo, IGetClusterUIInfo, IWCContextMenuCallback, IWCContextMenuCallback::AddExtensionMenuItem, IWEExtendContextMenu, IWEInvokeCommand::InvokeCommand


IWEExtendPropertySheet

Implement the IWEExtendPropertySheet interface to create property sheet pages for a cluster object and add them to a Cluster Administrator property sheet.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWEExtendPropertySheet Method | Description
CreatePropertySheetPages | Allows you to create property pages for a cluster object and add them to a Cluster Administrator property sheet.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.


IWEExtendPropertySheet::CreatePropertySheetPages

The CreatePropertySheetPages method creates property pages for a cluster object and adds them to a Cluster Administrator property sheet.

HRESULT CreatePropertySheetPages(
  IUnknown *piData,
  IWCPropertySheetCallback *piCallback
);

Parameters

piData
[in] IUnknown interface pointer for retrieving information relating to the new property pages. By calling IUnknown::QueryInterface with the piData pointer, the following interfaces are available:
  • IGetClusterUIInfo
  • IGetClusterDataInfo
  • IGetClusterObjectInfo

Depending on the type of cluster object for which property sheet pages are being created, a pointer to one of the following interfaces is also available:

  • IGetClusterNodeInfo, if the property page relates to a node.
  • IGetClusterGroupInfo, if the property page relates to a group.
  • IGetClusterNetworkInfo, if the property page relates to a network.
  • IGetClusterNetInterfaceInfo, if the property page relates to a network interface.
  • IGetClusterResourceInfo, if the property page relates to a resource.
piCallback
[in] Pointer to an IWCPropertySheetCallback interface implementation for adding property pages to the Cluster Administrator property sheet.

Return Values

Return one of the following values or any HRESULT that describes the results of the operation.

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | At least one of the parameters is invalid.
E_NOTIMPL | The extension does not support adding property pages.

Remarks

Cluster Administrator calls an extension's CreatePropertySheetPages method to extend a property sheet to handle an additional cluster object.

Notes to Implementers

For each property page to be added

  1. Use piData to call QueryInterface and retrieve an interface pointer for the cluster object associated with the page. For example, if you are adding a property page for a resource, you want to retrieve a pointer to the IGetClusterResourceInfo interface. Although it is possible to successfully query for interfaces that retrieve data unrelated to the target object, you should expect to receive errors when you attempt to call the methods.
  2. To create the page, call the Win32 function CreatePropertySheetPage. To produce pages that look like the pages provided by Cluster Administrator, each new property page should be no larger than 252 dialog units wide and 218 dialog units high, and should contain two standard controls:
    • For the object icon, an icon control positioned at (8,7) with a size of (18,20).
    • For the object name, a static control positioned at (38,12) with a size of (206,10).
  3. To add the page to the property sheet, call the IWCPropertySheetCallback::AddPropertySheetPage method pointed to by piCallback.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

CreatePropertySheetPage, IGetClusterDataInfo, IGetClusterGroupInfo, IGetClusterNetInterfaceInfo, IGetClusterNetworkInfo, IGetClusterNodeInfo, IGetClusterObjectInfo, IGetClusterResourceInfo, IGetClusterUIInfo, IWCPropertySheetCallback, IWCPropertySheetCallback::AddPropertySheetPage, IWEExtendPropertySheet


IWEExtendWizard

Implement the IWEExtendWizard interface to add wizard pages to Cluster Administrator's New Resource Wizard or Cluster Application Wizard.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWEExtendWizard Method | Description
CreateWizardPages | Allows you to create wizard pages and add them to Cluster Administrator's New Resource Wizard or Cluster Application Wizard.

Remarks

To support Wizard97 wizards and wizard pages, implement the IWEExtendWizard97 interface.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.


IWEExtendWizard::CreateWizardPages

The CreateWizardPages method allows you to create wizard pages and add them to Cluster Administrator's New Resource Wizard or Cluster Application Wizard.

HRESULT CreateWizardPages(
  IUnknown *piData,
  IWCWizardCallback *piCallback
);

Parameters

piData
[in] IUnknown interface pointer for retrieving information relating to the wizard pages to be added. By calling IUnknown::QueryInterface with the piData pointer, the following interfaces are available:
  • IGetClusterUIInfo
  • IGetClusterDataInfo
  • IGetClusterObjectInfo

Depending on the type of cluster object for which the wizard page is being created, a pointer to one of the following interfaces is also available:

  • IGetClusterNodeInfo, if the property page relates to a node.
  • IGetClusterGroupInfo, if the property page relates to a group.
  • IGetClusterNetworkInfo, if the property page relates to a network.
  • IGetClusterNetInterfaceInfo, if the property page relates to a network interface.
  • IGetClusterResourceInfo, if the property page relates to a resource.
piCallback
[in] Pointer to an IWCWizardCallback interface implementation used to add the new property pages to the wizard.

Return Values

Return one of the following values or any HRESULT that describes the results of the operation.

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | At least one of the parameters is invalid.
E_NOTIMPL | The extension does not support adding a property page to the Create Group Wizard or Create Resource Wizard.

Remarks

To add Wizard97 wizard pages, use the IWEExtendWizard97::CreateWizard97Pages method.

Notes to Implementers

For each property page to be added

  1. Use piData to call QueryInterface and retrieve an interface pointer for the cluster object associated with the new page. For example, if you are adding a property page for a resource, you want to retrieve a pointer to the IGetClusterResourceInfo interface. Although it is possible to successfully query for interfaces that retrieve data unrelated to the object being extended, you should expect to receive errors when you attempt to call the methods.
  2. To create the page, call the Win32 function CreatePropertySheetPage. To produce pages that look like the pages provided by Cluster Administrator, each new property page should be no larger than 252 dialog units wide and 218 dialog units high, and should contain two standard controls:
    • For the object icon, an icon control positioned at (8,7) with a size of (18,20).
    • For the object name, a static control positioned at (38,12) with a size of (247,10).
  3. To add the page to a Cluster Administrator Wizard, call IWCWizardCallback::AddWizardPage using the piCallback pointer.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

CreatePropertySheetPage, IGetClusterDataInfo, IGetClusterGroupInfo, IGetClusterNetInterfaceInfo, IGetClusterNetworkInfo, IGetClusterNodeInfo, IGetClusterObjectInfo, IGetClusterResourceInfo, IGetClusterUIInfo, IWCWizardCallback, IWCPropertySheetCallback::AddPropertySheetPage, IWEExtendWizard, IWEExtendWizard97, IWEExtendWizard97::CreateWizard97Pages


IWEExtendWizard97

Implement the IWEExtendWizard97 interface to add Wizard97-style wizard pages to a Cluster Administrator wizard.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWEExtendWizard97 Method | Description
CreateWizard97Pages | Allows you to create Wizard 97 wizard pages and add them to a Cluster Administrator wizard.

Remarks

To create non-Wizard97 pages, see IWEExtendWizard.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.


IWEExtendWizard97::CreateWizard97Pages

The CreateWizard97Pages method allows you to create Wizard97 property pages and add them to a Cluster Administrator Wizard.

HRESULT CreateWizard97Pages(
  IUnknown *piData,
  IWCWizard97Callback *piCallback
);

Parameters

piData
[in] IUnknown interface pointer for retrieving information relating to the wizard97 pages to be added. By calling IUnknown::QueryInterface with the piData pointer, the following interfaces are available:
  • IGetClusterUIInfo
  • IGetClusterDataInfo
  • IGetClusterObjectInfo

Depending on the type of cluster object, a pointer to one of the following interfaces is also available:

  • IGetClusterNodeInfo, if the property page relates to a node.
  • IGetClusterGroupInfo, if the property page relates to a group.
  • IGetClusterNetworkInfo, if the property page relates to a network.
  • IGetClusterNetInterfaceInfo, if the property page relates to a network interface.
  • IGetClusterResourceInfo, if the property page relates to a resource.
piCallback
[in] Pointer to an IWCWizard97Callback interface implementation used to add the new Wizard97 property pages to the wizard.

Return Values

Return one of the following values or any HRESULT that describes the results of the operation.

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | At least one of the parameters is invalid.
E_NOTIMPL | The extension does not support adding Wizard97 pages.

Notes to Implementers

If your extension has no Wizard97 pages but does have non-Wizard97 pages, you can either:

  • Support only the IWEExtendWizard interface.
  • Support both the IWEExtendWizard and IWEExtendWizard97 interfaces, but in your implementation of IWEExtendWizard97, query for the IWCWizardCallback interface from the interface passed in by way of the piCallback parameter.

For each Wizard97 property page to be added

  1. Use piData to call QueryInterface and retrieve an interface pointer for the object associated with the new page. For example, if you are adding a property page for a resource, you want to retrieve a pointer to the IGetClusterResourceInfo interface. Although it is possible to successfully query for interfaces that retrieve data unrelated to the object being extended, you should expect to receive errors when you attempt to call the methods.
  2. To create the page, call the Win32 function CreatePropertySheetPage. To produce pages that look like the pages provided by Cluster Administrator, each new wizard97 page should be no larger than 293 dialog units wide and 172 dialog units high, and should contain a static control positioned at (38,12) with a size of (247,10).
  3. To add the page to a Cluster Administrator Wizard, call IWCWizard97Callback::AddWizard97Page using the piCallback pointer.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

CreatePropertySheetPage, IGetClusterDataInfo, IGetClusterGroupInfo, IGetClusterNetInterfaceInfo, IGetClusterNetworkInfo, IGetClusterNodeInfo, IGetClusterObjectInfo, IGetClusterResourceInfo, IGetClusterUIInfo, IWCWizardCallback, IWCPropertySheetCallback::AddPropertySheetPage, IWEExtendWizard, IWEExtendWizard97, IWEExtendWizard97::CreateWizard97Pages


IWEInvokeCommand

Cluster Administrator calls your implementation of the IWEInvokeCommand interface when users select context menu items that you created with the IWEExtendContextMenu interface.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWEInvokeCommand Method | Description
InvokeCommand | Allows you to implement procedures that execute when users select your context menu items.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendContextMenu


IWEInvokeCommand::InvokeCommand

The InvokeCommand method allows you to implement procedures that execute when users select your context menu items.

HRESULT InvokeCommand(
  ULONG nCommandID,
  IUnknown *piData
);

Parameters

nCommandID
[in] Identifier of the menu item containing the command to perform. The identifier represented by nCommandID is the identifier passed to the IWCContextMenuCallback::AddExtensionMenuItem method.
piData
[in] IUnknown interface pointer for retrieving information associated with the command identified by nCommandID. By calling IUnknown::QueryInterface with the piData pointer, the following interfaces are available:
  • IGetClusterUIInfo
  • IGetClusterDataInfo
  • IGetClusterObjectInfo

Depending on the type of cluster object to which the context menu item applies, a pointer to one of the following interfaces is also available:

  • IGetClusterNodeInfo, if the property page relates to a node.
  • IGetClusterGroupInfo, if the property page relates to a group.
  • IGetClusterNetworkInfo, if the property page relates to a network.
  • IGetClusterNetInterfaceInfo, if the property page relates to a network interface.
  • IGetClusterResourceInfo, if the property page relates to a resource.

Return Values

Returns one of the following values or any HRESULT that describes the results of the operation.

Value | Meaning
NOERROR | The operation was successful.
E_NOTIMPL | The operation is not implemented by this method.

Remarks

To create context menu items and add them to Cluster Administrator, use the IWEExtendContextMenu::AddContextMenuItems method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo, IGetClusterGroupInfo, IGetClusterNetInterfaceInfo, IGetClusterNetworkInfo, IGetClusterNodeInfo, IGetClusterObjectInfo, IGetClusterResourceInfo, IGetClusterUIInfo, IWCContextMenuCallback::AddExtensionMenuItem, IWEInvokeCommand, IWEExtendContextMenu::AddContextMenuItems


Cluster Administrator Callback Interfaces

Cluster Administrator implements the following interfaces to allow allow your extension to create new property pages, wizard pages, and context menu items:

  • IWCContextMenuCallback
  • IWCPropertySheetCallback
  • IWCWizardCallback
  • IWCWizard97Callback


IWCContextMenuCallback

The IWCContextMenuCallback interface is called by a Cluster Administrator extension to add items to a Cluster Administrator context menu.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWCContextMenuCallback Method | Description
AddExtensionMenuItem | Adds a menu item to a Cluster Administrator context menu.

Remarks

Use the piCallback pointer that you receive when Cluster Administrator calls your IWEExtendContextMenu::AddContextMenuItems method to call the IWCContextMenuCallback interface.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendContextMenu::AddContextMenuItems


IWCContextMenuCallback::AddExtensionMenuItem

The AddExtensionMenuItem method adds a menu item to a Cluster Administrator context menu.

HRESULT AddExtensionMenuItem(
  BSTR lpszName,
  BSTR lpszStatusBarText,
  ULONG nCommandID,
  ULONG nSubmenuCommandID,
  ULONG uFlags
);

Parameters

lpszName
[in] Pointer to a null-terminated Unicode string containing the name of the item to be added to the menu. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
lpszStatusBarText
[in] Pointer to text to display on the status bar when the new item is selected. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
nCommandID
[in] Identifier for the command to be invoked when the menu item is selected. The nCommandID parameter must not be set to –1.
nSubmenuCommandID
[in] Identifier for a submenu. Submenus are not supported, and the nSubmenuCommandID parameter must be zero.
uFlags
[in] Bitmask of flags that describes the new menu item. One or more of the following values may be set:
Flag | Description
MF_CHECKED | Acts as a toggle with MF_UNCHECKED to place the default check mark next to the item.
MF_UNCHECKED | Acts as a toggle with MF_CHECKED to remove a check mark placed next to the item.
MF_DISABLED | Disables the menu item so it cannot be selected but does not dim it.
MF_ENABLED | Enables the menu item so it can be selected and restores it from its dimmed state if the item was previously dimmed.
MF_GRAYED | Disables the menu item so it cannot be selected and dims it.
MF_MENUBARBREAK | Places the item in a new column. The new column is separated from the old column by a vertical dividing line.
MF_MENUBREAK | Places the item in a new column. No dividing line is placed between the columns.
MF_SEPARATOR | Draws a horizontal dividing line. This line cannot be dimmed, disabled, or highlighted. The lpszName and lpszStatusBarText parameters are ignored.
MF_STRING | Specifies that the menu item is a character string. The lpszName parameter contains a pointer to a NULL-terminated Unicode string. This is the default interpretation.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | The uFlags parameter was set to either MF_OWNERDRAW or MF_POPUP.
E_OUTOFMEMORY | There was an error allocating the menu item.

If AddExtensionMenuItem is not successful, it can return other HRESULTs.

Remarks

The AddExtensionMenuItem method adds items at the top of the context menu and follows them by a separator. The command identified by nCommandID is passed in the nCommandID parameter to the IWEInvokeCommand::InvokeCommand method when the user selects this menu item.

Note that the MF_OWNERDRAW and MF_POPUP flags are not supported specifically for the uFlags parameter.

Cluster Administrator extensions call AddExtensionMenuItem from their IWEExtendContextMenu::AddContextMenuItems method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWCContextMenuCallback, IWEExtendContextMenu::AddContextMenuItems, IWEInvokeCommand::InvokeCommand


IWCPropertySheetCallback

The IWCPropertySheetCallback interface is called by a Cluster Administrator extension to add property pages to a Cluster Administrator property sheet.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWCPropertySheetCallback Method | Description
AddPropertySheetPage | Adds a property page to a Cluster Administrator property sheet.

Remarks

Use the piCallback pointer that you receive when Cluster Administrator calls your IWEExtendPropertySheet::CreatePropertySheetPages method to call the IWCPropertySheetCallback interface.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages


IWCPropertySheetCallback::AddPropertySheetPage

The AddPropertySheetPage method adds a property page to a Cluster Administrator property sheet.

HRESULT AddPropertySheetPage(
  HPROPSHEETPAGE hpage
);

Parameters

hpage
[in] Handle to the property page to be added.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | The hpage parameter is invalid.

If AddPropertySheetPage was not successful, it can return other HRESULTs.

Remarks

Call the AddPropertySheetPage method from your IWEExtendPropertySheet::CreatePropertySheetPages implementation. However, before you call AddPropertySheetPage, call the Win32 function CreatePropertySheetPage to retrieve a handle to pass in the hpage parameter.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

CreatePropertySheetPage, IWCPropertySheetCallback, IWEExtendPropertySheet::CreatePropertySheetPages


IWCWizardCallback

The IWCWizardCallback interface is called by a Cluster Administrator extension to add a property page to a Cluster Administrator Wizard and to manage navigation.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWCWizardCallback Method | Description
AddWizardPage | Adds a property page to a Cluster Administrator Wizard.
EnableNext | Enables or disables the Next or Finish button on a Cluster Administrator Wizard page, depending on whether the current page is last.

Remarks

Use the piCallback pointer that you receive when Cluster Administrator calls your IWEExtendWizard::CreateWizardPages method to call the methods of the IWCWizardCallback interface.

Use IWCWizard97Callback to add Wizard97 pages.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendWizard::CreateWizardPages, IWCWizard97Callback


IWCWizardCallback::AddWizardPage

The AddWizardPage method adds a property page to a Cluster Administrator Wizard.

HRESULT AddWizardPage(
  HPROPSHEETPAGE hpage
);

Parameters

hpage
[in] Handle to the property page to be added.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | The hpage parameter represents an unknown page.

If AddWizardPage is not successful, it can return other HRESULTs.

Remarks

Cluster Administrator extensions call the AddWizardPage method from their IWEExtendWizard::CreateWizardPages methods. Before calling AddWizardPage, extensions must call the Win32 function CreatePropertySheetPage to retrieve a handle to pass in the hpage parameter.

Use IWCWizard97Calllback::AddWizard97Page to add Wizard97 pages.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

CreatePropertySheetPage, IWCWizardCallback, IWEExtendWizard::CreateWizardPages, IWCWizard97Callback::AddWizard97Page


IWCWizardCallback::EnableNext

The EnableNext method enables or disables the Next or Finish button on a Cluster Administrator Wizard page, depending on whether the current page is last.

HRESULT IWCWizardCallback::EnableNext(
  HPROPSHEETPAGE hpage,
  BOOL bEnable
);

Parameters

hpage
[in] Handle to the property page containing the button to be enabled or disabled.
bEnable
[in] Value indicating whether to enable or disable the button. If bEnable is set to TRUE, the appropriate button is enabled. If bEnable is set to FALSE, it is disabled.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | The hpage parameter represents an unknown page.

If EnableNext is not successful, it can return other HRESULTs.

Remarks

Extensions should call the EnableNext method in their handling of the PSN_SETACTIVE message for a property page that they have added to the Cluster Administrator Wizard. Cluster Administrator determines whether the Next or Finish button should be displayed based on the page specified in the hpage parameter.

For Wizard97 pages, use IWCWizard97Callback::EnableNext.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWCWizardCallback, IWCWizard97Callback::EnableNext


IWCWizard97Callback

The IWCWizard97Callback interface is called by a Cluster Administrator extension to add a Wizard97 property page to a Wizard97 wizard, such as the Cluster Application Wizard.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IWCWizard97Callback Method | Description
AddWizard97Page | Adds a property page to a Wizard97 wizard.
EnableNext | Enables or disables the Next or Finish button on a Wizard97 page, depending on whether the current page is last.

Remarks

Use the piCallback pointer that you receive when Cluster Administrator calls your IWEExtendWizard97::CreateWizard97Pages method to call the methods of the IWCWizard97Callback interface.

To add non-Wizard97 pages use IWCWizardCallback.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendWizard97::CreateWizard97Pages, IWCWizardCallback


IWCWizard97Callback::AddWizard97Page

The AddWizard97Page method adds a Wizard97 property page to a Wizard97 wizard, such as the Cluster Application Wizard.

HRESULT AddWizard97Page(
  HPROPSHEETPAGE hpage
);

Parameters

hpage
[in] Handle to the property page to be added.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | The hpage parameter represents an unknown page.

If AddWizard97Page is not successful, it can return other HRESULTs.

Remarks

Cluster Administrator extensions call the AddWizard97Page method from their IWEExtendWizard97::CreateWizard97Pages methods. Before calling AddWizard97Page, extensions must call the Win32 function CreatePropertySheetPage to retrieve a handle to pass in the hpage parameter.

To add non-Wizard97 pages, use IWCWizardCallback::AddWizardPage.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

CreatePropertySheetPage, IWCWizard97Callback, IWEExtendWizard97::CreateWizard97Pages, IWCWizardCallback::AddWizardPage


IWCWizard97Callback::EnableNext

The EnableNext method enables or disables the Next or Finish button on a Wizard97 wizard page, depending on whether the current page is last.

HRESULT IWCWizard97Callback::EnableNext(
  HPROPSHEETPAGE hpage,
  BOOL bEnable
);

Parameters

hpage
[in] Handle to the property page containing the button to be enabled or disabled.
bEnable
[in] Value indicating whether to enable or disable the button. If bEnable is set to TRUE, the appropriate button is enabled. If bEnable is set to FALSE, it is disabled.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | The hpage parameter represents an unknown page.

If EnableNext is not successful, it can return other HRESULTs.

Remarks

Extensions should call the EnableNext method in their handling of the PSN_SETACTIVE message for a property page that they have added to the Cluster Administrator Wizard. Cluster Administrator determines whether the Next or Finish button should be displayed based on the page specified in the hpage parameter.

For non-Wizard97 pages use IWCWizardCallback::EnableNext .

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWCWizard97Callback, IWCWizardCallback::EnableNext


Cluster Administrator Information Interfaces

To retrieve information from Cluster Administrator about the object for which a property page, wizard page, and context menu is being shown, use one of the following interfaces:

  • IGetClusterDataInfo
  • IGetClusterGroupInfo
  • IGetClusterNetInterfaceInfo
  • IGetClusterNetworkInfo
  • IGetClusterNodeInfo
  • IGetClusterObjectInfo
  • IGetClusterResourceInfo
  • IGetClusterUIInfo


IGetClusterDataInfo

The IGetClusterDataInfo interface is called by a Cluster Administrator extension to retrieve information about a cluster.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterDataInfo Method | Description
GetClusterName | Returns the name of the cluster.
GetClusterHandle | Returns a handle to the cluster.
GetObjectCount | Returns a count of the number of selected objects.

Remarks

You can use the IGetClusterDataInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterDataInfo methods.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterDataInfo::GetClusterName

The GetClusterName method returns the name of the cluster.

HRESULT GetClusterName(
  BSTR lpszName,
  LONG *pcchName
);

Parameters

lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the cluster; or NULL to indicate that the caller is requesting only the length of the name. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
pcchName
[in, out] On input, pointer to the size of the buffer, in characters, pointed to by the lpszName parameter. On output, pointer to the total number of characters in the buffer including the NULL-terminating character.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | One or more of the parameters are invalid.
ERROR_MORE_DATA | The buffer pointed to by lpszName is too small to hold the requested name. GetClusterName returns the required number of characters in the content of pcchName.

If GetClusterName is not successful, it can return other HRESULTs.

Remarks

If the lpszName parameter is set to NULL and the pcchName parameter is not set to NULL, the GetClusterName method returns NOERROR.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo


IGetClusterDataInfo::GetClusterHandle

The GetClusterHandle method returns a handle to the cluster.

HCLUSTER GetClusterHandle();

Parameters

This method had no parameters.

Return Values

A cluster handle.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo


IGetClusterDataInfo::GetObjectCount

The IGetClusterDataInfo::GetObjectCount method returns a count of the number of selected cluster objects.

LONG GetObjectCount();

Parameters

This method had no parameters.

Return Values

A count of the number of selected objects.

Remarks

Because Cluster Administrator supports only one selected object, the GetObjectCount method always returns 1. However, Cluster Administrator extensions should be prepared to handle the case where more than one object is selected.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo


IGetClusterGroupInfo

The IGetClusterGroupInfo interface is called by a Cluster Administrator extension to retrieve information about a group.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterGroupInfo Method | Description
GetGroupHandle | Returns a handle to a group.

Remarks

If the object being extended is not a group, queries for IGetClusterGroupInfo methods will fail. Otherwise, you can use the IGetClusterGroupInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterGroupInfo methods.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterGroupInfo::GetGroupHandle

The GetGroupHandle method returns a handle to a group.

HGROUP GetGroupHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target group. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.

Return Values

If GetGroupHandle is successful, it returns a handle for the group represented by lObjIndex.

If GetGroupHandle is not successful, it returns NULL. For more information about the error, call the Win32 function GetLastError.

Remarks

Do not close the handle obtained through this method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

GetLastError, IGetClusterDataInfo::GetObjectCount, IGetClusterGroupInfo


IGetClusterNetInterfaceInfo

The IGetClusterNetInterfaceInfo interface is called by a Cluster Administrator extension to retrieve information about a network interface.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterNetInterfaceInfo Method | Description
GetNetInterfaceHandle | Returns a handle to a network interface.

Remarks

If the object being extended is not a network interface, queries for IGetClusterNetInterfaceInfo methods will fail. Otherwise, you can use the IGetClusterNetInterfaceInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterNetInterfaceInfo methods.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterNetInterfaceInfo::GetNetInterfaceHandle

The GetNetInterfaceHandle method retrieves a handle to a node.

HNETINTERFACE GetNetInterfaceHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target network interface. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.

Return Values

If GetNetInterfaceHandle is successful, it returns a handle for the network interface represented by lObjIndex.

If GetNetInterfaceHandle is not successful, it returns NULL. For more information about the error, call the Win32 function GetLastError.

Remarks

Do not close the handle obtained through this method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

GetLastError, IGetClusterDataInfo::GetObjectCount, IGetClusterNetInterfaceInfo


IGetClusterNetworkInfo

The IGetClusterNetworkInfo interface is called by a Cluster Administrator extension to retrieve information about a network.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterNetworkInfo Method | Description
GetNetworkHandle | Retrieves a handle to a network.

Remarks

If the object being extended is not a network, queries for IGetClusterNetworkInfo methods will fail. Otherwise, you can use the IGetClusterNetworkInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterNetworkInfo methods.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterNetworkInfo::GetNetworkHandle

The GetNetworkHandle method retrieves a handle to a network.

HNETWORK GetNetworkHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target network. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.

Return Values

If GetNetworkHandle is successful, it returns a handle for the network represented by lObjIndex.

If GetNetworkHandle is not successful, it returns NULL. For more information about the error, call the Win32 function GetLastError.

Remarks

Do not close the handle obtained through this method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

GetLastError, IGetClusterDataInfo::GetObjectCount, IGetClusterNetworkInfo


IGetClusterNodeInfo

The IGetClusterNodeInfo interface is called by a Cluster Administrator extension to retrieve information about a node.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterNetworkInfo Method | Description
GetNodeHandle | Returns a handle to a node.

Remarks

If the object being extended is not a node, queries for IGetClusterNodenfo methods will fail. Otherwise, you can use the IGetClusterNodeInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterNodeInfo methods.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterNodeInfo::GetNodeHandle

The GetNodeHandle method returns a handle to a node.

HNODE GetNodeHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target node. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.

Return Values

If GetNodeHandle is successful, it returns a handle for the node represented by lObjIndex.

If GetNodeHandle is not successful, it returns NULL. For more information about the error, call the Win32 function GetLastError.

Remarks

Do not close the handle obtained through this method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

GetLastError, IGetClusterDataInfo::GetObjectCount, IGetClusterNodeInfo


IGetClusterObjectInfo

The IGetClusterObjectInfo interface is called by a Cluster Administrator extension to retrieve information about a cluster object.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterNetworkInfo Method | Description
GetObjectName | Returns the name of a cluster object.
GetObjectType | Returns the type of a cluster object.

Remarks

You can use the IGetClusterObjectInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterObjectInfo methods.

Do not obtain other information interfaces, such as IGetClusterGroupInfo, from the IGetClusterObjectInfo interface. While QueryInterface will return a valid interface, the operation is not valid in the context of the cluster, and the result is an interface that represents no real cluster object. For an illustration, see IGetClusterResourceInfo.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterObjectInfo::GetObjectName

The GetObjectName method returns the name of a cluster object.

HRESULT GetObjectName(
  LONG lObjIndex,
  BSTR lpszName,
  LONG *pcchName
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target object. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.
lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the object associated with lObjIndex. The lpszName parameter can be NULL, indicating that the caller is requesting only the name length. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
pcchName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszName parameter. The pcchName parameter cannot be NULL. On output, pointer to the count of characters in the name stored in the content of lpszName, including the NULL-terminating character.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | One or more of the parameters are invalid.
ERROR_MORE_DATA | The buffer pointed to by lpszName is too small to hold the requested name. GetObjectName returns the required number of characters in the content of pcchName.

If GetObjectName is not successful, it can return other HRESULTs.

Remarks

If the lpszName parameter is specified as NULL, the GetObjectName method returns NOERROR.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo::GetObjectCount, IGetClusterObjectInfo


IGetClusterObjectInfo::GetObjectType

The GetObjectType method returns the type of a cluster object.

CLUADMEX_OBJECT_TYPE GetObjectType(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target object. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.

Return Values

If GetObjectType is successful, it returns one of the following values representing object types:

  • CLUADMEX_OT_NONE
  • CLUADMEX_OT_CLUSTER
  • CLUADMEX_OT_NETINTERFACE
  • CLUADMEX_OT_NETWORK
  • CLUADMEX_OT_NODE
  • CLUADMEX_OT_GROUP
  • CLUADMEX_OT_RESOURCE
  • CLUADMEX_OT_RESOURCETYPE

If GetObjectType is not successful, it returns –1. For more information, call the Win32 function GetLastError.

Remarks

CLUADMEX_OT_NONE is returned when Cluster Administrator does not recognize the object type.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

GetLastError, IGetClusterDataInfo::GetObjectCount, IGetClusterObjectInfo


IGetClusterResourceInfo

The IGetClusterResourceInfo interface is called by a Cluster Administrator extension to retrieve information about a resource.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterResourceInfo Method | Description
GetResourceHandle | Returns a handle to a resource.
GetResourceNetworkName | Returns the name of the network managed by the Network Name resource on which a resource depends.
GetResourceTypeName | Returns the resource type of a resource.

Remarks

If the object being extended is not a resource, queries for IGetClusterResourceInfo methods will fail. Otherwise, you can use the IGetClusterResourceInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterResourceInfo methods.

Use the IGetClusterResourceInfo interface only in the context of a resource extension. Do not obtain other information interfaces, such as IGetClusterGroupInfo, from the IGetClusterResourceInfo interface. While QueryInterface will return a valid interface, the operation is not valid in the context of the cluster, and the result is an interface that represents no real cluster object. For illustration, in the following code, the section enclosed by C-style comments will fail:

//
// Context is a resource extension.
//
HRESULT
CExtObject::HrGetResourceInfo(
    IGetClusterResourceInfo *piResInfo
)
{
    HRESULT   hr;
    HRESOURCE hRes;
    HGROUP    hGroup;
    HCLUSTER  hCluster;
    DWORD     cchNameSize = MAX_NAME_SIZE; // 256
    WCHAR     szGroupName[cchNameSize];

    IGetClusterGroupInfo *pGrpInfo;

    hRes = piResInfo->GetResourceHandle();

    //
    // Get group handle
    //
/**************************************
Incorrect:

    //
    // Obtain an IGetClusterGroupInfo interface from IGetClusterResourceInfo.
    // By the rules of QueryInterface, this must return a valid interface.
    // But it is not a valid cluster operation so the interface won't represent a real object.
    //
    hr = pResInfo->QueryInterface(
                IID_IGetClusterGroupInfo,
                (LPVOID *) &pGrpInfo );

    //
    // Interface is valid, will pass this test.
    //
    if( FAILED( hr ) )
        goto Error;

    //
    // FAILS!
    // Interface does not represent a real cluster object.
    //
    hGrp = pGrpInfo->GetGroupHandle( 0 );

**************************************/
// Correct:
    //
    // Use the valid resource handle to call GetClusterResourceState.
    // This yields the name of the group to which it belongs, which
    // can be used to obtain a group handle.
    //
    dwState = GetClusterResourceState(
                hRes,
                NULL,
                0,
                szGroupName,
                &cchGroupNameSize );

    // Add error check.

    hCluster = OpenCluster( g_szClusterName );

    // Add error check.

    hGrp = OpenClusterGroup( hCluster, szGroupName );

    // After error check, use group handle...

}

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterResourceInfo::GetResourceHandle

The IGetClusterResourceInfo::GetResourceHandle method returns a handle to a resource.

HRESOURCE GetResourceHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target resource. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.

Return Values

If GetResourceHandle is successful, it returns a handle for the resource represented by lObjIndex.

If GetResourceHandle is not successful, it returns NULL. For more information about the error, call the Win32 function GetLastError.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

GetLastError, IGetClusterDataInfo::GetObjectCount, IGetClusterResourceInfo


IGetClusterResourceInfo::GetResourceNetworkName

The GetResourceNetworkName method returns the name of the network managed by the Network Name resource on which a resource depends.

BOOL GetResourceNetworkName(
  LONG lObjIndex,
  BSTR lpszNetName,
  ULONG *pcchNetName
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target resource. The target resource may or may not depend on a Network Name resource. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.
lpszNetName
[out] Pointer to a null-terminated Unicode string containing the name of the network upon which the resource indexed by lObjIndex depends. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
pcchNetName
[in, out] Pointer to the maximum count in characters of the buffer pointed to by lpszNetName. On input, this value should be large enough to contain MAX_COMPUTERNAME_LENGTH + 1 characters. On output, pcchNetName points to the actual number of characters copied to the content of lpszNetName.

Return Values

Value | Meaning
TRUE | The resource indexed by lObjIndex has a dependency on a Network Name resource, and the name of the network was successfully returned.
FALSE | The resource indexed by lObjIndex does not have a dependency on a Network Name resource.

Remarks

The GetResourceNetworkName method is necessary to allow Cluster Administrator extension property pages to determine whether a resource has an existing or a pending dependency on a Network Name resource.

The name of the network is stored in the Network Name resource's Name private property. The Network Name resource's Name common property is the name of the resource, not the network.

MAX_COMPUTERNAME_LENGTH is a constant defined in the Win32 header file winbase.h.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo::GetObjectCount, IGetClusterResourceInfo


IGetClusterResourceInfo::GetResourceTypeName

The GetResourceTypeName method returns the type of a resource.

HRESULT GetResourceTypeName(
  LONG lObjIndex,
  BSTR lpszResTypeName,
  LONG *pcchResTypeName
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target resource. lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.
lpszResTypeName
[out] Pointer to the type of the resource associated with lObjIndex. The lpszResTypeName parameter can be NULL, indicating that the caller is requesting only the length of the resource type. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
pcchResTypeName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszResTypeName parameter. The pcchResTypeName parameter cannot be NULL. On output, pointer to the count of characters in the resource type name stored in the content of lpszResTypeName, including the NULL-terminating character.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | One or more of the parameters are invalid.
ERROR_MORE_DATA | The buffer pointed to by lpszResTypeName is too small to hold the requested resource type. GetResourceTypeName returns the required number of characters in the content of pcchResTypeName.

If GetResourceTypeName is not successful, it can return other HRESULTs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterDataInfo::GetObjectCount, IGetClusterResourceInfo


IGetClusterUIInfo

The IGetClusterUIInfo interface is called by a Cluster Administrator extension to retrieve information about Cluster Administrator's user interface.

Methods in Vtable Order

IUnknown Method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments the reference count.
Release | Decrements the reference count.

IGetClusterUIInfo Method | Description
GetClusterName | Returns the name of the cluster.
GetLocale | Returns the locale identifier to be used with property and wizard pages.
GetFont | Returns a handle to the font to be displayed on property and wizard pages.
GetIcon | Returns a handle to the icon to use in the upper-left corner of property and wizard pages.

Remarks

You can use the IGetClusterUIInfo interface when Cluster Administrator calls your implementations of the following methods:

  • IWEExtendPropertySheet::CreatePropertySheetPages
  • IWEExtendContextMenu::AddContextMenuItems
  • IWEExtendWizard::CreateWizardPages
  • IWEExtendWizard97::CreateWizard97Pages
  • IWEInvokeCommand::InvokeCommand

Cluster Administrator passes in an IUnknown pointer, piData. Use piData to call QueryInterface for one of the IGetClusterUIInfo methods.

Do not obtain other information interfaces, such as IGetClusterGroupInfo, from the IGetClusterUIInfo interface. While QueryInterface will return a valid interface, the operation is not valid in the context of the cluster, and the result is an interface that represents no real cluster object. For an illustration, see IGetClusterResourceInfo.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IWEExtendPropertySheet::CreatePropertySheetPages, IWEExtendContextMenu::AddContextMenuItems, IWEExtendWizard::CreateWizardPages, IWEExtendWizard97::CreateWizard97Pages, IWEInvokeCommand::InvokeCommand


IGetClusterUIInfo::GetClusterName

The GetClusterName method returns the name of the cluster.

HRESULT GetClusterName(
  BSTR lpszName,
  LONG *pcchName
);

Parameters

lpszName
[out] Pointer to a null-terminated Unicode string containing the name of the cluster, or NULL to indicate that the caller is requesting only the length of the name. Although declared as a BSTR, this parameter is implemented as an LPWSTR.
pcchName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszName parameter. On output, pointer to the total number of characters in the buffer including the NULL-terminating character.

Return Values

Value | Meaning
NOERROR | The operation was successful.
E_INVALIDARG | One or more of the parameters are invalid.
ERROR_MORE_DATA | The buffer pointed to by lpszName is too small to hold the requested name. GetClusterName returns the required number of characters in the content of pcchName.

If GetClusterName is not successful, it can return other HRESULTs.

Remarks

If the lpszName parameter is set to NULL and the pcchName parameter is not set to NULL, the GetClusterName method returns NOERROR.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterUIInfo


IGetClusterUIInfo::GetLocale

The GetLocale method returns the locale identifier to be used with property and wizard pages.

LCID GetLocale();

Parameters

This method has no parameters.

Return Values

GetLocale always returns the locale identifier for the cluster.

Remarks

Cluster Administrator extensions call the GetLocale method to retrieve the locale identifier that can be used for loading dialog resources. A single Cluster Administrator extension DLL can support multiple languages.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterUIInfo


IGetClusterUIInfo::GetFont

The IGetClusterUIInfo::GetFont method returns a handle to the font to be displayed on property and wizard pages.

HFONT GetFont();

Parameters

This method has no parameters.

Return Values

If GetFont is successful, it returns a font handle.

Remarks

The GetFont method returns the font handle as NULL. Cluster Administrator extensions should not use this return value in their user interface displays.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterUIInfo


IGetClusterUIInfo::GetIcon

The IGetIcon method returns a handle to the icon to use in the upper-left corner of property and wizard pages.

HICON GetIcon();

Parameters

This method has no parameters.

Return Values

GetIcon always returns a handle to an icon.

Remarks

With the GetIcon method, each property page or wizard page should have an icon control positioned at (8,7) with a size of (18,20).

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Cluadmex.idl.
Library: Use Cluadmex.lib.

See Also

IGetClusterUIInfo


Cluster Administrator Extension Registration Functions

A Cluster Administrator extension DLL must be registered with the cluster and with COM. For information on how to register a Cluster Administrator extension DLL, see Registering Resource Types.

The Cluster Administrator extension registration functions follow.

Function | Description
DllRegisterCluAdminExtension | Registers a Cluster Administrator extension DLL with the cluster by adding information to the cluster database.
DllUnregisterCluAdminExtension | Cancels the registration of a Cluster Administrator extension DLL with the cluster by removing information from the cluster database.
DllRegisterServer | Registers a Cluster Administrator extension DLL with COM by adding information to the registry.
DllUnregisterServer | Cancels the registration of a Cluster Administrator extension DLL with COM by removing information from the registry.


DllRegisterCluAdminExtension

The DllRegisterCluAdminExtension function registers a Cluster Administrator extension DLL with the cluster by adding information to the cluster database.

STDAPI DllRegisterCluAdminExtension(
  HCLUSTER hCluster
);

Parameters

hCluster
[in] Handle to the cluster to modify in the cluster database.

Return Values

Value | Meaning
NOERROR | The Cluster Administrator extension DLL was successfully registered.

If DllRegisterCluAdminExtension is not successful, it can return a Win32 error value.

Remarks

You must implement this function in your extension DLL. For each cluster object that you extend in the DLL, append the CLSID of the extension to the object's AdminExtensions property. For example, if your extension DLL extends a group, you would add the CLSID of the extension to the AdminExtensions property of the group.

Note that the AdminExtensions property is a multi-sz value. There may already be extensions defined for the object. Your implementation should not overwrite existing CLSIDs or create duplicate entries in the AdminExtensions properties.

Example

Run the Resource Type Wizard and review the implementation of DllRegisterCluAdminExtension.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.


DllUnregisterCluAdminExtension

The DllUnregisterCluAdminExtension function cancels the registration of a Cluster Administrator extension DLL with the cluster by removing information from the cluster database.

STDAPI DllUnregisterCluAdminExtension(
  HCLUSTER hCluster
);

Parameters

hCluster
[in] Handle to the cluster to modify in the cluster database.

Return Values

Value | Meaning
NOERROR | Registration for the Cluster Administrator extension DLL was successfully removed.

If DllUnregisterCluAdminExtension is not successful, it returns a Win32 error value.

Remarks

You must implement this function in your extension DLL. Remove the CLSID of your extension from the AdminExtensions property of each cluster object extended by your DLL.

Example

Run the Resource Type Wizard and review the implementation of DllUnregisterCluAdminExtension.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.


DllRegisterServer

The DllRegisterServer function is described in detail in the COM Reference section of the Platform SDK. The following information applies only to registering extension DLLs.

Remarks

Client-side registration must be done on each computer on which Cluster Administrator runs.

Extension DLLs must be implemented as an in-process (INPROC) server.

For CoCreateInstance to find the correct server, its CLSID must be registered under HKEY_CLASSES_ROOT\CLSID. At the root, an empty-named value must contain the name of the Cluster Administrator extension. Three subkeys are situated below the root:

  • InProcServer32
  • ProgID
  • VersionIndependentProgID

An empty-named value must be defined at the InProcServer32 key to contain the path to the extension DLL. An empty-named value must be defined at the ProgID and VersionIndependentProgID keys to contain the short name of the extension.

To complete the registration, create a key at HKEY_CLASSES_ROOT\CLUADMEX.<short name of extension>. An empty-named value must be defined there with the name of the extension. Below that, a CLSID key must be defined with an empty-named value containing the extension CLSID.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Olectl.h.


DllUnregisterServer

The DllUnregisterServer function is described in detail in the COM Reference section of the Platform SDK.

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98: Requires Windows 95 or later.
Header: Declared in Olectl.h.


Cluster Properties

Each cluster object has a set of properties that define its identity and behavior in the cluster. Applications and resource DLLs manipulate the properties of cluster objects to maintain awareness of the cluster and to change the cluster to suit their needs.

Reference information on cluster properties is divided into the following sections based on property scope:

  • Common Properties are attributes possessed by all instances of a cluster object.
  • Private Properties are only possessed by individual object instances.


Common Properties

Common properties are attributes possessed by every instance of a cluster object. For example, every group possesses a set of group common properties.

Refer to the following sections for reference information on the common properties for an object:

  • Cluster Common Properties
  • Group Common Properties
  • Network Common Properties
  • Network Interface Common Properties
  • Node Common Properties
  • Resource Common Properties
  • Resource Type Common Properties

For more information on working with properties, see Getting Object Information.


Cluster Common Properties

Cluster common properties are stored in the cluster database and apply to the cluster as a whole. Common cluster properties follow.

Property | Access
AdminExtensions | Read/write
DefaultNetworkRole | Read/write
Description | Read/write
Security | Read/write
Security Descriptor | Read/write


AdminExtensions Property for Clusters

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extensions that are associated with the cluster. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


DefaultNetworkRole Property for Clusters

The DefaultNetworkRole property specifies the Role that the cluster automatically assigns to any newly discovered or created network.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | ClusterNetworkRoleNone
Maximum | ClusterNetworkRoleInternalAndClient
Default | ClusterNetworkRoleInternalAndClient

Remarks

When the Cluster service detects a new network, it sets the network's Role property to the value specified by DefaultNetworkRole. Thereafter, the network's role can be changed only by adjusting its Role property. Changing DefaultNetworkRole will not affect previously detected networks.

The DefaultNetworkRole property can be set to one of the following values.

Value | Description
ClusterNetworkRoleNone | The network is not used by the cluster.
ClusterNetworkRoleClientAccess | The network is used to connect client systems to the cluster.
ClusterNetworkRoleInternalUse | The network is used to carry internal cluster communication.
ClusterNetworkRoleInternalAndClient | The network is used to connect client systems and to carry internal cluster communication.

In versions of Microsoft® Windows NT® earlier than Windows® 2000, the Cluster service automatically applied a value of ClusterNetworkRoleClientAccess to new networks.

Example Code

The property value portion of a property list entry for DefaultNetworkRole can be set with the following example code code:

DWORD DefaultNetworkRoleData = ClusterNetworkRoleInternalAndClient;
CLUSPROP_DWORD DefaultNetworkRoleValue;
DefaultNetworkRoleValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
DefaultNetworkRoleValue.cbLength = sizeof(DWORD);
DefaultNetworkRoleValue.dw = DefaultNetworkRoleData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Description Property for Clusters

The Description property stores administrative comments about the cluster. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with with the following example code:

WCHAR szDescriptionData[] = L"Cluster description";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Security Property for Clusters

The Security property stores the Windows NT 4.0 security descriptor of a cluster. The following table summarizes the attributes of the Security property.

Attribute | Value
Data type | Byte array
Access | Read/write (see Remarks)
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | See Maximum String Size.
Default | 0

Remarks

While the property value is read/write, the underlying security descriptor can only be changed through the Access Control or Network Management APIs. To change the value of the Security property:

  • Retrieve the value of the property.
  • Assign the value to a SECURITY_DESCRIPTOR structure.
  • Pass the value to any Access Control or Network Management API function that will change the discretionary access-control list (DACL) of the descriptor, such as SetSecurityDescriptorDacl or NetShareSetInfo.
  • Once the value has been modified, update the Security property.

For Windows 2000 systems, use the Security Descriptor property.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

Access Control, CLUSPROP_BINARY, Network Management, NetShareSetInfo, Security Descriptor, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl


Security Descriptor Property for Clusters

The Security Descriptor property stores the Windows 2000 security descriptor of a cluster. The following table summarizes the attributes of the Security Descriptor property.

Attribute | Value
Data type | Byte array
Access | Read/write (see Remarks)
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | See Maximum String Size.
Default | 0

Remarks

Although the property value is read/write, the underlying security descriptor can be changed only through the Access Control or Network Management APIs. To change the value of the Security Descriptor property:

  • Retrieve the value of the property.
  • Assign the value to a SECURITY_DESCRIPTOR structure.
  • Pass the value to any Access Control or Network Management API function that will change the DACL of the descriptor, such as SetSecurityDescriptorDacl or NetShareSetInfo.
  • Once the value has been modified, update the Security Descriptor property.

For Windows NT 4.0 systems, use the Security property.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

Access Control, CLUSPROP_BINARY, Network Management, NetShareSetInfo, Security, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl


Group Common Properties

Common properties for groups are data values stored in the cluster database that describe the identity and behavior of each group in a cluster. Common properties for groups follow.

Property | Access
AdminExtensions | Read/write
AutoFailbackType | Read/write
Description | Read/write
FailbackWindowEnd | Read/write
FailbackWindowStart | Read/write
FailoverPeriod | Read/write
FailoverThreshold | Read/write
LoadBalState | Read/write
Name | Read-only
PersistentState | Read/write

For more information on working with properties, see Getting Group Information.


AdminExtensions Property for Groups

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extensions that are associated with the group. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | See Maximum String Size.
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


AutoFailbackType Property for Groups

The AutoFailbackType property specifies whether the group should automatically be failed back to the node identified as its preferred owner when that node comes back online following a failover. The following table summarizes the attributes of the AutoFailbackType property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | ClusterGroupPreventFailback
Maximum | ClusterGroupAllowFailback
Default | ClusterGroupPreventFailback

Remarks

The data for the AutoFailbackType property can be set to one of the following values.

Value | Description
ClusterGroupPreventFailback | Prevents failback.
ClusterGroupAllowFailback | Allows failback (requires a preferred owners list for the group).

Note that setting this property to ClusterGroupAllowFailback has no effect if you have not specified a preferred owners list for the group. Use the SetClusterGroupNodeList function to specify a preferred owners list.

Example Code

The property value portion of a property list entry for AutoFailbackType can be set with the following example code:

DWORD AutoFailbackTypeData = ClusterGroupAllowFailback;
CLUSPROP_DWORD AutoFailbackTypeValue;
AutoFailbackTypeValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
AutoFailbackTypeValue.cbLength = sizeof(DWORD);
AutoFailbackTypeValue.dw = AutoFailbackTypeData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Description Property for Groups

The Description property provides comments about the group. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with the following example code:

WCHAR szDescriptionData[] = L"Group description";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


FailbackWindowEnd Property for Groups

The FailbackWindowEnd property provides the latest time that the group can be failed back to the node identified as its preferred owner node. The following table summarizes the attributes of the FailbackWindowEnd property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0 (specifies midnight)
Maximum | 23 (specifies 11:00 P.M.) or -1 (0xFFFFFFFF for no failback window)
Default | -1 ( 0xFFFFFFFF)

Remarks

The value of the FailbackWindowEnd property can be set to the following values:

Value | Description
0 to 23 | Indicates the hour of day (local cluster time) that the failback window ends.
-1 (0xFFFFFFFF) | No failback window exists.

Both the FailbackWindowStart and FailbackWindowEnd properties must be specified for a failback window to exist.

  • If a failback window exists, failback will only take place between the hours of FailbackWindowStart and FailbackWindowEnd if the group's preferred node is active or becomes active during that interval.
  • If no failback window exists, failback occurs immediately after the preferred node becomes active.

Example Code

The property value portion of a property list entry for FailbackWindowEnd can be set with the following example code:

DWORD FailbackWindowEndData = 12;
CLUSPROP_DWORD FailbackWindowEndValue;
FailbackWindowEndValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailbackWindowEndValue.cbLength = sizeof(DWORD);
FailbackWindowEndValue.dw = FailbackWindowEndData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, FailbackWindowStart


FailbackWindowStart Property for Groups

The FailbackWindowStart property provides the earliest time (that is, local time as kept by the cluster) that the group can be failed back to the node identified as its preferred owner node. The following table summarizes the attributes of the FailbackWindowStart property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0 (specifies midnight)-1 (unsigned 0xFFFFFFFF)
Maximum | 23 (specifies 11:00 P.M.) or -1 (0xFFFFFFFF for no failback window)
Default | -1 (unsigned 0xFFFFFFFF)

Remarks

The value of the FailbackWindowStart property can be set to the following values.

Value | Description
0 to 23 | Indicates the hour of day (local cluster time) that the failback window ends.
-1 (0xFFFFFFFF) | No failback window exists.

Both the FailbackWindowEnd and FailbackWindowStart properties must be specified for a failback window to exist.

  • If a failback window exists, failback will only take place between the hours of FailbackWindowStart and FailbackWindowEnd if the group's preferred node is active or becomes active during that interval.
  • If no failback window exists, failback occurs immediately after the preferred node becomes active.

If the current owner of the group fails before the time specified by FailbackWindowStart, every group hosted by the failed node is moved regardless of the failback window settings.

Example Code

The property value portion of a property list entry for FailbackWindowStart can be set with the following example code:

DWORD FailbackWindowStartData = 10;
CLUSPROP_DWORD FailbackWindowStartValue;
FailbackWindowStartValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailbackWindowStartValue.cbLength = sizeof(DWORD);
FailbackWindowStartValue.dw = FailbackWindowStartData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, FailbackWindowEnd


FailoverPeriod Property for Groups

The FailoverPeriod property specifies a number of hours during which a maximum number of failover attempts, specified by FailoverThreshold, can occur. The following table summarizes the attributes of the FailoverPeriod property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 1193
Default | 6

Remarks

If the Cluster service exceeds the number of failover attempts specified by FailoverThreshold within the time interval specified by FailoverPeriod, it stops trying to fail over the group.

For example, if FailoverThreshold is set to 2 and FailoverPeriod is set to 1, then a node can tolerate two failover attempts of the group within any 1-hour interval. More than three failover attempts can occur, as long as they occur over an interval that is greater than 1 hour.

FailoverPeriod has a maximum value of 1193 hours. If a value for FailoverPeriod is not specified, the default value is 6 hours.

Example Code

The property value portion of a property list entry for FailoverPeriod can be set with the following example code:

DWORD FailoverPeriodData = 5;
CLUSPROP_DWORD FailoverPeriodValue;
FailoverPeriodValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailoverPeriodValue.cbLength = sizeof(DWORD);
FailoverPeriodValue.dw = FailoverPeriodData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, FailoverThreshold, RestartPeriod


FailoverThreshold Property for Groups

The FailoverThreshold property specifies the maximum number of failover attempts that can be made on a group within a time interval defined by FailoverPeriod. The following table summarizes the attributes of the FailoverThreshold property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 10

Remarks

If the Cluster service exceeds the number of failover attempts specified by FailoverThreshold within the time interval specified by FailoverPeriod, it stops trying to fail over the group.

For example, if FailoverThreshold is set to 2 and RestartPeriod is set to 1, a node can tolerate 2 failover attempts of the group within any 1-hour interval. More than 3 failover attempts can occur, as long as they occur over an interval that is greater than 1 hour.

If a value for FailoverThreshold is not specified, the default value is 10.

Example Code

The property value portion of a property list entry for FailoverThreshold can be set with the following example code:

DWORD FailoverThresholdData = 5;
CLUSPROP_DWORD FailoverThresholdValue;
FailoverThresholdValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailoverThresholdValue.cbLength = sizeof(DWORD);
FailoverThresholdValue.dw = FailoverThresholdData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, FailoverPeriod, RestartPeriod


LoadBalState Property for Groups

The LoadBalState property is reserved for future use and is not used by Windows Clustering at this time.


Name Property for Groups

The Name property specifies the name of the group. The following table summarizes the attributes of the Name property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Name property is read-only, it cannot be changed using the CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code. Applications can change a group's name by calling the Cluster API function SetClusterGroupName.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, SetClusterGroupName


PersistentState Property for Groups

The PersistentState property specifies whether a group should be automaticallybrought online when the cluster forms. The following table summarizes the attributes of the PersistentState property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | FALSE (0)
Maximum | TRUE (1 or other nonzero)
Default | FALSE

Remarks

Set PersistentState to TRUE (any nonzero value, preferably 1) for any group that should be automatically brought online when the cluster forms. (for information on the form/join process, see Nodes). The default value is FALSE (0) which means that the group is left offline when the cluster forms.

Resources use their group's PersistentState property when they lack a value for their own PersistentState property.

Example Code

The property value portion of a property list entry for PersistentState can be set with the following example code:

DWORD PersistentStateData = FALSE;
CLUSPROP_DWORD PersistentStateValue;
PersistentStateValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PersistentStateValue.cbLength = sizeof(DWORD);
PersistentStateValue.dw = PersistentStateData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, PersistentState


Network Common Properties

Common properties for networks are data values stored in the cluster database that describe the identity and behavior of each network in a cluster. Common properties for networks follow.

Property | Access
Address | Read-only
AddressMask | Read-only
AdminExtensions | Read/write
Description | Read/write
Name | Read-only
Role | Read/write

For more information on working with properties, see Getting Network Information.


Address Property for Networks

The Address property provides the address for the entire network or subnet. The following table summarizes the attributes of the Address property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size.)
Default | NULL

Remarks

The Address property does not specify the address of an individual node.

The data is formatted as xxx.xxx.xxx.xxx where xxx represents a decimal number between 0 and 255.

Because the Address property is read-only, it cannot be changed using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETWORK_SET_COMMON_PROPERTIES, CLUSPROP_SZ


AddressMask Property for Networks

The AddressMask property provides the mask that distinguishes the network and host portions of an address. The following table summarizes the attributes of the AddressMask property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size)
Default | NULL

Remarks

The data in the AddressMask property is formatted as xxx.xxx.xxx.xxx where xxx represents a decimal number between 0 and 255.

Because the AddressMask property is read-only, it cannot be changed using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETWORK_SET_COMMON_PROPERTIES, CLUSPROP_SZ


AdminExtensions Property for Networks

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extensions that are associated with the network. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | See Maximum String Size.
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


Description Property for Networks

The Description property provides comments about the network. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with the following example code:

WCHAR szDescriptionData[] = L"External network";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Name Property for Networks

The Name property provides the name of the network. The following table summarizes the attributes of the Name property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Name property is read-only, it cannot be changed using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code. Applications can change a network's name only by calling SetClusterNetworkName, which is one of the network management functions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETWORK_SET_COMMON_PROPERTIES, CLUSPROP_SZ, SetClusterNetworkName


Role Property for Networks

The Role property provides the role of the network in the cluster. The following table summarizes the attributes of the Role property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | ClusterNetworkRoleNone
Maximum | ClusterNetworkRoleInternalAndClient
Default | ClusterNetworkRoleInternalAndClient

Remarks

The data value for the Role property can be set to one of the following values.

Role property data value | Description
ClusterNetworkRoleNone | The network is not used by the cluster.
ClusterNetworkRoleClientAccess | The network is used to connect client systems to the cluster.
ClusterNetworkRoleInternalUse | The network is used to carry internal cluster communication.
ClusterNetworkRoleInternalAndClient | The network is used to connect client systems and to carry internal cluster communication.

There are some restrictions to the data value. If any IP Address resources reference this network, the Role property may not be changed to ClusterNetworkRoleNone or ClusterNetworkRoleInternalUse. If this network is the only one used for internal cluster communication, the Role property may not be changed to ClusterNetworkRoleNone or ClusterNetworkRoleClientAccess.

Example Code

The property value portion of a property list entry for Role can be set with the following example code:

DWORD RoleData = ClusterNetworkRoleClientAccess;
CLUSPROP_DWORD RoleValue;
RoleValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RoleValue.cbLength = sizeof(DWORD);
RoleValue.dw = RoleData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Network Interface Common Properties

Common properties for network interfaces are data values stored in the cluster database that describe the identity and behavior of each network interface in a cluster. Common properties for network interfaces follow.

Property | Access
Adapter | Read-only
Address | Read-only
AdminExtensions | Read/write
Description | Read/write
Name | Read-only
Network | Read-only
Node | Read-only

For more information on working with properties, see Getting Network Interface Information.


Adapter Property for Network Interfaces

The Adapter property provides the name that is used to uniquely identify the network interface in the cluster. The following table summarizes the attributes of the Adapter property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Adapter property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES, CLUSPROP_SZ


Address Property for Network Interfaces

The Address property provides the primary network address that the node uses for the network interface. The following table summarizes the attributes of the Address property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | 255.255.255.255
Default | NULL

Remarks

A network interface's primary IP address is an example of the data that is typically stored for the Address property.

The data in the Address property is formatted as xxx.xxx.xxx.xxx where xxx represents a decimal number between 0 and 255.

Because the Address property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES, CLUSPROP_SZ


AdminExtensions Property for Network Interfaces

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extensions that are associated with the network interface. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | See Maximum String Size.
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


Description Property for Network Interfaces

The Description property provides comments about the network interface. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with the following example code:

WCHAR szDescriptionData[] = L"Network Interface Description";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Name Property for Network Interfaces

The Name property provides the cluster-generated name for the network interface. This name appears on the network interface's property sheets in Cluster Administrator and is the name passed to the OpenClusterNetInterface function. The following table summarizes the attributes of the Name property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Name property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES, CLUSPROP_SZ, OpenClusterNetInterface


Network Property for Network Interfaces

The Network property provides the name of the network to which the network interface is connected. The following table summarizes the attributes of the Network property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Network property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES, CLUSPROP_SZ


Node Property for Network Interfaces

The Node property provides the name of the node in which the network interface is installed. The following table summarizes the attributes of the Node property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Node property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES, CLUSPROP_SZ


Node Common Properties

Common properties for nodes are data values stored in the cluster database that describe the identity and behavior of each node in a cluster. Common properties for nodes follow.

Property | Access
AdminExtensions | Read/write
BuildNumber | Read-only
CSDVersion | Read-only
Description | Read/write
EnableEventLogReplication | Read-write
MajorVersion | Read-only
MinorVersion | Read-only
NodeHighestVersion | Read-only
NodeLowestVersion | Read-only
NodeName | Read-only

For more information on working with properties, see Getting Node Information.


AdminExtensions Property for Nodes

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extensions that are associated with the node. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | See Maximum String Size.
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


BuildNumber Property for Nodes

The BuildNumber property specifies the build number of Microsoft® Windows NT®/Window® 2000 installed on a node. The following table summarizes the attributes of the BuildNumber property.

Attribute | Value
Data type | DWORD
Access | Read-only
Structure | CLUSPROP_DWORD
Minimum | 0x00000000
Maximum | 0xFFFFFFF
Default | Varies

Remarks

The version of Windows NT/Window 2000 installed on a node is fully described by the following properties:

  • MajorVersion
  • MinorVersion
  • CSDVersion
  • BuildNumber

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.


CSDVersion Property for Nodes

The CSDVersion property specifies the name of the most recent service pack installed on the node (if any). The following table summarizes the attributes of the CSDVersion property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

The version of Windows NT/Window 2000 installed on a node is fully described by the following properties:

  • MajorVersion
  • MinorVersion
  • CSDVersion
  • BuildNumber

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.


Description Property for Nodes

The Description property provides comments about the node. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with the following example code:

WCHAR szDescriptionData[] = L "Node Description";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


EnableEventLogReplication Property for Nodes

The EnableEventLogReplication property controls whether a node's system, application, and security event log entries are replicated in the event logs of all other cluster nodes.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | FALSE (0). The node's event log entries are not replicated to the other cluster nodes.
Maximum | TRUE (1) The node's event log entries are replicated event logs of all other cluster nodes.
Default | TRUE

Remarks

The EnableEventLogReplication property only affects events logged to a node's system, application, and security logs.

Example Code

The property value portion of a property list entry for EnableEventLogReplication can be set with the following example code:

CLUSPROP_DWORD PropertyValue;
PropertyValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PropertyValue.cbLength = sizeof(DWORD);
PropertyValue.dw = FALSE;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


MajorVersion Property for Nodes

The MajorVersion property specifies the integer component of the Windows NT/Window 2000 version installed on the node. For example, the major version of Windows NT 4.0 is 4. The following table summarizes the attributes of the MajorVersion property.

Attribute | Value
Data type | DWORD
Access | Read-only
Structure | CLUSPROP_DWORD
Minimum | 0x00000004
Maximum | 0xFFFFFFF
Default | Varies

Remarks

The MajorVersion and MinorVersion properties represent a Windows NT/Window 2000 version number of the form MajorVersion.MinorVersion. Further version information is provided by the CSDVersion and BuildNumber properties.

Note that the MajorVersion and MinorVersion properties refer to the Windows NT/Window 2000 version installed on the node, while the NodeHighestVersion property describes the version of the Cluster service installed on the node.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.


MinorVersion Property for Nodes

The MinorVersion property specifies the decimal component of the Windows NT/Window 2000 version installed on the node. For example, the minor version of Windows NT 4.0 is 0. The following table summarizes the attributes of the MinorVersion property.

Attribute | Value
Data type | DWORD
Access | Read-only
Structure | CLUSPROP_DWORD
Minimum | 0x00000000
Maximum | 0xFFFFFFF
Default | Varies

Remarks

The MajorVersion and MinorVersion properties represent a Windows NT/Window 2000 version number of the form MajorVersion.MinorVersion. Further version information is provided by the CSDVersion and BuildNumber properties.

Note that the MajorVersion and MinorVersion properties refer to the Windows NT/Window 2000 version installed on the node, while the NodeHighestVersion property describes the version of the Cluster service installed on the node.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.


NodeHighestVersion Property for Nodes

The NodeHighestVersion property specifies the highest possible version of the Cluster service with which the node can join or communicate. The following table summarizes the attributes of the NodeHighestVersion property.

Attribute | Value
Data type | DWORD
Access | Read-only
Structure | CLUSPROP_DWORD
Minimum | 0x000100E0
Maximum | 0xFFFFFFF
Default | Varies

Remarks

The value of NodeHighestVersion is set when the Cluster service is installed or upgraded on a node. The upper 16 bits of the value store the version number, while the lower 16 bits describe the build number. For more information on how the Cluster service creates and uses version numbers, see Version Compatibility.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

NodeLowestVersion, CLUSTERVERSIONINFO, GetClusterInformation, CLUSPROP_DWORD


NodeLowestVersion Property for Nodes

The NodeLowestVersion property specifies the lowest possible version of the Cluster service with which the node can join or communicate. The following table summarizes the attributes of the NodeLowestVersion property.

Attribute | Value
Data type | DWORD
Access | Read-only
Structure | CLUSPROP_DWORD
Minimum | 0x0100E0
Maximum | 0xFFFFFF
Default | Previous release version of the Cluster service.

Remarks

The value of NodeHighestVersion is set when the Cluster service is installed or upgraded on a node. The upper 16 bits of the value store the version number, while the lower 16 bits describe the build number. For more information on how the Cluster service creates and uses version numbers, see Version Compatibility.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

NodeHighestVersion, CLUSTERVERSIONINFO, GetClusterInformation CLUSPROP_DWORD


NodeName Property for Nodes

The NodeName property provides the name of the node. The following table summarizes the attributes of the NodeName property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the NodeName property is read-only, it cannot be changed using the CLUSCTL_NODE_SET_COMMON_PROPERTIES control code.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ


Resource Common Properties

Common properties for resources are data values stored in the cluster database that describe the identity and behavior of each resource in a cluster. Common properties for resources follow.

Property | Access
AdminExtensions | Read/write
DebugPrefix | Read/write
Description | Read/write
IsAlivePollInterval | Read/write
LoadBalAnalysisInterval | Read/write
LoadBalMinMemoryUnits | Read/write
LoadBalMinProcessorUnits | Read/write
LoadBalSampleInterval | Read/write
LoadBalStartupInterval | Read/write
LooksAlivePollInterval | Read/write
Name | Read-only
PendingTimeout | Read/write
PersistentState | Read/write
RestartAction | Read/write
RestartPeriod | Read/write
RestartThreshold | Read/write
RetryPeriodOnFailure | Read/write
SeparateMonitor | Read/write
Type | Read/write

For more information on working with properties, see Getting Resource Information.


AdminExtensions Property for Resources

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extensions that are associated with the resource. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | See Maximum String Size
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


DebugPrefix Property for Resources

The DebugPrefix property specifies the path to the debugger used to debug the resource. The following table summarizes the attributes of the DebugPrefix property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

To use the DebugPrefix property, a resource must run in a separate Resource Monitor. The debugger specified by the DebugPrefix property is attached to the Resource Monitor. If the debugger is in a directory that is included in the path, DebugPrefix can be set to a relative path. Otherwise, a full path must be specified.

Setting the DebugPrefix property causes -p <process id> to be appended to the end of the debug command, where <process id> represents the process identifier for the Resource Monitor handling the resource.

For more information about debugging a resource, see Debugging a Resource DLL.

Example Code

The property value portion of a property list entry for DebugPrefix can be set with the following example code:

WCHAR szDebugPrefixData[] = L"c:\\bin\\debug.exe";
CLUSPROP_SZ_DECLARE( DebugPrefixValue, sizeof( szDebugPrefixData ) / sizeof( WCHAR ) );
DebugPrefixValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DebugPrefixValue.cbLength = sizeof( szDebugPrefixData );
lstrcpyW( DebugPrefixValue.sz, szDebugPrefixData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, DebugPrefix


Description Property for Resources

The Description property provides comments about the resource. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with the following example code:

WCHAR szDescriptionData[] = L"Word processing resource";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


IsAlivePollInterval Property for Resources

The IsAlivePollInterval property provides the recommended interval in milliseconds at which the Cluster service should poll the resource to determine if it is operational. The polling occurs when the Resource Monitor calls the resource DLL's IsAlive entry point function. The following table summarizes the attributes of the IsAlivePollInterval property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 10
Maximum | 0xFFFFFFFE
Default | 0xFFFFFFFF (-1)

Remarks

If a resource does not set the IsAlivePollInterval property or sets it to – 1, the Cluster service uses the IsAlivePollInterval property for the resource type associated with the resource.

The data value for IsAlivePollInterval cannot be zero.

Example Code

The property value portion of a property list entry for IsAlivePollInterval can be set with the following example code:

DWORD IsAlivePollIntervalData = 300;
CLUSPROP_DWORD IsAlivePollIntervalValue;
IsAlivePollIntervalValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
IsAlivePollIntervalValue.cbLength = sizeof(DWORD);
IsAlivePollIntervalValue.dw = IsAlivePollIntervalData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, IsAlive, IsAlivePollInterval


LoadBalAnalysisInterval Property for Resources

The LoadBalAnalysisInterval property is reserved for future use and is not used by Windows Clustering at this time.


LoadBalMinMemoryUnits Property for Resources

The LoadBalMinMemoryUnits property is reserved for future use and is not used by Windows Clustering at this time.


LoadBalMinProcessorUnits Property for Resources

The LoadBalMinProcessorUnits property is reserved for future use and is not used by Windows Clustering at this time.


LoadBalSampleInterval Property for Resources

The LoadBalSampleInterval property is reserved for future use and is not used by Windows Clustering at this time.


LoadBalStartupInterval Property for Resources

The LoadBalStartupInterval property is reserved for future use and is not used by Windows Clustering at this time.


LooksAlivePollInterval Property for Resources

The LooksAlivePollInterval property provides the recommended interval in milliseconds at which the Cluster service should poll the resource to determine if it appears operational. The polling occurs when the Resource Monitor calls the resource DLL's LooksAlive entry point function. The following table summarizes the attributes of the LooksAlivePollInterval property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | -1
Maximum | 0xFFFFFFFF
Default | -1

Remarks

If a resource does not set the LooksAlivePollInterval property or sets it to – 1, the Cluster service uses the LooksAlivePollInterval property for the resource type associated with the resource.

When the data value for LooksAlivePollInterval is set to zero, the Resource Monitor never calls the resource DLL's LooksAlive entry point function. Instead, the resource DLL should return an event handle from the Online call that is signaled when a resource fails. For more information, see Implementing LooksAlive and Implementing Online.

Example Code

The property value portion of a property list entry for LooksAlivePollInterval can be set with the following example code:

DWORD LooksAlivePollIntervalData = 300;
CLUSPROP_DWORD LooksAlivePollIntervalValue;
LooksAlivePollIntervalValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
LooksAlivePollIntervalValue.cbLength = sizeof(DWORD);
LooksAlivePollIntervalValue.dw = LooksAlivePollIntervalData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, LooksAlive, LooksAlivePollInterval, Online


Name Property for Resources

The Name property provides the name of the resource. The following table summarizes the attributes of the Name property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the Name property is read-only, it cannot be changed using the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code. Applications can change a resource's name only by calling SetClusterResourceName, which is one of the resource management functions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES, CLUSPROP_SZ, SetClusterResourceName


PendingTimeout Property for Resources

The PendingTimeout property sets the number of milliseconds that a Resource Monitor will wait for a resource DLL to update the status of a resource in an OnlinePending or OfflinePending state before terminating the resource. The following table summarizes the attributes of the PendingTimeout property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 180000

Remarks

The PendingTimeout property does not necessarily limit the time that a resource can spend in a ClusterOnlinePending or ClusterOfflinePending state. This property determines only how long a Resource Montor will wait for resource DLLs to report status updates with the SetResourceStatus function. As long as a resource DLL never exceeds the PendingTimeout interval between calls to SetResourceStatus, the resource DLL can keep a resource in a pending state indefinately.

If a resource DLL exceeds the PendingTimeout interval between calls to SetResourceStatus, the Resource Monitor calls the resource DLL's Terminate entry point function.

Example Code

The property value portion of a property list entry for PendingTimeout can be set with the following example code:

DWORD PendingTimeoutData = 120000;
CLUSPROP_DWORD PendingTimeoutValue;
PendingTimeoutValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PendingTimeoutValue.cbLength = sizeof(DWORD);
PendingTimeoutValue.dw = PendingTimeoutData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, Offline, Online, Terminate


PersistentState Property for Resources

The PersistentState property specifies whether the resource should be brought online or left offline when the Cluster service is started. The following table summarizes the attributes of the PersistentState property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The data value for the PersistentState property can be set to TRUE or FALSE. When PersistentState is set to TRUE, the resource is automatically brought online when the Cluster service starts. When set to FALSE, it is left offline.

When a resource is brought online, its PersistentState property is deleted from the cluster database. Therefore, PersistentState should only be set when a resource is offline.

To retrieve the current state of a resource, call the GetClusterResourceState function.

Example Code

The property value portion of a property list entry for PersistentState can be set with the following example code:

DWORD PersistentStateData = FALSE;
CLUSPROP_DWORD PersistentStateValue;
PersistentStateValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PersistentStateValue.cbLength = sizeof(DWORD);
PersistentStateValue.dw = PersistentStateData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, GetClusterResourceState


RestartAction Property for Resources

The RestartAction property describes the action to be taken by the Cluster service if the resource fails. The following table summarizes the attributes of the RestartAction property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | ClusterResourceDontRestart
Maximum | ClusterResourceRestartNotify
Default | ClusterResourceRestartNotify

Remarks

The data value for the RestartAction property can be set to the following values.

RestartAction value | Description
ClusterResourceDontRestart | Do not restart the resource after a failure.
ClusterResourceRestartNoNotify | Restart the resource after a failure. If the resource exceeds its restart threshold within its restart period, do not attempt to failover the group to another node in the cluster.
ClusterResourceRestartNotify | Restart the resource after a failure. If the resource exceeds its restart threshold within its restart period, attempt to fail over the group to another node in the cluster. This is the default setting.

Example Code

The property value portion of a property list entry for RestartAction can be set with the following example code:

DWORD RestartActionData = ClusterResourceDontRestart;
CLUSPROP_DWORD RestartActionValue;
RestartActionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RestartActionValue.cbLength = sizeof(DWORD);
RestartActionValue.dw = RestartActionData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


RestartPeriod Property for Resources

The RestartPeriod property defines an interval of time, in milliseconds, during which a specified number of restart attempts can be made on a nonresponsive resource. The RestartThreshold property specifies the allowable number of restart attempts that can occur within the interval defined by RestartPeriod. The following table summarizes the attributes of the RestartPeriod property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 900000

Remarks

When a resource fails, the Cluster service attempts to restart the resource (unless the RestartAction property is set to ClusterResourceDontRestart).

The RestartPeriod and RestartThreshold properties work together to limit restart attempts. For example, if the RestartPeriod property is set to 200 milliseconds, and the RestartThreshold property is set to two retry attempts, the Cluster service tolerates two restart failures within any 200 millisecond interval. More than two failures can occur, as long as they occur over an interval that is greater than 200 milliseconds. On the third restart failure within the 200 millisecond interval, the Cluster service considers the resource to have failed and may, depending on the RestartAction property, attempt to fail over the resource's group to another node.

After the interval defined by the RestartPeriod property is exceeded, the Cluster service resets the property to zero.

If not specified, the default value for the RestartPeriod property is 90000 milliseconds.

Example Code

The property value portion of a property list entry for RestartPeriod can be set with the following example code:

DWORD RestartPeriodData = 1800000;
CLUSPROP_DWORD RestartPeriodValue;
RestartPeriodValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RestartPeriodValue.cbLength = sizeof(DWORD);
RestartPeriodValue.dw = RestartPeriodData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, RestartAction, RestartThreshold


RestartThreshold Property for Resources

The RestartThreshold property specifies the maximum number of restart attempts that can be made on a resource within an interval defined by the RestartPeriod property before the Cluster service initiates the action specified by the RestartAction property. The following table summarizes the attributes of the RestartThreshold property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 3

Remarks

When a resource does fails, the Cluster service attempts to restart the resource (unless the RestartAction property is set to ClusterResourceDontRestart).

The RestartPeriod and RestartThreshold properties work together to limit restart attempts. For example, if the RestartPeriod property is set to 200 milliseconds, and the RestartThreshold property is set to two retry attempts, then the Cluster service tolerates two restart failures within any 200 millisecond interval. More than two failures can occur, as long as they occur over an interval that is greater than 200 milliseconds. On the third restart failure within the 200 millisecond interval, the Cluster service considers the resource to have failed and may, depending on the RestartAction property, attempt to fail over the resource's group to another node.

Example Code

The property value portion of a property list entry for RestartThreshold can be set with the following example code:

DWORD RestartThresholdData = 5;
CLUSPROP_DWORD RestartThresholdValue;
RestartThresholdValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RestartThresholdValue.cbLength = sizeof(DWORD);
RestartThresholdValue.dw = RestartThresholdData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, RestartAction, RestartPeriod, RestartThreshold


RetryPeriodOnFailure Property for Resources

The RetryPeriodOnFailure property specifies the interval of time (in milliseconds) that a resource should remain in a failed state before the Cluster service attempts to restart it. The following table summarizes the attributes of the RetryPeriodOnFailure property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | RestartPeriod value
Maximum | 0xFFFFFFFF (no retry)
Default | 0xFFFFFFFF (no retry)

Remarks

By default, if a resource fails, it remains in the failed state until an active effort is made to locate and restart the resource. The RetryPeriodOnFailure property provides a way for resources to recover from failures automatically.

When adjusting the RetryPeriodOnFailure property:

  • Note that the default value (0xFFFFFFFF) prevents the Cluster service from making a restart attempts.
  • Intervals measured in minutes (multiples of 0xEA60) are recommended.
  • Do not set the interval any lower than that specified by the RestartPeriod property.

The Cluster Service attempts to restart the resource by calling its resource DLL's Online entry point function.

Example Code

The property value portion of a property list entry for RetryPeriodOnFailure can be set with the following example code:

DWORD RetryPeriodOnFailureData = ( 5 * 0xEA60 ); // 5 minutes
CLUSPROP_DWORD RetryPeriodOnFailureValue;
RetryPeriodOnFailureValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RetryPeriodOnFailureValue.cbLength = sizeof(DWORD);
RetryPeriodOnFailureValue.dw = RetryPeriodOnFailureData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, RestartAction, RestartPeriod, RestartThreshold


SeparateMonitor Property for Resources

The SeparateMonitor property indicates whether the resource requires its own Resource Monitor. The following table summarizes the attributes of the SeparateMonitor property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The data value for the SeparateMonitor property can be set to TRUE or FALSE. To use a debugger with a resource DLL, the resource's SeparateMonitor property must be set to TRUE.

A change to the SeparateMonitor property does not take effect immediately unless the resource is offline at the time of the change. If the resource is online, the change takes effect after the resource is taken offline and brought back online.

Example Code

The property value portion of a property list entry for SeparateMonitor can be set with the following example code:

DWORD SeparateMonitorData = TRUE;
CLUSPROP_DWORD SeparateMonitorValue;
SeparateMonitorValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
SeparateMonitorValue.cbLength = sizeof(DWORD);
SeparateMonitorValue.dw = SeparateMonitorData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Type Property for Resources

The Type property specifies the display name of the resource. The following table summarizes the attributes of the Type property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

It is important to distinguish between the display name of the resource's type and the registered name of the resource's type. For more information, see Display Names.

To access the type name of a resource type, call ClusterResourceControl and pass CLUSCTL_RESOURCE_GET_RESOURCE_TYPE for the dwControlCode parameter.

The Name property for resource types also specifies a resource type display name.

Example Code

The property value portion of a property list entry for Type can be set with the following example code:

WCHAR szTypeData[] = L"Generic Application";
CLUSPROP_SZ_DECLARE( TypeValue, sizeof( szTypeData ) / sizeof( WCHAR ) );
TypeValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
TypeValue.cbLength = sizeof( szTypeData );
lstrcpyW( TypeValue.sz, szTypeData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSCTL_RESOURCE_GET_RESOURCE_TYPE, CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, ClusterResourceControl, Name


Resource Type Common Properties

Common properties for resource types are data values stored in the cluster database that describe the identity and behavior of each resource type in a cluster. Common properties for resource types follow.

Property | Access
AdminExtensions | Read/write
DebugControlFunctions | Read/write
DebugPrefix | Read/write
Description | Read/write
DllName | Read-only
IsAlivePollInterval | Read/write
LooksAlivePollInterval | Read/write
Name | Read/write

For more information on working with these properties, see Getting Resource Type Information.


AdminExtensions Property for Resource Types

The AdminExtensions property provides the class identifiers (CLSIDs) for the Cluster Administrator extension DLLs that are associated with the resource type. The following table summarizes the attributes of the AdminExtensions property.

Attribute | Value
Data type | LPCWSTR pointer or a WCHAR array
Access | Read/write
Structure | CLUSPROP_MULTI_SZ
Minimum | NULL
Maximum | CLSID
Default | NULL

Remarks

The data value for the AdminExtensions property should be set to one or more class identifiers, formatted as a sequence of null-terminated Unicode strings with the entire sequence terminated by an additional NULL.

Example Code

The property value portion of a property list entry for AdminExtensions can be set with the following example code:

WCHAR szAdmExData[] = L"{4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}\0{806EA659-39DC-4BC9-B9DE-B44B671F0236}\0{7904197E-F39E-4458-8848-A56CA675EE4D}\0";

CLUSPROP_SZ_DECLARE(
    AdmExValue,
    sizeof( szAdmExData ) / sizeof( WCHAR ) );

AdmExValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;

AdmExValue.cbLength = sizeof( szAdmExData );

CopyMemory(
    (PVOID) AdmExValue.sz,
    (PVOID) szAdmExData,
    sizeof( szAdmExData ) );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_MULTI_SZ


DebugControlFunctions Property for Resource Types

The DebugControlFunctions property indicates whether the Cluster service should create a separate Resource Monitor to use for debugging the control functions of a resource type. The following table summarizes the attributes of the DebugControlFunctions property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The data value for the DebugControlFunctions property can be TRUE or FALSE. When set to TRUE, the Cluster service starts a new Resource Monitor that can be used for control function debugging.

Example Code

The property value portion of a property list entry for DebugControlFunctions can be set with the following example code:

DWORD DebugControlFunctionsData = TRUE;
CLUSPROP_DWORD DebugControlFunctionsValue;
DebugControlFunctionsValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
DebugControlFunctionsValue.cbLength = sizeof(DWORD);
DebugControlFunctionsValue.dw = DebugControlFunctionsData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


DebugPrefix Property for Resource Types

The DebugPrefix property provides the path to a debugger that is used to debug all resources of the type that are running in the Resource Monitor for the resource type. The following table summarizes the attributes of the DebugPrefix property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

A debugger can be used only if the resource type is running with a separate Resource Monitor. If the debugger is in a directory that is included in the path, the DebugPrefix property can be set to a relative path. Otherwise, a full path must be specified.

Setting the DebugPrefix property causes -p <process id> to be appended to the end of the debug command, where <process id> represents the process identifier for the Resource Monitor handling the resource type.

Example Code

The property value portion of a property list entry for DebugPrefix can be set with the following example code:

WCHAR szDebugPrefixData[] = L"c:\\bin\\debug.exe";
CLUSPROP_SZ_DECLARE( DebugPrefixValue, sizeof( szDebugPrefixData ) / sizeof( WCHAR ) );
DebugPrefixValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DebugPrefixValue.cbLength = sizeof( szDebugPrefixData );
lstrcpyW( DebugPrefixValue.sz, szDebugPrefixData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Description Property for Resource Types

The Description property provides comments about the resource type. The following table summarizes the attributes of the Description property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Description can be set with the following example code:

WCHAR szDescriptionData[] = L"Resource type description";
CLUSPROP_SZ_DECLARE( DescriptionValue, sizeof( szDescriptionData ) / sizeof( WCHAR ) );
DescriptionValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof( szDescriptionData );
lstrcpyW( DescriptionValue.sz, szDescriptionData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


DllName Property for Resource Types

The DllName property provides the name of the dynamic-link library (DLL) for the resource type. The following table summarizes the attributes of the DllName property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read-only
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Because the DLLName property is read-only, it cannot be changed using the CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code. The DLLName property is set when the resource type is created with the CreateClusterResourceType function.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CreateClusterResourceType


IsAlivePollInterval Property for Resource Types

The IsAlivePollInterval property is the recommended interval in milliseconds at which a Resource Monitor should poll resources of the particular resource type to determine if they are operational. The polling occurs when the Resource Monitor calls a resource DLL's IsAlive entry point function. The following table summarizes the attributes of the IsAlivePollInterval property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 1
Maximum | 0xFFFFFFFF
Default | 60000

Remarks

The IsAlivePollInterval property cannot be zero. It should be set to a value that is as small as possible to cause failovers to occur in a timely manner.

The IsAlivePollInterval property for resources is also a common resource property.

Example Code

The property value portion of a property list entry for IsAlivePollInterval can be set with the following example code:

DWORD IsAlivePollIntervalData = 300;
CLUSPROP_DWORD IsAlivePollIntervalValue;
IsAlivePollIntervalValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
IsAlivePollIntervalValue.cbLength = sizeof(DWORD);
IsAlivePollIntervalValue.dw = IsAlivePollIntervalData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, IsAlive, IsAlivePollInterval


LooksAlivePollInterval Property for Resource Types

The LooksAlivePollInterval property is the recommended interval in milliseconds at which the Cluster service should poll resources of the particular resource type to determine if they appear operational. The polling occurs when the Resource Monitor calls a resource DLL's LooksAlive entry point function. The following table summarizes the attributes of the LooksAlivePollInterval property.

Attribute | Value
Data type | DWORD
Access | Read/write
Structure | CLUSPROP_DWORD
Minimum | 1
Maximum | 0xFFFFFFFF
Default | 5000

Remarks

A resource type must have a value for its LooksAlivePollInterval property; it is not optional. LooksAlivePollInterval should be set to a value that is as small as possible to cause failovers to occur in a timely manner. Zero is not a valid setting because it prevents the Resource Monitor from calling any of the resources' LooksAlive entry point functions.

The LooksAlivePollInterval property for resources is also a common resource property.

Example Code

The property value portion of a property list entry for LooksAlivePollInterval can be set with the following example code:

DWORD LooksAlivePollIntervalData = 300;
CLUSPROP_DWORD LooksAlivePollIntervalValue;
LooksAlivePollIntervalValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
LooksAlivePollIntervalValue.cbLength = sizeof(DWORD);
LooksAlivePollIntervalValue.dw = LooksAlivePollIntervalData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

LooksAlive, LooksAlivePollInterval, CLUSPROP_DWORD


Name Property for Resource Types

The Name property specifies the display name of the resource type. The display name is the name that appears to administrators in the Cluster Administrator user interface. The following table summarizes the attributes of the Name property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

It is important to distinguish between the display name of the resource type and the registered name of the resource type. For more information, see Display Names.

The Type property for resources also specifies a resource type display name.

Example Code

The property value portion of a property list entry for Name can be set with the following example code:

WCHAR szNameData[] = L"Spreadsheet App";
CLUSPROP_SZ_DECLARE( NameValue, sizeof( szNameData ) / sizeof( WCHAR ) );
NameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof( szNameData );
lstrcpyW( NameValue.sz, szNameData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, Type


Private Properties

Private properties are attributes possessed by an individual instance of a cluster object. Other instances may or may not possess the same property.

Refer to the following sections for reference information on the private properties defined by server clusters:

  • DHCP Service Private Properties
  • File Share Private Properties
  • Generic Application Private Properties
  • Generic Service Private Properties
  • IP Address Private Properties
  • Network Name Private Properties
  • Physical Disk Private Properties
  • Print Spooler Private Properties
  • WINS Service Private Properties

Developers can establish new private properties as needed to support a new resource type.

For more information on working with properties, see Getting Object Information.


DHCP Service Private Properties

A cluster's DHCP Service resource has three private properties.

Property | Status
BackupPath | Required
LogFilePath | Required
DatabasePath | Required


BackupPath Property for the DHCP Service

The BackupPath property specifies the path to the DHCP backup file. The following table summarizes the attributes of the BackupPath property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | The DCHP BackupPath property defaults to a value of the form <drive>:\<old path> where <drive> is the drive letter of the Physical Disk dependency and <old path> is the former path to the DHCP backup file. For example, if a DHCP Service resource depends on drive K: and the former path was c:\winnt\system32\dhcp, the default for this property will be K:\winnt\system32\dhcp.

Remarks

The DHCP backup path does not include a file name or a trailing backslash.

Example Code

The property value portion of a property list entry for BackupPath can be set with the following example code:

WCHAR szBackupPathData[] = L"\\\\DHCP\\BackupDirectory";
CLUSPROP_SZ_DECLARE( BackupPathValue, sizeof( szBackupPathData ) / sizeof( WCHAR ) );
BackupPathValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
BackupPathValue.cbLength = sizeof( szBackupPathData );
lstrcpyW( BackupPathValue.sz, szBackupPathData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

DatabasePath, LogFilePath, CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


LogFilePath Property for the DHCP Service

The LogFilePath property specifies the path to the DHCP log file. The following table summarizes the attributes of the LogFilePath property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | The DCHP LogFilePath property defaults to a value of the form <drive>:\<old path> where <drive> is the drive letter of the Physical Disk dependency and <old path> is the former path to the log file. For example, if a DHCP Service resource depends on drive K: and the former path was c:\winnt\system32\dhcp, the default for this property will be K:\winnt\system32\dhcp.

Remarks

The DHCP log file path does not include a file name or a trailing backslash.

Example Code

The property value portion of a property list entry for LogFilePath can be set with the following example code:

WCHAR szLogFilePathData[] = L"\\\\DHCP\\Log";
CLUSPROP_SZ_DECLARE( LogFilePathValue, sizeof( szLogFilePathData ) / sizeof( WCHAR ) );
LogFilePathValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
LogFilePathValue.cbLength = sizeof( szLogFilePathData );
lstrcpyW( LogFilePathValue.sz, szLogFilePathData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

BackupPath, DatabasePath, CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


DatabasePath Property for the DHCP Service

The DatabasePath property specifies the path to the DHCP database. The following table summarizes the attributes of the DatabasePath property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | The DCHP DatabasePath property defaults to a value of the form <drive>:\<old path> where <drive> is the drive letter of the Physical Disk dependency and <old path> is the former path to the database. For example, if a DHCP Service resource depends on drive K: and the former path was c:\winnt\system32\dhcp, the default for this property will be K:\winnt\system32\dhcp.

Remarks

The DHCP database path does not include a file name or a trailing backslash.

Example Code

The property value portion of a property list entry for DatabasePath can be set with the following example code:

WCHAR szDatabasePathData[] = L"\\\\DHCP\\DBDirectory";
CLUSPROP_SZ_DECLARE( DatabasePathValue, sizeof( szDatabasePathData ) / sizeof( WCHAR ) );
DatabasePathValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DatabasePathValue.cbLength = sizeof( szDatabasePathData );
lstrcpyW( DatabasePathValue.sz, szDatabasePathData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

BackupPath, LogFilePath, CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


File Share Private Properties

File Share resources have several private properties, some that are required and others that are optional.

Property | Status
CSCCache | Optional
HideSubDirShares | Optional
IsDfsRoot | Optional
MaxUsers | Optional
Path | Required
Remark | Optional
Security | Optional
ShareName | Required
ShareSubDirs | Optional

Cluster Administrator presents the File Share private properties on the property page associated with the Parameters tab for File Share resources.


CSCCache Property for File Shares

[This is preliminary documentation and subject to change.]

The CSCCache property controls client-side caching on a file share. The following table summarizes the attributes of the CSCCache property.

Attribute | Value
Data type | BYTE
Access | Read/write
Status | Optional
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | 48
Default | 0

The CSCCache property must be set to one of the following values:

Hex | Enum | Meaning
0x00 | CSC_CACHE_MANUAL_REINT | Automatic file-by-file reintegration is not allowed on the share.
0x10 | CSC_CACHE_AUTO_REINT | Automatic file-by-file reintegration is allowed on the share.
0x20 | CSC_CACHE_VDO | Autocaching for programs is enabled..
0x30 | CSC_CACHE_NONE | No client-side caching is allowed on the share.

Example

The property value portion of a property list entry for CSCCache can be set with the following example code:

BYTE CSCData = 0x10;
CLUSPROP_BINARY_DECLARE( CSCData, sizeof( CSCData ) );
CSCValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_BINARY;
CSCValue.cbLength = sizeof( CSCData );
memcpy( CSCValue.rgb, CSCData, sizeof( CSCData ) );

Requirements

Version: Requires Whistler.


HideSubDirShares Property for File Shares

The HideSubDirShares property determines whether the subdirectories of a file share are displayed. The following table summarizes the attributes of the HideSubDirShares property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The HideSubDirShares property can be set to one of the following values.

Value | Description
TRUE | Any subdirectories of the file share are hidden.
FALSE | File share subdirectories are not hidden.

Example Code

The property value portion of a property list entry for HideSubDirShares can be set with the following example code:

DWORD HideSubDirSharesData = FALSE;
CLUSPROP_DWORD HideSubDirSharesValue;
HideSubDirSharesValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
HideSubDirSharesValue.cbLength = sizeof(DWORD);
HideSubDirSharesValue.dw = HideSubDirSharesData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


IsDfsRoot Property for File Shares

The IsDfsRoot property identifies a file share resource as a DFS root. The following table summarizes the attributes of the IsDfsRoot property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The data value for the IsDfsRoot property can be set to one of the following values.

IsDfsRoot property data value | Description
FALSE | The file share is not a DFS root.
TRUE | The file share is a DFS root.

There can be only one DFS root per cluster. In other words, a cluster can have only one file share resource whose IsDfsRoot property is set to TRUE.

Example Code

The property value portion of a property list entry for IsDfsRoot can be set with the following example code:

DWORD IsDfsRootData = TRUE;
CLUSPROP_DWORD IsDfsRootValue;
IsDfsRootValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
IsDfsRootValue.cbLength = sizeof(DWORD);
IsDfsRootValue.dw = IsDfsRootData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


MaxUsers Property for File Shares

The MaxUsers property describes the number of simultaneous users that can access the file share. The following table summarizes the attributes of the MaxUsers property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 0xFFFFFFFF

Example Code

The property value portion of a property list entry for MaxUsers can be set with the following example code:

DWORD MaxUsersData = 10;
CLUSPROP_DWORD MaxUsersValue;
MaxUsersValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
MaxUsersValue.cbLength = sizeof(DWORD);
MaxUsersValue.dw = MaxUsersData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Path Property for File Shares

The Path property describes the path to the directory being shared. The following table summarizes the attributes of the Path property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Path can be set with the following example code:

WCHAR szPathData[] = L"g:\\ShareDirectory";
CLUSPROP_SZ_DECLARE( PathValue, sizeof( szPathData ) / sizeof( WCHAR ) );
PathValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
PathValue.cbLength = sizeof( szPathData );
lstrcpyW( PathValue.sz, szPathData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Remark Property for File Shares

The Remark property provides a description of the File Share resource. The following table summarizes the attributes of the Remark property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Optional
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Remark can be set with the following example code:

WCHAR szRemarkData[] = L"File Share Description";
CLUSPROP_SZ_DECLARE( RemarkValue, sizeof( szRemarkData ) / sizeof( WCHAR ) );
RemarkValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
RemarkValue.cbLength = sizeof( szRemarkData );
lstrcpyW( RemarkValue.sz, szRemarkData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Security Property for File Shares

The Security property stores the Windows NT 4.0 security descriptor of a file share. The following table summarizes the attributes of the Security property.

Attribute | Value
Data type | Byte array
Access | Read/write (see Remarks)
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | mem
Default | 0

Remarks

Although the property value is read/write, the underlying security descriptor can be changed only through the Access Control or Network Management APIs. To change the value of the Security property:

  • Retrieve the value of the property.
  • Assign the value to a SECURITY_DESCRIPTOR structure.
  • Pass the value to any Access Control or Network Management API function that will change the discretionary access control list (DACL) of the descriptor, such as SetSecurityDescriptorDacl or NetShareSetInfo.
  • Once the value has been modified, update the Security property.
  • Take the File Share resource offline and bring it back online to activate the new security settings.

For Windows 2000 systems, use the Security Descriptor property.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

Access Control, CLUSPROP_BINARY, Network Management, NetShareSetInfo, Security Descriptor, SetSecurityDescriptorDacl, SECURITY_DESCRIPTOR


Security Descriptor Property for File Shares

The Security Descriptor property stores the Windows 2000 security descriptor of a file share. The following table summarizes the attributes of the Security Descriptor property.

Attribute | Value
Data type | Byte array
Access | Read/write (see Remarks)
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | mem
Default | 0

Remarks

Although the property value is read/write, the underlying security descriptor can be changed only through the Access Control or Network Management APIs. To change the value of the Security Descriptor property:

  • Retrieve the value of the property.
  • Assign the value to a SECURITY_DESCRIPTOR structure.
  • Pass the value to any Access Control or Network Management API function that will change the discretionary access control list (DACL) of the descriptor, such as SetSecurityDescriptorDacl or NetShareSetInfo.
  • Once the value has been modified, update the Security Descriptor property.
  • Take the File Share resource offline and bring it back online to activate the new security settings.

Windows NT 4.0 systems use the Security property. To support rolling upgrades, you should set both the Security and SecurityDescriptor properties.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

Access Control, CLUSPROP_BINARY, Network Management, NetShareSetInfo, Security, SECURITY_DESCRIPTOR, SetSecurityDescriptorDacl


ShareName Property for File Shares

The ShareName property describes the name of the file share present on the network. The following table summarizes the attributes of the ShareName property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

All ShareName values within a given cluster must be unique.

The property value portion of a property list entry for ShareName can be set with the following example code:

WCHAR szShareNameData[] = L"Sharename";
CLUSPROP_SZ_DECLARE( ShareNameValue, sizeof( szShareNameData ) / sizeof( WCHAR ) );
ShareNameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
ShareNameValue.cbLength = sizeof( szShareNameData );
lstrcpyW( ShareNameValue.sz, szShareNameData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


ShareSubDirs Property for File Shares

The ShareSubDirs property determines whether the subdirectories of a file share are included in the share. The following table summarizes the attributes of the ShareSubDirs property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The ShareSubDirs property can be set to one of the following values.

Value | Description
TRUE | Any subdirectories of the file share are included in the share.
FALSE | No subdirectories are included in the share.

Example Code

The property value portion of a property list entry for ShareSubDirs can be set with the following example code:

DWORD ShareSubDirsData = TRUE;
CLUSPROP_DWORD ShareSubDirsValue;
ShareSubDirsValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
ShareSubDirsValue.cbLength = sizeof(DWORD);
ShareSubDirsValue.dw = ShareSubDirsData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Generic Application Private Properties

Generic Application resources have several private properties, some that are required and others that are optional. Private properties for Generic Application resources follow.

Property | Status
CommandLine | Required
CurrentDirectory | Required
InteractWithDesktop | Optional
UseNetworkName | Optional

Cluster Administrator presents the Generic Application private properties on the property page associated with the Parameters tab for Generic Application resources.


CommandLine Property for Generic Applications

The CommandLine property describes the command-line used to invoke the application when it is started. The following table summarizes the attributes of the CommandLine property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for CommandLine can be set with the following example code:

WCHAR szCommandLineData[] = L"c:\\bin\\myapp.exe";
CLUSPROP_SZ_DECLARE( CommandLineValue, sizeof( szCommandLineData ) / sizeof( WCHAR ) );
CommandLineValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
CommandLineValue.cbLength = sizeof( szCommandLineData );
lstrcpyW( CommandLineValue.sz, szCommandLineData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


CurrentDirectory Property for Generic Applications

The CurrentDirectory property describes the directory in which the application should be run. The following table summarizes the attributes of the CurrentDirectory property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

The path in the CurrentDirectory property must be an absolute path on a cluster disk. An environment variable representing a path cannot be used. A dot (.) defaults to the directory in which the Cluster service is installed.

Example Code

The property value portion of a property list entry for CurrentDirectory can be set with the following example code:

WCHAR szCurrentDirectoryData[] = L"c:\\bin";
CLUSPROP_SZ_DECLARE( CurrentDirectoryValue, sizeof( szCurrentDirectoryData ) / sizeof( WCHAR ) );
CurrentDirectoryValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
CurrentDirectoryValue.cbLength = sizeof( szCurrentDirectoryData );
lstrcpyW( CurrentDirectoryValue.sz, szCurrentDirectoryData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


InteractWithDesktop Property for Generic Applications

The InteractWithDesktop property specifies whether the generic application can provide a user interface, on the desktop, that can be used by any person logged on to the node on which the resource is online. The following table summarizes the attributes of the InteractWithDesktop property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

The data for the InteractWithDesktop property can be set to TRUE or FALSE. Setting it to TRUE allows the application to display windows on the desktop. The application has read and write access to its own windows but no access to the rest of the desktop.

Setting InteractWithDesktop to FALSE causes the application to be inaccessible from either the desktop or the toolbar.

Example Code

The property value portion of a property list entry for InteractWithDesktop can be set with the following example code:

DWORD InteractWithDesktopData = TRUE;
CLUSPROP_DWORD InteractWithDesktopValue;
InteractWithDesktopValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
InteractWithDesktopValue.cbLength = sizeof(DWORD);
InteractWithDesktopValue.dw = InteractWithDesktopData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


UseNetworkName Property for Generic Applications

The UseNetworkName property affects the outcome of a call to the Win32 function GetComputerName. The following table summarizes the attributes of the UseNetworkName property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

When an application being managed as a Generic Application resource calls GetComputerName, the UseNetworkName property determines what kind of data is returned as follows.

UseNetworkName value | Name returned by GetComputerName
TRUE | The name of the network, as stored in the Name private property of the Network Name resource on which the application depends.
FALSE | The name of the node currently running the application.

Example Code

The property value portion of a property list entry for UseNetworkName can be set with the following example code:

DWORD UseNetworkNameData = TRUE;
CLUSPROP_DWORD UseNetworkNameValue;
UseNetworkNameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
UseNetworkNameValue.cbLength = sizeof(DWORD);
UseNetworkNameValue.dw = UseNetworkNameData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, GetComputerName, Name


Generic Service Private Properties

Generic Service resources have three private properties, one that is required and two that are optional. Private properties for Generic Service resources follow.

Property | Status
StartupParameters | Optional
ServiceName | Required
UseNetworkName | Optional

Cluster Administrator presents the Generic Service private properties on the property page associated with the Parameters tab for Generic Service resources.


StartupParameters Property for Generic Services

The StartupParameters property describes the command-line to pass to the Generic Service when it is started. The following table summarizes the attributes of the StartupParameters property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Optional
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for StartupParameters can be set with the following example code:

WCHAR szStartupParametersData[] = L"PARAM1,PARAM2";
CLUSPROP_SZ_DECLARE( StartupParametersValue, sizeof( szStartupParametersData ) / sizeof( WCHAR ) );
StartupParametersValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
StartupParametersValue.cbLength = sizeof( szStartupParametersData );
lstrcpyW( StartupParametersValue.sz, szStartupParametersData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


ServiceName Property for Generic Services

The ServiceName property describes the short name of the Generic Service to run. The following table summarizes the attributes of the ServiceName property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

For more information about service names, see the Win32 function CreateService.

Example Code

The property value portion of a property list entry for ServiceName can be set with the following example code:

WCHAR szServiceNameData[] = L"MYSVC";
CLUSPROP_SZ_DECLARE( ServiceNameValue, sizeof( szServiceNameData ) / sizeof( WCHAR ) );
ServiceNameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
ServiceNameValue.cbLength = sizeof( szServiceNameData );
lstrcpyW( ServiceNameValue.sz, szServiceNameData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, CreateService


UseNetworkName Property for Generic Services

The UseNetworkName property affects the outcome of a call to the Win32 function GetComputerName. The following table summarizes the attributes of the UseNetworkName property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

When an application being managed as a Generic Service resource calls GetComputerName, the UseNetworkName property determines what kind of data is returned as follows.

UseNetworkName value | Name returned by GetComputerName
TRUE | The name of the network, as stored in the Name private property of the Network Name resource on which the application depends.
FALSE | The name of the node currently running the service.

Example Code

The property value portion of a property list entry for UseNetworkName can be set with the following example code:

DWORD UseNetworkNameData = TRUE;
CLUSPROP_DWORD UseNetworkNameValue;
UseNetworkNameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
UseNetworkNameValue.cbLength = sizeof(DWORD);
UseNetworkNameValue.dw = UseNetworkNameData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD, GetComputerName, Name


IP Address Private Properties

IP Address resources have the following private properties.

Property | Status
Address | Required
EnableNetBIOS | Optional
Network | Required
SubnetMask | Required

Cluster Administrator presents the IP Address private properties on the property page associated with the Parameters tab for IP Address resources.


Address Property for IP Addresses

The Address property provides the address for the IP Address resource. The following table summarizes the attributes of the Address property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | xxx.xxx.xxx.xxx
Default | NULL

Remarks

The data in the Address property must be formatted as xxx.xxx.xxx.xxx where xxx represents a decimal number between 0 and 255. The value 255.255.255.255 is not valid.

Example Code

The property value portion of a property list entry for Address can be set with the following example code:

WCHAR szAddressData[] = L"111.244.221.454";
CLUSPROP_SZ_DECLARE( AddressValue, sizeof( szAddressData ) / sizeof( WCHAR ) );
AddressValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AddressValue.cbLength = sizeof( szAddressData );
lstrcpyW( AddressValue.sz, szAddressData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


EnableNetBIOS Property for IP Addresses

The EnableNetBIOS property determines whether a netbios device is created and bound to the IP address. The following table summarizes the attributes of the EnableNetBIOS property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | TRUE

Remarks

The EnableNetBIOS property can be set to one of the following values.

Value | Description
TRUE | Creates a netbios device and binds it to the IP address.
FALSE | Does not create a netbios device.

Setting EnableNetBIOS to TRUE allows netbios applications to use the IP Address resource.

There is a limit of 64 netbios devices in the cluster. If you have a large number of IP addresses for non-netbios use (for example, a Web server with many virtual roots), set EnableNetBIOS to FALSE for each IP Address resource.

Example Code

The property value portion of a property list entry for EnableNetBIOS can be set with the following example code:

DWORD EnableNetBIOSData = FALSE;
CLUSPROP_DWORD EnableNetBIOSValue;
EnableNetBIOSValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
EnableNetBIOSValue.cbLength = sizeof(DWORD);
EnableNetBIOSValue.dw = EnableNetBIOSData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Network Property for IP Addresses

The Network property specifies the name of the network for which the IP address is to be created. The following table summarizes the attributes of the Network property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for Network can be set with the following example code:

WCHAR szNetworkData[] = L"NetworkX";
CLUSPROP_SZ_DECLARE( NetworkValue, sizeof( szNetworkData ) / sizeof( WCHAR ) );
NetworkValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NetworkValue.cbLength = sizeof( szNetworkData );
lstrcpyW( NetworkValue.sz, szNetworkData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


SubnetMask Property for IP Addresses

The SubnetMask property describes the subnet mask to be applied for routing for the IP address. The following table summarizes the attributes of the SubnetMask property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | xxx.xxx.xxx.xxx
Default | NULL

Remarks

The data in the SubnetMask property must be formatted as xxx.xxx.xxx.xxx where xxx represents a decimal number between 0 and 255. The value 255.255.255.255 is not valid.

Example Code

The property value portion of a property list entry for SubnetMask can be set with the following example code:

WCHAR szSubnetMaskData[] = L"255.255.0.0";
CLUSPROP_SZ_DECLARE( SubnetMaskValue, sizeof( szSubnetMaskData ) / sizeof( WCHAR ) );
SubnetMaskValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
SubnetMaskValue.cbLength = sizeof( szSubnetMaskData );
lstrcpyW( SubnetMaskValue.sz, szSubnetMaskData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


Network Name Private Properties

Network Name resources have the following private properties.

Property | Status
Name | Required
RemapPipeNames | Optional

Cluster Administrator presents this property on the property page associated with the Parameters tab for Network Name resources.


Name Property for Network Names

The Name property provides the name of the network being managed by a Network Name resource. The following table summarizes the attributes of the Name property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

Every cluster has a core Network Name resource. The core Network Name resource stores the cluster name in its Name private property and is used by the Cluster service to manage the cluster name. The Name private property of the core Network Name resource is read-only. Applications must call the SetClusterName function to change the cluster name.

The Name private property for all other Network Name resources is read/write.

Note that the Name common property for a Network Name resource provides the name of the resource, not the name of the network.

Example Code

The property value portion of a property list entry for Name can be set with the following example code:

WCHAR szNameData[] = L"Redmond Cluster";
CLUSPROP_SZ_DECLARE( NameValue, sizeof( szNameData ) / sizeof( WCHAR ) );
NameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof( szNameData );
lstrcpyW( NameValue.sz, szNameData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, SetClusterName


RemapPipeNames Property for Network Names

The RemapPipeNames property controls how named pipes are opened on the network managed by the Network Name resource. The following table summarizes the attributes of the RemapPipeNames property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE
Maximum | TRUE
Default | FALSE

Remarks

If RemapPipeNames is set to TRUE, named pipes are always opened using local pipe names. For example, when a client opens "Pipe" on "\\NodeName" the client will actually open $$\NodeName\Pipe.

By default, RemapPipeNames is set to FALSE.

Example Code

The property value portion of a property list entry for RemapPipeNames can be set with the following example code:

DWORD RemapPipeNameData = TRUE;
CLUSPROP_DWORD RemapPipeNameValue;
RemapPipeNameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RemapPipeNameValue.cbLength = sizeof(DWORD);
RemapPipeNameValue.dw = RemapPipeNameData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


Physical Disk Private Properties

Physical Disk resources have the following private properties.

Property | Status
ConditionalMount | Optional.
DiskInfo | Optional.
Drive | You must specify either a drive or a signature, but not both.
UseMountPoints | Optional.
MountVolumeInfo | Optional.
Signature | You must specify either a drive or a signature, but not both.
SkipChkDsk | Optional.
UseMountPoints | Optional.

Cluster Administrator presents these properties on the property page associated with the Parameters tab for Physical Disk resources.


ConditionalMount Property for Physical Disks

The ConditionalMount property determines whether a physical disk is mounted only if chkdsk performs successfully. The following table summarizes the attributes of the ConditionalMount property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE (always mount the disk
Maximum | TRUE (conditionally mount the disk)
Default | TRUE

Remarks

Setting ConditionalMount to FALSE causes the operating system to attempt to mount the disk regardless of chkdsk failures, if any. With ConditionalMount set to TRUE (the default), the operating system will not attempt to mount a disk if chkdsk reports errors for the disk. Note that if chkdsk does not run, it will not produce errors, and therefore the operating system will attempt to mount the disk regardless of the ConditionalMount setting. The SkipChkdsk property determines if chkdsk runs or not.

The following table summarizes the interaction between SkipChkdsk and ConditionalMount.

SkipChkdsk value | ConditionalMount value | Chkdsk runs? | Disk mounted?
FALSE | TRUE | yes | If chkdsk reports errors, no. Otherwise, yes.
FALSE | FALSE | yes | yes
TRUE | TRUE | no | yes
TRUE | FALSE | no | yes

Forcing a disk to mount despite errors can result in loss of data. Use caution when changing these properties.

Example Code

The property value portion of a property list entry for ConditionalMount can be set with the following example code:

DWORD ConditionalMountData = FALSE;
CLUSPROP_DWORD ConditionalMountValue;
ConditionalMountValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
ConditionalMountValue.cbLength = sizeof(DWORD);
ConditionalMountValue.dw = ConditionalMountData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

SkipChkdsk


DiskInfo Property for Physical Disks

The DiskInfo property provides Windows NT 4.0 disk information. The following table summarizes the attributes of the DiskInfo property.

Attribute | Value
Data type | byte array
Access | Read/write
Status | Optional
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | mem
Default | 0

Remarks

For information on interpreting the DiskInfo byte array, see the MountVolumeInfo property.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

MountVolumeInfo


Drive Property for Physical Disks

The Drive property specifies the drive letter for the Physical Disk resource. The following table summarizes the attributes of the Drive property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Remarks

The Drive property is used to create Physical Disk resources with the command-line tool Cluster.exe. Make sure that the assigned drive letter does not conflict with existing drive letters anywhere in the cluster, including each node's local drives.

Example Code

The property value portion of a property list entry for Drive can be set with the following example code:

WCHAR szDriveData[] = L"D:";
CLUSPROP_SZ_DECLARE( DriveValue, sizeof( szDriveData ) / sizeof( WCHAR ) );
DriveValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DriveValue.cbLength = sizeof( szDriveData );
lstrcpyW( DriveValue.sz, szDriveData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


MPVolGuids Property for Physical Disks

[This is preliminary documentation and subject to change.]

The MPVolGuids property is reserved for internal use by the Cluster service.

See Also

UseMountPoints


MountVolumeInfo Property for Physical Disks

The MountVolumeInfo property stores information used by Disk Management. Disk Management is a Windows 2000 graphical tool for managing disks and volumes. For more information, see Windows 2000 Help.

The following table summarizes the attributes of the MountVolumeInfo property.

Attribute | Value
Data type | byte array
Access | Read/write
Status | Optional
Structure | CLUSPROP_BINARY
Minimum | 0
Maximum | mem
Default | 0

Remarks

The MountVolumeInfo property is used to track changes made in the Disk Manager user interface on Windows 2000 systems. Windows NT systems use the DiskInfo property.

When a disk resource is brought online, the Cluster service checks the physical disk configuration, and then updates the property data. The Cluster service also updates MountVolumeInfo when the drive letter of a disk resource is changed from Disk Manager.

MountVolumeInfo data consists of a byte array organized as follows:

  • A 16-byte "header" consisting of the disk signature (first 8 bytes) and the number of volumes (second 8 bytes).
  • One or more 48-byte entries describing the following information.
Position | Data
First 16 bytes | Starting Offset
Second 16 bytes | Partition Length
Next 8 bytes | Volume Number
Next 2 bytes | Disk Type
Next 2 bytes | Drive Letter
Last 4 bytes | Padding

For example, the following MountVolumeInfoData:

D3DB5C5404000000000200000000000000004006000000000100000007460000000240060000000000FE3F060000000002000000074B00000000800C00000000000040060000000003000000074C00000040C0120000000000C03F06000000000400000007490000

would be interpreted as follows:

signature   volumes
D3DB5C54    04000000

starting offset      partition length     volume#    type  letter  pad
00020000.00000000    00004006.00000000    01000000    07    46    0000
00024006.00000000    00FE3F06.00000000    02000000    07    4B    0000
0000800C.00000000    00004006.00000000    03000000    07    4C    0000
0040C012.00000000    00C03F06.00000000    04000000    07    49    0000

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

DiskInfo


Signature Property for Physical Disks

The Signature property specifies the signature for the Physical Disk resource. The following table summarizes the attributes of the Signature property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Required
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 0

Remarks

The Signature property specifies an identifier for the disk.

Example Code

The property value portion of a property list entry for Signature can be set with the following example code:

DWORD SignatureData = 12343;
CLUSPROP_DWORD SignatureValue;
SignatureValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
SignatureValue.cbLength = sizeof(DWORD);
SignatureValue.dw = SignatureData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


SkipChkdsk Property for Physical Disks

The SkpChkdsk property determines whether the operating system runs chkdsk on a physical disk before attempting to mount the disk. The following table summarizes the attributes of the SkpChkdsk property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE (run Chkdsk)
Maximum | TRUE (skip Chkdsk)
Default | FALSE

Remarks

Setting SkpChkdsk to TRUE causes the operating system to mount the disk without running chkdsk. With SkpChkdsk set to FALSE (the default), the operating system runs chkdsk first and, if errors are found, takes action based on the ConditionalMount property. The following table summarizes the interaction between SkipChkdsk and ConditionalMount.

SkipChkdsk value | ConditionalMount value | Chkdsk runs? | Disk mounted?
FALSE | TRUE | yes | If chkdsk reports errors, no. Otherwise, yes.
FALSE | FALSE | yes | yes
TRUE | TRUE | no | yes
TRUE | FALSE | no | yes

Forcing a disk to mount despite errors can result in loss of data. Use caution when changing these properties.

Example Code

The property value portion of a property list entry for SkipChkdsk can be set with the following example code:

DWORD SkipChkdskData = FALSE;
CLUSPROP_DWORD SkipChkdskValue;
SkipChkdskValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
SkipChkdskValue.cbLength = sizeof(DWORD);
SkipChkdskValue.dw = SkipChkdskData;

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

ConditionalMount


UseMountPoints Property for Physical Disks

[This is preliminary documentation and subject to change.]

The UseMountPoints property determines whether the Physical Disk resource DLL updates the MPVolGuids property for a Physical Disk resource.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | FALSE (do not maintain a mount point list)
Maximum | TRUE (maintain a mount point list)
Default | TRUE

Remarks

When a disk's UseMountPoints property is set to FALSE, the Physical Disk resource DLL does not maintain any mount point information for it, causing the MPVolGuids property to return NULL. The disk can still be targeted as a mounted drive.

Example Code

The property value portion of a property list entry for UseMountPoints can be set with the following example code:

DWORD UseMountPointsData = FALSE;
CLUSPROP_DWORD UseMountPointsValue;
UseMountPointsValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
UseMountPointsValue.cbLength = sizeof(DWORD);
UseMountPointsValue.dw = UseMountPointsData;

Requirements

Windows NT/2000 or later: Requires Whistler.

See Also

MPVolGuids


Print Spooler Private Properties

Print Spooler resources have two private properties that follow; one is required and one is optional.

Property | Status
DefaultSpoolDirectory | Required
JobCompletionTimeout | Optional

Cluster Administrator presents these properties on the property page associated with the Parameters tab for Print Spooler resources.


DefaultSpoolDirectory Property for Print Spoolers

The DefaultSpoolDirectory property provides the name of the spooler folder for the Print Spooler resource. The following table summarizes the attributes of the DefaultSpoolDirectory property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | NULL

Example Code

The property value portion of a property list entry for DefaultSpoolDirectory can be set with the following example code:

WCHAR szDefaultSpoolDirData[] = L"c:\\ClusSpoolA";
CLUSPROP_SZ_DECLARE( DefaultSpoolDirValue, sizeof( szDefaultSpoolDirData ) / sizeof( WCHAR ) );
DefaultSpoolDirValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DefaultSpoolDirValue.cbLength = sizeof( szDefaultSpoolDirData );
lstrcpyW( DefaultSpoolDirValue.sz, szDefaultSpoolDirData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE


JobCompletionTimeout Property for Print Spoolers

The JobCompletionTimeout property indicates the number of milliseconds before a pending job is deleted from the Print Spooler resource queue. The following table summarizes the attributes of the JobCompletionTimeout property.

Attribute | Value
Data type | DWORD
Access | Read/write
Status | Optional
Structure | CLUSPROP_DWORD
Minimum | 0
Maximum | 0xFFFFFFFF
Default | 0

Example Code

The property value portion of a property list entry for JobCompletionTimeout can be set with the following example code:

DWORD JobCompletionTimeOutData = 200;
CLUSPROP_DWORD JobCompletionTimeOutValue;
JobCompletionTimeOutValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
JobCompletionTimeOutValue.cbLength = sizeof(DWORD);
JobCompletionTimeOutValue.dw = JobCompletionTimeOutData;

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_DWORD


WINS Service Private Properties

A cluster's WINS Service resource has two private properties.

Property | Status
BackupPath | Optional
DatabasePath | Optional


BackupPath Property for the WINS Service

The BackupPath property specifies the path to the WINS backup file. The following table summarizes the attributes of the BackupPath property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | %SystemRoot%\wins\backup

Remarks

The WINS backup path does not include a file name or a trailing backslash.

Example Code

The property value portion of a property list entry for BackupPath can be set with the following example code:

WCHAR szBackupPathData[] = L"\\\\WINS\\BackupDirectory";
CLUSPROP_SZ_DECLARE( BackupPathValue, sizeof( szBackupPathData ) / sizeof( WCHAR ) );
BackupPathValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
BackupPathValue.cbLength = sizeof( szBackupPathData );
lstrcpyW( BackupPathValue.sz, szBackupPathData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, BackupPath (WINS)


DatabasePath Property for the WINS Service

The DatabasePath property specifies the path to the WINS database. The following table summarizes the attributes of the DatabasePath property.

Attribute | Value
Data type | Null-terminated Unicode string
Access | Read/write
Status | Required
Structure | CLUSPROP_SZ
Minimum | NULL
Maximum | None (but see Maximum String Size).
Default | %SystemRoot%\wins\wins.mdb

Remarks

Note that the WINS database path includes the file name of the database.

Example Code

The property value portion of a property list entry for DatabasePath can be set with the following example code:

WCHAR szDatabasePathData[] = L"\\\\WINS\\DBDirectory\\wins.mdb";
CLUSPROP_SZ_DECLARE( DatabasePathValue, sizeof( szDatabasePathData ) / sizeof( WCHAR ) );
DatabasePathValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DatabasePathValue.cbLength = sizeof( szDatabasePathData );
lstrcpyW( DatabasePathValue.sz, szDatabasePathData );

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with an array of the correct size.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.

See Also

CLUSPROP_SZ, CLUSPROP_SZ_DECLARE, DatabasePath (WINS)


Cluster Structures

The Server Cluster API defines a number of structures that are categorized as follows:

  • Data structures are used to describe data values and are the building blocks of value lists.
  • Utility structures are used to build property tables, parse property lists, describe worker threads, and perform miscellaneous tasks.
  • Resource DLL structures are used to create and store resource DLL function tables and to describe the status of a resource.
  • Macros are used to initialize data structures and assist in building property lists.

'


Data Structures

Data structures describe data relating to a cluster object and are used as the building blocks of value lists. The data structures follow.

Data structure | Description
CLUS_FTSET_INFO | Reserved for future use.
CLUS_PARTITION_INFO | Used as the data value of the CLUSPROP_PARTITION_INFO structure.
CLUS_RESOURCE_CLASS_INFO | Used as the data value of the CLUSPROP_RESOURCE_CLASS_INFO structure.
CLUS_SCSI_ADDRESS | Used as the data value of the CLUSPROP_SCSI_ADDRESS structure.
CLUSPROP_BINARY | Describes binary data.
CLUSPROP_DISK_NUMBER | Describes the number of a disk.
CLUSPROP_DISK_SIGNATURE | Describes the signature of a disk.
CLUSPROP_DWORD | Describes numeric data.
CLUSPROP_FTSET_INFO | Reserved for future use.
CLUSPROP_LONG | Describes a signed long value.
CLUSPROP_MULTI_SZ | Describes multiple NULL-terminated Unicode strings.
CLUSPROP_PARTITION_INFO | Describes a partition on a storage class resource.
CLUSPROP_PROPERTY_NAME | Describes the name of a property.
CLUSPROP_PROPERTY_NAME_DECLARE | Macro used to initialize a CLUSPROP_PROPERTY_NAME structure.
CLUSPROP_REQUIRED_DEPENDENCY | Describes a resource upon which another resource must depend.
CLUSPROP_RESOURCE_CLASS | Describes a resource class value.
CLUSPROP_RESOURCE_CLASS_INFO | Describes information relevant to a resource class.
CLUSPROP_SCSI_ADDRESS | Describes an address for a SCSI device.
CLUSPROP_SECURITY_DESCRIPTOR | Reserved for future use.
CLUSPROP_SYNTAX | Describes the format and type of a data value.
CLUSPROP_SZ | Describes a NULL-terminated Unicode string.
CLUSPROP_SZ_DECLARE | Macro used to initialize a CLUSPROP_SZ structure.
CLUSPROP_ULARGE_INTEGER | Describes an unsigned, large integer.
CLUSPROP_VALUE | Describes the syntax and length of a data value.
CLUSPROP_WORD | Describes a WORD value.

Many of these data structures include other data structures as members:

  • Most structures that describe data of a particular type include a CLUSPROP_VALUE structure as the first member.
  • The CLUSPROP_VALUE structure uses a CLUSPROP_SYNTAX union as its first member.
  • Some of the data structures use other data structures to store data values. For example, the CLUSPROP_SCSI_ADDRESS structure uses a CLUS_SCSI_ADDRESS structure to hold the data for a SCSI device.

If a structure contains other structures as members, the description of the structure lists the members of the contained structures explicitly, rather than simply listing the contained structure. For example, clusapi.h defines a CLUSPROP_SZ structure as follows:

typedef struct _CLUSPROP_SZ {
  CLUSPROP_VALUE;
  WCHAR                     sz[];
} CLUSPROP_SZ, *PCLUSPROP_SZ;

To promote clarity, this documentation describes CLUSPROP_SZ as:

typedef struct _CLUSPROP_SZ {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  WCHAR                     sz[];
} CLUSPROP_SZ, *PCLUSPROP_SZ;

The following diagram shows the relationship between the structures used as headers, the structures used to describe data values, and the structures used to hold data for the data values:


CLUS_FTSET_INFO

The CLUS_FTSET_INFO structure is reserved for future use.


CLUS_PARTITION_INFO

The CLUS_PARTITION_INFO structure contains data describing a storage class resource volume and file system. It is used as the data member of a CLUSPROP_PARTITION_INFO structure and as the return value of some control code operations.

typedef struct _CLUS_PARTITION_INFO {
  DWORD           dwFlags;
  WCHAR           szDeviceName[MAX_PATH];
  WCHAR           szVolumeLabel[MAX_PATH];
  DWORD           dwSerialNumber;
  DWORD           rgdwMaximumComponentLength[2];
  DWORD           dwFileSystemFlags;
  WCHAR           szFileSystem[32];
} CLUSPROP_PARTITION_INFO, *PCLUSPROP_PARTITION_INFO;

Members

dwFlags
Value that describes the storage class resource. One of the following flags is valid.
Partition flag value | Description
CLUSPROP_PIFLAG_STICKY | The drive letter is sticky.
CLUSPROP_PIFLAG_REMOVABLE | The storage class resource is removable.
CLUSPROP_PIFLAG_USABLE | The storage class resource is formatted with a file system that is usable by the Cluster service.
CLUSPROP_PIFLAG_DEFAULT_QUORUM | The partition should be used to store quorum files if no partition is specified in the SetClusterQuorumResource function. For Physical Disk resources, the smallest NTFS partition larger than 50MB automatically receives this flag.

szDeviceName
Device name for the storage class resource, such as C:. No backslash is included.
szVolumeLabel
Volume label for the storage class resource.
dwSerialNumber
Serial number of the storage class resource volume.
rgdwMaximumComponentLength
Value of the maximum length, in characters, of a file name component supported by the specified file system. A file name component is the portion of a file name between backslashes.
dwFileSystemFlags
Value that describes the file system. One or more of the following flags are valid.
Flag | Description
FS_CASE_IS_PRESERVED | The file system preserves the case of file names when it places a name on the storage class resource.
FS_CASE_SENSITIVE | The file system supports case-sensitive file names.
FS_UNICODE_STORED_ON_DISK | The file system supports Unicode in file names as they appear on the storage class resource.
FS_PERSISTENT_ACLS | The file system preserves and enforces Access Control Lists (ACLs).

szFileSystem
Name of the file system, such as FAT or NTFS.

Remarks

A CLUS_PARTITION_INFO structure can be returned by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO and can be returned by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS.

Example

See Creating Physical Disk Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO, CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS, CLUSPROP_PARTITION_INFO, ClusterResourceControl, ClusterResourceTypeControl


CLUS_RESOURCE_CLASS_INFO

The CLUS_RESOURCE_CLASS_INFO structure contains resource class data. It is used as the data member of a CLUSPROP_RESOURCE_CLASS_INFO structure and as the return value of some control code operations.

typedef struct CLUS_RESOURCE_CLASS_INFO {
  union {
      struct {
          union {
              DWORD                   dw;
              CLUSTER_RESOURCE_CLASS  rc;
          };
          DWORD           SubClass;
      };
      ULARGE_INTEGER      li;
  };
} CLUS_RESOURCE_CLASS_INFO, *PCLUS_RESOURCE_CLASS_INFO;

Members

dw
Provides another way to access the resource class data.
rc
Resource class described with one of the following values.
Resource class value | Description
CLUS_RESCLASS_UNKNOWN | Resource class is unknown.
CLUS_RESCLASS_STORAGE | Resource is a storage device, such as a physical disk.
CLUS_RESCLASS_USER | Resource classes beginning at this value are user-defined.

SubClass
A 32-bit mask value that further describes the resource class. The following value is valid for storage class resources such as Physical Disk resources:

CLUS_RESSUBCLASS_SHARED

Setting SubClass to CLUS_RESSUBCLASS_SHARED indicates that the resource manages a shared resource such as a disk on a shared SCSI bus.

li
Resource class and subclass described as a ULARGE_INTEGER value with a low DWORD and a high DWORD.

Remarks

A resource class identifies resources of similar capability. A resource DLL that defines its own resource class should provide a unique identifier for the class that is set to a value greater than CLUS_RESCLASS_USER. CLUS_RESCLASS_USER specifies the beginning for user-defined resource class identifiers. To obtain a resource class identifier from Microsoft that is guaranteed to be unique, resource DLL writers send e-mail to resclass@microsoft.com/ with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail
  • Suggested name of the resource class
  • Purpose of the resource class

A CLUS_RESOURCE_CLASS_INFO structure is returned by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_GET_CLASS_INFO and is returned by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_GET_CLASS_INFO, CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO, CLUSPROP_RESOURCE_CLASS_INFO, ClusterResourceControl, ClusterResourceTypeControl


CLUS_SCSI_ADDRESS

The CLUS_SCSI_ADDRESS structure contains SCSI address data. It is used as the data member of a CLUSPROP_SCSI_ADDRESS structure and as the return value of some control code operations.

typedef struct _CLUS_SCSI_ADDRESS {
  union {
      struct {
          UCHAR PortNumber;
          UCHAR PathId;
          UCHAR TargetId;
          UCHAR Lun;
      };
      DWORD   dw;
  };
} CLUS_SCSI_ADDRESS, *PCLUS_SCSI_ADDRESS;

Members

PortNumber
Identifies the SCSI controller.
PathId
Identifies the bus on the SCSI controller.
TargetId
Identifies the target device on the SCSI bus.
Lun
Identifies the individual logical unit at the target device specified by TargetId.
dw
Numeric value that describes the SCSI address as a combination of the PortNumber, PathId, TargetId, and Lun values.

Remarks

A CLUS_SCSI_ADDRESS structure can also be returned by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO and can be returned by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS.

Example

See Creating Physical Disk Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO, CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS, CLUSPROP_SCSI_ADDRESS, ClusterResourceControl, ClusterResourceTypeControl


CLUSPROP_BINARY

The CLUSPROP_BINARY structure describes a binary data value. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A byte array containing the data.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_BINARY {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  BYTE                      rgb[];
} CLUSPROP_BINARY, *PCLUSPROP_BINARY;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the rgb member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the rgb member.
rgb
Array of bytes containing the data.

Remarks

Use the CLUSPROP_BINARY_DECLARE macro to initialize a CLUSPROP_BINARY structure.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_BINARY_DECLARE, CLUSPROP_VALUE


CLUSPROP_DISK_NUMBER

The CLUSPROP_DISK_NUMBER structure describes a numeric value identifying the physical drive of a disk. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A DWORD value identifying the physical drive of a disk.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_DISK_NUMBER {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  DWORD                     dw;
} CLUSPROP_DISK_NUMBER, *PCLUSPROP_DISK_NUMBER;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the dw member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the dw member.
dw
Numeric value identifying the physical drive of the disk. Valid values begin at zero.

Example

See Creating Physical Disk Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_DISK_SIGNATURE

The CLUSPROP_DISK_SIGNATURE structure describes the signature that is stored on the disk for identifying it to the operating system. The CLUSPROP_DISK_SIGNATURE structure is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A DWORD value.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_DISK_SIGNATURE {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  DWORD                     dw;
} CLUSPROP_DISK_SIGNATURE, *PCLUSPROP_DISK_SIGNATURE;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the dw member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the dw member.
dw
Numeric value that describes the disk signature.

Example

See Creating Physical Disk Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_DWORD

The CLUSPROP_DWORD structure describes numeric data. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A DWORD value.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_DWORD {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  DWORD                     dw;
} CLUSPROP_DWORD, *PCLUSPROP_DWORD;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the dw member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the dw member.
dw
Numeric value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_FTSET_INFO

The CLUSPROP_FTSET_INFO structure is reserved for future use.


CLUSPROP_LONG

The CLUSPROP_LONG structure describes signed long data. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A long value.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_LONG {
  CLUSPROP_SYNTAX          Syntax;
  long                     cbLength;
  long                     l;
} CLUSPROP_LONG, *PCLUSPROP_LONG;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the l member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the l member.
l
Signed long value.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_MULTI_SZ

The CLUSPROP_MULTI_SZ structure describes multiple NULL-terminated Unicode strings. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the partition information.
  • A string array.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_MULTI_SZ {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  WCHAR                     sz[];
} CLUSPROP_MULTI_SZ, *PCLUSPROP_MULTI_SZ;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the sz member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the sz member. Padding bytes are not included in the count.
sz
Multiple null-terminated Unicode strings with the last string followed by an additional NULL-terminating character.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_PARTITION_INFO

The CLUSPROP_PARTITION_INFO structure contains information relevant to storage class resources. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the partition information.
  • A CLUS_PARTITION_INFO structure.

An example of a storage class resource is the Physical Disk resource.

For convenience, the CLUSPROP_VALUE and CLUS_PARTITION_INFO members are listed explicitly.

typedef struct _CLUSPROP_PARTITION_INFO {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  DWORD                     dwFlags;
  WCHAR                     szDeviceName[MAX_PATH];
  WCHAR                     szVolumeLabel[MAX_PATH];
  DWORD                     dwSerialNumber;
  DWORD                     rgdwMaximumComponentLength;
  DWORD                     dwFileSystemFlags;
  WCHAR                     szFileSystem[32];
} CLUSPROP_PARTITION_INFO, *PCLUSPROP_PARTITION_INFO;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the partition information.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the CLUSPROP_PARTITION_INFO structure.
dwFlags
Member of the CLUS_PARTITION_INFO structure that describes the storage class resource. One of the following flags is valid.
Partition flag value | Description
CLUSPROP_PIFLAG_STICKY | The drive letter is sticky.
CLUSPROP_PIFLAG_REMOVABLE | The storage class resource is removable.
CLUSPROP_PIFLAG_USABLE | The storage class resource is formatted with a file system that is usable by the Cluster service.

szDeviceName
Member of the CLUS_PARTITION_INFO structure that describes the device name for the storage class resource, such as C:. No backslashes are included.
szVolumeLabel
Member of the CLUS_PARTITION_INFO structure that describes the volume label for the storage class resource.
dwSerialNumber
Member of the CLUS_PARTITION_INFO structure that describes the serial number of the storage class resource volume.
rgdwMaximumComponentLength
Member of the CLUS_PARTITION_INFO structure that describes the maximum length, in characters, of a file name component supported by the specified file system. A file name component is that portion of a file name between backslashes.
dwFileSystemFlags
Member of the CLUS_PARTITION_INFO structure that describes the file system. One or more of the following flags are valid.
Flag | Description
FS_CASE_IS_PRESERVED | The file system preserves the case of file names when it places a name on the storage class resource.
FS_CASE_SENSITIVE | The file system supports case-sensitive file names.
FS_UNICODE_STORED_ON_DISK | The file system supports Unicode in file names as they appear on storage class resource.
FS_PERSISTENT_ACLS | The file system preserves and enforces access control lists (ACLs).

szFileSystem
Member of the CLUS_PARTITION_INFO structure that describes the name of the file system, such as FAT, HPFS, or NTFS.

Example

See Creating Physical Disk Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUS_PARTITION_INFO, CLUSPROP_VALUE.


CLUSPROP_PROPERTY_NAME

The CLUSPROP_PROPERTY_NAME structure describes the name of a property. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the property name.
  • A null-terminated Unicode string.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_PROPERTY_NAME {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  WCHAR                     sz[];
} CLUSPROP_PROPERTY_NAME, *PCLUSPROP_PROPERTY_NAME;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the property name.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the property name string. Padding bytes are not included in the count.
sz
Array of characters that contains the property name string.

Remarks

Use the CLUSPROP_PROPERTY_NAME_DECLARE macro to initialize a CLUSPROP_PROPERTY_NAME structure.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_PROPERTY_NAME_DECLARE, CLUSPROP_VALUE


CLUSPROP_REQUIRED_DEPENDENCY

The CLUSPROP_REQUIRED_DEPENDENCY union describes a resource that is a required dependency of another resource. This union is used as a value in the value list returned from a CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES or CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES control code operation.

typedef union _CLUSPROP_REQUIRED_DEPENDENCY {
  CLUSPROP_VALUE             Value;
  CLUSPROP_RESOURCE_CLASS    ResClass;
  CLUSPROP_SZ                ResTypeName;
} CLUSPROP_REQUIRED_DEPENDENCY, *PCLUSPROP_REQUIRED_DEPENDENCY;

Members

Value
CLUSPROP_VALUE structure describing whether the data in the structure is a resource class or resource type name.
ResClass
Resource class upon which a resource must depend. One of the following values are valid.
Resource class value | Description
CLUS_RESCLASS_UNKNOWN | A resource has a dependency on a resource of an unknown class.
CLUS_RESCLASS_STORAGE | A resource has a dependency on a storage device, such as a Physical Disk resource.
CLUS_RESCLASS_USER | A resource has a dependency on a resource belonging to a user-defined class. CLUS_RESCLASS_USER specifies the beginning of the range for user-defined resource classes.

ResTypeName
Resource type upon which a resource must depend, such as IP Address.

Remarks

The CLUSPROP_REQUIRED_DEPENDENCY structure describes mandatory dependencies. For example, a Print Spooler resource has required dependencies on a storage device and a Network Name resource. The first type of dependency is described using a resource class; storage device resources belong to the CLUS_RESCLASS_STORAGE resource class. The second type of dependency is described using a resource type name, such as Network Name. Therefore, when an application calls ClusterResourceControl with the CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code, a value list is returned with two entries: a CLUSPROP_REQUIRED_DEPENDENCY structure with the ResClass member set to CLUS_RESCLASS_STORAGE, and a second CLUSPROP_REQUIRED_DEPENDENCY structure with the ResTypeName member set to Network Name.

Example

See Creating Value Lists.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES, CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES, CLUSPROP_VALUE, ClusterResourceControl


CLUSPROP_RESOURCE_CLASS

The CLUSPROP_RESOURCE_CLASS structure describes a resource class. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the resource class value.
  • A CLUSPROP_RESOURCE_CLASS value describing the resource class. CLUSPROP_RESOURCE_CLASS is an enumeration defined in clusapi.h.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_RESOURCE_CLASS {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  CLUSTER_RESOURCE_CLASS    rc;
} CLUSPROP_RESOURCE_CLASS, *PCLUSPROP_RESOURCE_CLASS;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the rc member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the rc member. Padding bytes are not included in the count.
rc
Resource class described with one of these values.
Resource class value | Description
CLUS_RESCLASS_UNKNOWN | Resource class is unknown.
CLUS_RESCLASS_STORAGE | Resource is a storage device, such as a Physical Disk resource.
CLUS_RESCLASS_USER | Resource belongs to a user-defined class. CLUS_RESCLASS_USER specifies the beginning of the range for user-defined resource classes.

Remarks

A resource class identifies resources of similar capability. A resource DLL that defines its own resource class should provide a unique identifier for the class that is set to a value greater than CLUS_RESCLASS_USER. CLUS_RESCLASS_USER specifies the beginning for user-defined resource class identifiers. To obtain a resource class identifier from Microsoft that is guaranteed to be unique, resource DLL writers send e-mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_RESOURCE_CLASS_INFO

The CLUSPROP_RESOURCE_CLASS_INFO structure describes information relating to a resource class. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure indicating the format and type of the resource class information.
  • A CLUS_RESOURCE_CLASS_INFO structure describing the resource class and subclass of the resource.

For convenience, the CLUSPROP_VALUE and CLUS_RESOURCE_CLASS_INFO members are listed explicitly.

typedef struct _CLUSPROP_RESOURCE_CLASS_INFO {
  CLUSPROP_SYNTAX                     Syntax;
  DWORD                               cbLength;
  union {
      struct {
          union {
              DWORD                   dw;
              CLUSTER_RESOURCE_CLASS  rc;
          };
          DWORD                       SubClass;
      };
      ULARGE_INTEGER                  li;
  };
} CLUSPROP_RESOURCE_CLASS_INFO, *PCLUSPROP_RESOURCE_CLASS_INFO;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the data in the CLUS_RESOURCE_CLASS_INFO structure.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the CLUS_RESOURCE_CLASS_INFO structure. Padding bytes are not included in the count.
dw
Member of the CLUS_RESOURCE_CLASS_INFO structure that describes the resource class as a numeric value.
rc
Member of the CLUS_RESOURCE_CLASS_INFO structure that describes the resource class with one of the following values.
Resource class value | Description
CLUS_RESCLASS_UNKNOWN | Resource class is unknown.
CLUS_RESCLASS_STORAGE | Resource is a storage device, such as a Physical Disk resource.
CLUS_RESCLASS_USER | Resource belongs to a user-defined class. CLUS_RESCLASS_USER specifies the beginning of the range for user-defined resource classes.

SubClass
Member of the CLUS_RESOURCE_CLASS_INFO structure that further describes the resource class. The following value is valid for Physical Disk resources:

CLUS_RESSUBCLASS_SHARED

Setting SubClass to CLUS_RESSUBCLASS_SHARED indicates that the resource manages a shared resource such as a disk on a shared SCSI bus.

li
Member of the CLUS_RESOURCE_CLASS_INFO structure that describes the resource class and subclass as a ULARGE_INTEGER value with a low DWORD and a high DWORD.

Remarks

A resource class identifies resources of similar capability. A resource DLL that defines its own resource class should provide a unique identifier for the class that is set to a value greater than CLUS_RESCLASS_USER. CLUS_RESCLASS_USER specifies the beginning for user-defined resource class identifiers. To obtain a resource class identifier from Microsoft that is guaranteed to be unique, resource DLL writers send mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUS_RESOURCE_CLASS_INFO, CLUSPROP_VALUE


CLUSPROP_SCSI_ADDRESS

The CLUSPROP_SCSI_ADDRESS structure describes an address for a SCSI device. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure indicating the format and type of the resource class information.
  • A CLUS_SCSI_ADDRESS structure.

For convenience, the CLUSPROP_VALUE and CLUS_SCSI_ADDRESS members are listed explicitly.

typedef struct _CLUSPROP_SCSI_ADDRESS {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  union {
      struct {
          UCHAR     PortNumber;
          UCHAR     PathId;
          UCHAR     TargetId;
          UCHAR     Lun;
      };
      DWORD         dw;
  };
} CLUSPROP_SCSI_ADDRESS, *PCLUSPROP_SCSI_ADDRESS;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the data in the CLUS_SCSI_ADDRESS structure.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the CLUS_SCSI_ADDRESS structure. Padding bytes are not included in the count.
PortNumber
Member of the CLUS_SCSI_ADDRESS structure that identifies the SCSI controller.
PathId
Member of the CLUS_SCSI_ADDRESS structure that identifies the bus on the SCSI controller.
TargetId
Member of the CLUS_SCSI_ADDRESS structure that identifies the target device on SCSI bus.
Lun
Member of the CLUS_SCSI_ADDRESS structure that identifies the individual logical unit at the target device specified by TargetId.
dw
Member of the CLUS_SCSI_ADDRESS structure that describes the SCSI address.

Example

See Creating Physical Disk Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUS_SCSI_ADDRESS, CLUSPROP_VALUE


CLUSPROP_SECURITY_DESCRIPTOR

The CLUSPROP_SECURITY_DESCRIPTOR structure is reserved for future use.


CLUSPROP_SYNTAX

The CLUSPROP_SYNTAX union describes the format and type of a data value. It is used as the Syntax member of the CLUSPROP_VALUE structure.

typedef union _CLUSPROP_SYNTAX {
  DWORD dw;
  struct {
      WORD wFormat;
      WORD wType;
  };
} CLUSPROP_SYNTAX, *PCLUSPROP_SYNTAX;

Members

dw
Numeric value describing the combined format and type of the data value. Clusapi.h defines the following values.
dw value | Description
CLUSPROP_SYNTAX_LIST_VALUE_BINARY | Describes a binary value.
CLUSPROP_SYNTAX_LIST_VALUE_DWORD | Describes a DWORD value.
CLUSPROP_SYNTAX_LIST_VALUE_EXPAND_SZ | Describes a NULL-terminated Unicode string value with unexpanded references to environment variables.
CLUSPROP_SYNTAX_LIST_VALUE_EXPANDED_SZ | Describes a NULL-terminated Unicode string value with expanded references to environment variables.
CLUSPROP_SYNTAX_LIST_VALUE_LONG | Describes a signed long value.
CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ | Describes an array of NULL-terminated Unicode string values.
CLUSPROP_SYNTAX_LIST_VALUE_SZ | Describes a NULL-terminated Unicode string value.
CLUSPROP_SYNTAX_DISK_NUMBER | Describes a disk number value represented by a CLUSPROP_DISK_NUMBER structure.
CLUSPROP_SYNTAX_DISK_SIGNATURE | Describes a disk signature value represented by a CLUSPROP_DISK_SIGNATURE structure.
CLUSPROP_SYNTAX_ENDMARK | Marks the end of a value list.
CLUSPROP_SYNTAX_FTSET_INFO | Reserved for future use.
CLUSPROP_SYNTAX_NAME | Describes a property name, such as the Name property for resources and the NodeName property for nodes. A property name is represented by a CLUSPROP_PROPERTY_NAME structure.
CLUSPROP_SYNTAX_PARTITION_INFO | Describes a collection of information about a Physical Disk resource, such as its device name and volume label. Partition information is represented by a CLUSPROP_PARTITION_INFO structure.
CLUSPROP_SYNTAX_RESCLASS | Describes a resource class value. A resource class value is represented by a CLUSPROP_RESOURCE_CLASS structure.
CLUSPROP_SYNTAX_SCSI_ADDRESS | Describes the address for an IP Address resource. IP Address resources store this address in their Address private property. A SCSI address value is represented by a CLUSPROP_SCSI_ADDRESS structure.

wFormat
Numeric value describing only the format of the data value. Clusapi.h defines the following values.
Format value | Description
CLUSPROP_FORMAT_BINARY | Data is a binary value.
CLUSPROP_FORMAT_DWORD | Data is a DWORD value.
CLUSPROP_FORMAT_
EXPAND_SZ 		Data is a null-terminated Unicode string with unexpanded references to environment variables.
CLUSPROP_FORMAT_
EXPANDED_SZ 		Data is a null-terminated Unicode string with expanded references to environment variables.
CLUSPROP_FORMAT_LONG | Data is an signed long value.
CLUSPROP_FORMAT_MULTI_SZ | Data is an array of null-terminated Unicode strings.
CLUSPROP_FORMAT_SZ | Data is a null-terminated Unicode string.
CLUSPROP_FORMAT_
ULARGE_INTEGER 		Data is an unsigned large integer.
CLUSPROP_FORMAT_UNKNOWN | Data is in an unknown format.
CLUSPROP_FORMAT_USER | Data is in a user-defined format.
CLUSPROP_FORMAT_WORD | Data is a WORD value.

wType
Numeric value that describes only the type of the data value. Clusapi.h defines the following values.
wType value | Description
CLUSPROP_TYPE_DISK_NUMBER | Describes the number value of a disk resource. A disk number value is represented by a CLUSPROP_DISK_NUMBER structure.
CLUSPROP_TYPE_ENDMARK | Designates the data value as the last entry in a property or value list.
CLUSPROP_SYNTAX_FTSET_INFO | Reserved for future use.
CLUSPROP_TYPE_LIST_VALUE | Describes a data value in a property list. For example, in the property list passed to a control code function for a property validation operation, CLUSPROP_TYPE_LIST_VALUE is the required type to be included with each property value.
CLUSPROP_TYPE_NAME | Describes a data value used as a name, such as a property name. A name value is represented by a CLUSPROP_PROPERTY_NAME structure.
CLUSPROP_TYPE_PARTITION_INFO | Describes a collection of information about a disk resource, such as its device name and volume label. Partition data is represented by a CLUSPROP_PARTITION_INFO structure.
CLUSPROP_TYPE_RESCLASS Describes resource class information. A resource class value is described with a CLUSPROP_RESOURCE_CLASS structure. Resource classes are returned when an application calls ClusterResourceControl or ClusterResourceTypeControl with one of the following control codes:

CLUSCTL_RESOURCE_GET_CLASS_INFO

CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO

CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES

CLUSPROP_TYPE_SCSI_ADDRESS | Describes an Address property for an IP Address resource. A SCSI address value is represented by a CLUSPROP_SCSI_ADDRESS structure.
CLUSPROP_TYPE_SIGNATURE | Describes a Signature property for a disk resource. A signature value is represented by a CLUSPROP_DISK_SIGNATURE structure.
CLUSPROP_TYPE_USER | Describes the beginning of the range for users to define their own types. Associate this type with user-defined private properties.

Remarks

To parse data that is returned from a control code function, use the wFormat member of this structure if the wType member defines a type that the application cannot understand.

Example

See Creating Physical Disk Resources and Building with CLUSPROP_BUFFER_HELPER.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

Address, CLUSCTL_RESOURCE_GET_CLASS_INFO, CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO, CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES, CLUSPROP_DISK_NUMBER, CLUSPROP_DISK_SIGNATURE, CLUSPROP_PARTITION_INFO, CLUSPROP_PROPERTY_NAME, CLUSPROP_RESOURCE_CLASS, CLUSPROP_SCSI_ADDRESS, CLUSPROP_VALUE, ClusterResourceControl, ClusterResourceTypeControl, Name (property for resources and the) NodeName


CLUSPROP_SZ

The CLUSPROP_SZ structure describes a null-terminated Unicode string. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure indicating the format and type of string.
  • A null-terminated Unicode string.

For convenience, the CLUSPROP_VALUE members are listed explicitly.

typedef struct _CLUSPROP_SZ {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  WCHAR                     sz[];
} CLUSPROP_SZ, *PCLUSPROP_SZ;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the string.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the sz member. Padding bytes are not included in the count.
sz
Array of Unicode characters ending with a NULL terminator.

Remarks

Use the CLUSPROP_SZ_DECLARE macro to initialize a CLUSPROP_SZ structure.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_SZ_DECLARE, CLUSPROP_VALUE


CLUSPROP_ULARGE_INTEGER

The CLUSPROP_ULARGE_INTEGER structure describes an unsigned large integer. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure indicating the format and type of the integer value.
  • An unsigned large integer value.

For convenience, the CLUSPROP_VALUE members are listed explicitly.

typedef struct _CLUSPROP_ULARGE_INTEGER {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
  ULARGE_INTEGER            li;
} CLUSPROP_ULARGE_INTEGER, *PCLUSPROP_ULARGE_INTEGER;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the unsigned large integer.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the li member.
li
Unsigned large integer value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


CLUSPROP_VALUE

The CLUSPROP_VALUE structure describes the syntax and length of a data value used in a value list. The CLUSPROP_VALUE structure is used as a generic header in all of the structures that describe data of a particular type, such as CLUSPROP_BINARY and CLUSPROP_SZ.

typedef struct _CLUSPROP_VALUE {
  CLUSPROP_SYNTAX           Syntax;
  DWORD                     cbLength;
} CLUSPROP_VALUE, *PCLUSPROP_VALUE;

Members

Syntax
CLUSPROP_SYNTAX union that describes a value.
cbLength
Count of bytes in the data that follows this CLUSPROP_VALUE structure.

Remarks

The CLUSPROP_VALUE structure is used to describe the format, type, and length of a data value in the following structures:

  • CLUSPROP_BINARY
  • CLUSPROP_DISK_NUMBER
  • CLUSPROP_DISK_SIGNATURE
  • CLUSPROP_DWORD
  • CLUSPROP_MULTI_SZ
  • CLUSPROP_PARTITION_INFO
  • CLUSPROP_PROPERTY_NAME
  • CLUSPROP_REQUIRED_DEPENDENCY
  • CLUSPROP_RESOURCE_CLASS
  • CLUSPROP_RESOURCE_CLASS_INFO
  • CLUSPROP_SCSI_ADDRESS
  • CLUSPROP_SZ
  • CLUSPROP_ULARGE_INTEGER
  • CLUSPROP_WORD

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_BINARY, CLUSPROP_SYNTAX, CLUSPROP_SZ


CLUSPROP_WORD

[This is preliminary documentation and subject to change.]

The CLUSPROP_WORD structure describes numeric data. It is used as an entry in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A WORD value.

For convenience, the CLUSPROP_VALUE members are listed explicitly:

typedef struct _CLUSPROP_WORD {
  CLUSPROP_SYNTAX  Syntax;
  DWORD  cbLength;
  WORD  w;
} CLUSPROP_WORD, *PCLUSPROP_WORD;

Members

Syntax
Member of the CLUSPROP_VALUE structure describing the format and type of the w member.
cbLength
Member of the CLUSPROP_VALUE structure indicating the count of bytes in the w member.
w
Numeric value.

Requirements

Version: Requires Whistler.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_VALUE


Utility Structures

The utility structures perform a variety of tasks. Refer to the individual descriptions in the following table:

Utility structure | Description
CLUS_STARTING_PARAMS | Describes the circumstances under which the Cluster service is starting on a node.
CLUS_WORKER | Describes information about a worker thread.
CLUSPROP_BUFFER_HELPER | Used to build or parse a property or value list.
CLUSPROP_LIST | Used to access the beginning of a property list.
CLUSTERVERSIONINFO | Describes version information about the Cluster service on a node running Windows 2000 or later.
CLUSTERVERSIONINFO_NT4 | Describes version information about the Cluster service on a node running Windows NT 4.x.
RESUTIL_PROPERTY_ITEM | Contains information about a property and an offset to the property's data.


CLUS_STARTING_PARAMS

The CLUS_STARTING_PARAMS structure indicates whether a node's attempt to start the Cluster service represents an attempt to form or join a cluster, and whether the node has attempted to start this version of the Cluster service before. Resource DLLs receive the CLUS_STARTING_PARAMS structure with the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1 and CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 control codes.

typedef struct CLUS_STARTING_PARAMS {
  DWORD   dwSize;
  BOOL    bForm;
  BOOL    bFirst;
} CLUS_STARTING_PARAMS, * PCLUS_STARTING_PARAMS;

Members

dwSize
Byte size of the structure.
bForm
Indicates whether this particular start of the Cluster service represents a form or a join operation.
Value | Implications
TRUE | The node starting the Cluster service is attempting to form a cluster. No other nodes are currently active.
FALSE | The node starting the Cluster service is attempting to join an existing cluster. At least one other node is currently active.

bFirst
Indicates whether this version of the Cluster service has ever started on the node.
Value | Implications
TRUE | The node is starting a version of the Cluster service for the first time.
FALSE | The node has started this version of the Cluster service previously.

Remarks

The CLUS_STARTING_PARAMS structure allows resource DLLs to respond to the CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1 and CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2 control codes based on the circumstances of the start. For example, a DLL might perform special initialization steps when the cluster forms, and perform another set of operations in response to joins.

Example

The following example illustrates an abbreviated implementation of ResourceTypeControl. For more information, see Implementing ResourceTypeControl.

const LPWSTR g_MY_RESOURCE_TYPE_NAME[] =
{
    "MyType_0",
    "MyType_1",
    "MyType_2",
    "MyType_3"
};

DWORD
WINAPI
MyDllResourceTypeControl(
    IN LPCWSTR ResourceTypeName,
    IN DWORD ControlCode,
    IN PVOID InBuffer,
    IN DWORD InBufferSize,
    OUT PVOID OutBuffer,
    IN DWORD OutBufferSize,
    OUT LPDWORD BytesReturned
)
{
    DWORD status;
    PCLUS_STARTING_PARAMS pStart;

    switch ( ControlCode )
    {
        case CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1:

            if( lstrcmpi( ResourceTypeName, g_MY_RESOURCE_TYPE_NAME[2] ) == 0 )
            {
                pStart = (PCLUS_STARTING_PARAMS) InBuffer;
                if( ( pStart->bForm == TRUE ) &&
                    ( pStart->bFirst == FALSE ) )
                {
                //  Hypothetical initialization code for resource type "MyType_2"
                //  Fires only when the cluster forms, but not for first-time launches of the Cluster service.
                }
            }
            else
            {
                status = ERROR_INVALID_FUNCTION;
            }

            break;

        case CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2:

            pStart = (PCLUS_STARTING_PARAMS) InBuffer;
            if( pStart->bFirst == TRUE )
            {
            //  Hypothetical verification code for all resource types supported by the DLL
            //  Fires for first-time launches of the Cluster service
            }
            else
            {
                status = ERROR_INVALID_FUNCTION;
            }

            break;

    //  case ( Other control codes )....
    //      ...
    //      break;

        default:
            status = ERROR_INVALID_FUNCTION;
            break;

    }
    // end switch

    return( status );

}
// MyDllResourceTypeControl

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_RESOURCE_TYPE_STARTING_PHASE1, CLUSCTL_RESOURCE_TYPE_STARTING_PHASE2


CLUS_WORKER

The CLUS_WORKER structure contains information about a worker thread.

typedef struct _CLUS_WORKER {
  HANDLE hThread;
  BOOL Terminate;
} CLUS_WORKER, *PCLUS_WORKER;

Members

hThread
Handle to the worker thread.
Terminate
Flag that indicates whether the thread is to be terminated.

Remarks

A worker thread is a thread that is created to offload work from a main thread so that the main thread is not blocked.

A CLUS_WORKER structure is returned as output from ClusWorkerCreate and passed as input to ClusWorkerCheckTerminate and ClusWorkerTerminate. There is never any reason for an application or resource DLL to alter the members of a CLUS_WORKER structure. This structure should always be treated as read-only.

The Terminate member prevents a potential race condition that can occur if multiple threads call the ClusWorkerTerminate function to end the same worker thread. The first call sets Terminate to TRUE. Subsequent calls return immediately after checking the value of Terminate without waiting for the thread to exit.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

ClusWorkerCheckTerminate, ClusWorkerCreate, ClusWorkerTerminate


CLUSPROP_BUFFER_HELPER

The CLUSPROP_BUFFER_HELPER union is used to build or parse a property list or a value list.

typedef union _CLUSPROP_BUFFER_HELPER {
  BYTE *                          pb;
  WORD *                          pw;
  DWORD *                         pdw;
  LONG *                          pl;
  LPWSTR                          psz;
  PCLUSPROP_LIST                  pList;
  PCLUSPROP_SYNTAX                pSyntax;
  PCLUSPROP_PROPERTY_NAME         pName;
  PCLUSPROP_VALUE                 pValue;
  PCLUSPROP_BINARY                pBinaryValue;
  PCLUSPROP_DWORD                 pDwordValue;
  PCLUSPROP_LONG                  pLongValue;
  PCLUSPROP_ULARGE_INTEGER        pULargeIntegerValue;
  PCLUSPROP_SZ                    pStringValue;
  PCLUSPROP_MULTI_SZ              pMultiSzValue;
  PCLUSPROP_RESOURCE_CLASS        pResourceClassValue;
  PCLUSPROP_RESOURCE_CLASS_INFO   pResourceClassInfoValue;
  PCLUSPROP_DISK_SIGNATURE        pDiskSignatureValue;
  PCLUSPROP_SCSI_ADDRESS          pScsiAddressValue;
  PCLUSPROP_DISK_NUMBER           pDiskNumberValue;
  PCLUSPROP_PARTITION_INFO        pPartitionInfoValue;
  PCLUSPROP_REQUIRED_DEPENDENCY   pRequiredDependencyValue;
} CLUSPROP_BUFFER_HELPER, *PCLUSPROP_BUFFER_HELPER;

Members

pb
Pointer to a buffer containing an array of bytes.
pw
Pointer to a buffer containing an array of WORD values.
pdw
Pointer to a buffer containing an array of DWORD values.
pl
Pointer to a buffer containing an array of signed long values.
psz
Pointer to a buffer containing a null-terminated Unicode string value.
pList
Pointer to a CLUSPROP_LIST structure describing the beginning of a property list.
pSyntax
Pointer to a CLUSPROP_SYNTAX structure describing the format and type of a value.
pName
Pointer to a CLUSPROP_PROPERTY_NAME structure containing a property name value.
pValue
Pointer to a CLUSPROP_VALUE structure describing the format, type, and length of a data value.
pBinaryValue
Pointer to a CLUSPROP_BINARY structure containing a binary data value.
pDwordValue
Pointer to a CLUSPROP_DWORD structure containing a numeric data value.
pLongValue
Pointer to a CLUSPROP_LONG structure containing a signed long value.
pULargeIntegerValue
Pointer to a CLUSPROP_ULARGE_INTEGER structure containing an unsigned large integer value.
pStringValue
Pointer to a CLUSPROP_SZ structure containing a NULL-terminated Unicode string value.
pMultiSzValue
Pointer to a CLUSPROP_MULTI_SZ structure containing multiple null-terminated Unicode string values.
pResourceClassValue
Pointer to a CLUSPROP_RESOURCE_CLASS structure containing a resource class value.
pResourceClassInfoValue
Pointer to a CLUSPROP_RESOURCE_CLASS_INFO structure containing a resource class information value.
pDiskSignatureValue
Pointer to a CLUSPROP_DISK_SIGNATURE structure containing a disk signature value.
pScsiAddressValue
Pointer to a CLUSPROP_SCSI_ADDRESS structure containing an SCSI address value.
pDiskNumberValue
Pointer to a CLUSPROP_DISK_NUMBER structure containing a disk number value.
pPartitionInfoValue
Pointer to a CLUSPROP_PARTITION_INFO structure containing a partition information value.
pRequiredDependencyValue
Pointer to a CLUSPROP_REQUIRED_DEPENDENCY structure containing a resource dependency value.
pWordValue
Pointer to a CLUSPROP_WORD structure containing a numeric value.

Remarks

The CLUSPROP_BUFFER_HELPER structure is useful in working with property and value lists. Applications can use a generic CLUSPROP_BUFFER_HELPER pointer to advance by offsets through the entries of a property list or value list, retrieving or setting values without having to cast to the appropriate data type.

An alternate structure, RESUTIL_PROPERTY_ITEM, can also be used to work with multiple properties.

Example

In addition to the following example, see Creating Property Lists, Parsing Property Lists, Creating Value Lists, and Parsing a Value List.

//////////////////////////////////////////////////////////////////////
//
//    HOW TO USE CLUSPROP_BUFFER HELPER
//
//    (1) Position cbh to the next read or write location.
//    (2) Read or write data using an appropriate pointer.
//    (3) Check position within buffer.
//
//    Repeat (1)(2)(3)
//
//////////////////////////////////////////////////////////////////////
void
ClusDocEx_UsingCBH(
    void
)
{
    LPVOID lp = LocalAlloc( LPTR, 100 ); // It is important for cbh
                                         // to know the allocated
                                         // size.
    CLUSPROP_BUFFER_HELPER cbh;

// ( 1 )
//
//    Position cbh.  The pb member is convenient for
//    targeting single bytes.
//

      cbh.pb = (LPBYTE) lp;

//
//    The pb member points to the first byte of lp.
//
//    lp -----> 0 0 0 0 0 0 0 0 0 0 0 ... 0
//
//    cbh.pb-->|-|
//
//
//    Note what happens when different cbh pointer types are used:
//
//                   lp -----> 0 0 0 0 0 0 0 0 0 0 0 0 ... 0
//
//    cbh.pdw              -->|-------|
//    cbh.psz              -->|-|
//    cbh.pValue           -->|---------------|
//    cbh.pValue->Syntax.dw-->|-------|
//    cbh.pValue->cbLength         -->|-------|
//
//
//    The configuration of bytes that will be affected by a read
//    or write operation depends on the type of pointer used.
//

// ( 2 )
//
//    Read or write data to the present location.  Note how the
//    structure pointers let you "reach over" intervening members.
//

      cbh.pValue->Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;

      cbh.pValue->cbLength = sizeof( DWORD );

      cbh.pDwordValue->dw  = 0x0000EEEEL;

//
//    Result:   lp ----->| syntax | length |  value  | 0 0 0 0 ... 0
//

// ( 3 )
//
//    Check your remaining space.  Be sure you have room to advance
//    cbh past the current data and perform a read operation on the
//    next value.
//

      DWORD cbPosition = cbh.pb - (LPBYTE) lp;

      DWORD cbAdvance = ListEntrySize( sizeof( DWORD ) );  // ListEntrySize can be found in "ClusDocEx.h"

      if( ( cbPosition + cbAdvance + sizeof( DWORD ) ) > 100 )
      {
          // handle the fact that there's more data than the reported size of the buffer
      }

//
//    Repeat ( 1 ), ( 2 ), and ( 3 ) for the next value:
//

      // Position cbh

      cbh.pb += cbAdvance;

      // Write next entry

      cbh.pStringValue->Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;

      cbh.pStringValue->cbLength = ( lstrlenW( L"String Value" ) + 1 ) * sizeof( WCHAR );

      lstrcpyW( cbh.pStringValue.psz, L"String Value" )

      // Check space

      cbPosition = cbh.pb - (LPBYTE) lp;

      cbAdvance = ListEntrySize( cbh.pStringValue->cbLength );

      if( ( cbPosition + cbAdvance + sizeof( DWORD ) ) > 100 )
      {
          //
      }

//
//    Repeat ( 1 ), ( 2 ), and ( 3 )  until all values have been written or read.
//

      cbh.pb = NULL;

      LocalFree( lp );
}

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_BINARY, CLUSPROP_DISK_NUMBER, CLUSPROP_DISK_SIGNATURE, CLUSPROP_DWORD, CLUSPROP_LIST, CLUSPROP_MULTI_SZ, CLUSPROP_PARTITION_INFO, CLUSPROP_PROPERTY_NAME, CLUSPROP_REQUIRED_DEPENDENCY, CLUSPROP_RESOURCE_CLASS_INFO, CLUSPROP_RESOURCE_CLASS, CLUSPROP_SCSI_ADDRESS, CLUSPROP_SYNTAX, CLUSPROP_SZ, CLUSPROP_ULARGE_INTEGER, CLUSPROP_VALUE


CLUSPROP_LIST

The CLUSPROP_LIST structure is used to access the beginning of a property list.

typedef struct _CLUSPROP_LIST {
  DWORD                     nPropertyCount;
  CLUSPROP_PROPERTY_NAME    PropertyName;
} CLUSPROP_LIST, *PCLUSPROP_LIST;

Members

nPropertyCount
Number of properties in the property list.
PropertyName
Structure describing the name of the first property in the list.

Remarks

For information about property lists, see Property Lists.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLUSTERVERSIONINFO

The CLUSTERVERSIONINFO structure describes information about the version of the Cluster service installed locally on a node.

typedef struct _CLUSTERVERSIONINFO{
  DWORD dwVersionInfoSize;
  WORD  MajorVersion;
  WORD  MinorVersion;
  WORD  BuildNumber;
  WCHAR szVendorId[ 64 ];
  WCHAR szCSDVersion[ 64 ];
  DWORD dwClusterHighestVersion;
  DWORD dwClusterLowestVersion;
  DWORD dwFlags;
  DWORD dwReserved;
} CLUSTERVERSIONINFO, *LPCLUSTERVERSIONINFO, *PCLUSTERVERSIONINFO;

Members

dwVersionInfoSize
Size, in bytes, of the data structure. Users must set this size prior to calling GetClusterInformation.
MajorVersion
Identifies the major version number of Windows NT/Windows 2000 installed on the local node. For example, for version X.Y, the major version number is X.
MinorVersion
Identifies the minor version number of Windows NT/Windows 2000 installed on the local node. For example, for version X.Y, the minor version number is Y.
BuildNumber
Identifies the build number of Windows NT/Windows 2000installed on the local node, such as 224.
szVendorId
Contains the vendor identifier information for the Cluster service installed on the local node.
szCSDVersion
Contains the latest Microsoft Windows NT/Windows 2000 Service Pack installed on the node. If a Service Pack has not been installed, the szCSDVersion member is empty.
dwClusterHighestVersion
Identifies the highest version of the Cluster service with which the Cluster service installed on the local node can join to form a cluster.
dwClusterLowestVersion
Identifies the lowest version of the Cluster service with which theCluster service installed on the local node can join to form a cluster.
dwFlags
If the cluster nodes are running different versions of the Cluster service, this value is set to CLUSTER_VERSION_FLAG_MIXED_MODE. If all cluster nodes are running the same version of the Cluster service, this value is 0.
dwReserved
This value is reserved for internal use.

Remarks

To obtain cluster version information, applications declare a CLUSTERVERSIONINFO structure, specify the size of the structure in the dwVersionInfoSize member, and call the GetClusterInformation function. GetClusterInformation fills in the structure member data.

In previous versions of the Cluster service, CLUSTERVERSIONINFO was smaller (see CLUSTERVERSIONINFO_NT4 for the old definition). GetClusterInformation is designed to be backward-compatible and does not write past the szCSDVersion member if the dwVersionInfoSize member is set to the size of CLUSTERVERSIONINFO_NT4. Therefore, existing applications that call GetClusterInformation do not have to be modified.

To prevent overwrites for all possible combinations of Cluster service, API, and Windows NT/Windows 2000 versions, use the following guidelines:

  • Always use the new CLUSTERVERSIONINFO structure. Do not use CLUSTERVERSIONINFO_NT4.
  • Always set dwVersionSizeInfo to
    sizeof( CLUSTERVERSIONINFO ).

The dwClusterHighestVersion and dwClusterLowestVersion values indicate whether the local node can join with another node to form a cluster. A join can succeed if one of the following is true:

  • The local node's highest version exactly matches the other node's highest version.
  • The local node's lowest version exactly matches the other node's highest version.
  • The local node's highest version exactly matches the other node's lowest version.

For more information on how the Cluster service creates and uses version numbers, see Version Compatibility.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

GetClusterInformation


CLUSTERVERSIONINFO_NT4

The CLUSTERVERSIONINFO_NT4 structure was used as the CLUSTERVERSIONINFO structure in the previous version of the Cluster service.

typedef struct _CLUSTERVERSIONINFO_NT4{
  DWORD dwVersionInfoSize;
  WORD  MajorVersion;
  WORD  MinorVersion;
  WORD  BuildNumber;
  WCHAR szVendorId[ 64 ];
  WCHAR szCSDVersion[ 64 ];
} CLUSTERVERSIONINFO_NT4, *PCLUSTERVERSIONINFO_NT4;

Members

dwVersionInfoSize
Size, in bytes, of the data structure.
MajorVersion
Identifies the major version number of the Cluster service installed on the local node. For example, for version 1.0, the major version number is 1.
MinorVersion
Identifies the minor version number of the Cluster service installed on the local node. For example, for version 1.0, the minor version number is 0.
BuildNumber
Identifies the build number of the Cluster service installed on the local node, such as 224.
szVendorId
Contains the vendor identifier information for the Cluster service installed on the local node.
szCSDVersion
Contains the latest Microsoft Windows NT/Windows 2000 Service Pack installed on the node. If a Service Pack has not been installed, the szCSDVersion member is empty.

Remarks

Do not use the CLUSTERVERSIONINFO_NT4 structure except for size comparisons. It is included for backward compatibility only. Use the current CLUSTERVERSIONINFO structure in calls to GetClusterInformation.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSTERVERSIONINFO


RESUTIL_PROPERTY_ITEM

The RESUTIL_PROPERTY_ITEM structure contains information about a cluster object property. An array of RESUTIL_PROPERTY_ITEM structures forms a property table which can be used in property operations.

typedef struct _RESUTIL_PROPERTY_ITEM {
  LPWSTR  Name;
  LPWSTR  KeyName;
  DWORD   Format;
  union {
      DWORD_PTR  DefaultPtr;
      DWORD      Default;
      LPVOID     lpDefault;
  };
  DWORD   Minimum;
  DWORD   Maximum;
  DWORD   Flags;
  DWORD   Offset;
} RESUTIL_PROPERTY_ITEM, *PRESUTIL_PROPERTY_ITEM;

Members

Name
Contains the name of the property.
KeyName
Optional null-terminated Unicode string containing the name of the cluster database subkey for the property. This parameter can be NULL.
Format
Describes the format of the property such as CLUSPROP_FORMAT_BINARY or CLUSPROP_FORMAT_DWORD. For a list of valid format values, see the wFormat member of CLUSPROP_SYNTAX.
(union)
Specifies the default value of the property in one of the following ways:
DefaultPtr
Pointer to a DWORD default value.
Default
A DWORD default value.
lpDefault
Void pointer to a buffer containing the default value.

The default value must be consistent with the format specified by the Format member.

Minimum
Minimum data value for the property. For data values with the CLUSPROP_FORMAT_BINARY and CLUSPROP_FORMAT_MULTI_SZ formats, the Minimum member contains the byte size of the default data value specified by Default.
Maximum
Maximum data value for the property.
Flags
Bitmask that describes the property. Valid values are.
Flag | Indicates
RESUTIL_PROPITEM_READ_ONLY | The property is read-only.
RESUTIL_PROPITEM_REQUIRED | The property is required.
RESUTIL_PROPITEM_SIGNED | Flags a numeric property as a signed value.

Offset
Byte offset to the actual property data. The data is stored in a buffer known as a parameter block.

Remarks

For more information about building parameter blocks and property tables, see Using Lists and Tables.

Example

See Using Lists and Tables and Building with CLUSPROP_BUFFER_HELPER, and Defining Structures and Constants in Implementing Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_SYNTAX


Resource DLL Structures

The Resource API contains structures that are used to:

  • Describe the function table that is returned by the Startup entry point function.
  • Describe the status of a resource.

The resource DLL structures and macro follow.

Structure or macro | Description
CLRES_FUNCTION_TABLE | Structure that contains the version of the Resource API and pointers to all Resource API entry points except Startup.
CLRES_V1_FUNCTIONS | Structure that contains pointers to all resource entry points in the Resource API except Startup for Resource API 1.0.
RESOURCE_STATUS | Structure that contains information about a resource that is being brought online or taken offline.

See Also

CLRES_FUNCTION_TABLE, CLRES_V1_FUNCTIONS, RESOURCE_STATUS


CLRES_FUNCTION_TABLE

The CLRES_FUNCTION_TABLE structure describes a function table for any version of the Resource API.

typedef struct _CLRES_FUNCTION_TABLE {
  DWORD        TableSize;
  DWORD        Version;
  union {
     CLRES_V1_FUNCTIONS  V1Functions;
  }
} CLRES_FUNCTION_TABLE; *PCLRES_FUNCTION_TABLE;

Members

TableSize
Count of bytes in the structure, taken from the constant CLRES_V1_FUNCTION_SIZE.
Version
Number of the supported version of the Resource API, taken from the constant CLRES_VERSION_V1_00.
V1Functions
Table of entry points included in the Resource API version 1.0.

Remarks

Only the first two members are guaranteed to be at the same offset within the CLRES_FUNCTION_TABLE structure. All other entries within this structure are dependent on the Resource API version supported.

The V1Functions member is a CLRES_V1_FUNCTIONS structure containing pointers to all Resource API entry points except Startup. All pointers must be non-NULL except for pointers to the following entry point functions:

  • Arbitrate
  • Release
  • ResourceControl
  • ResourceTypeControl

For more information, see Implementing Resource DLLs.

To create a function table for version 1.0 of the Resource API, use the CLRES_V1_FUNCTION_TABLE macro.

Example

See Defining Structures and Constants in Implementing Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Arbitrate, CLRES_V1_FUNCTION_TABLE, CLRES_V1_FUNCTIONS, Release, ResourceControl, ResourceTypeControl,


CLRES_V1_FUNCTIONS

The CLRES_V1_FUNCTIONS structure contains pointers to all Resource API version 1.0 entry points except Startup.

typedef struct _CLRES_V1_FUNCTIONS
  POPEN_ROUTINE         Open;
  PCLOSE_ROUTINE        Close;
  PONLINE_ROUTINE       Online;
  POFFLINE_ROUTINE      Offline;
  PTERMINATE_ROUTINE    Terminate;
  PLOOKS_ALIVE_ROUTINE  LooksAlive;
  PIS_ALIVE_ROUTINE     IsAlive;
  PARBITRATE_ROUTINE    Arbitrate;
  PRELEASE_ROUTINE      Release;
  PRESOURCE_CONTROL_ROUTINE ResourceControl;
  PRESOURCE_TYPE_CONTROL_ROUTINE ResourceTypeControl
} CLRES_V1_FUNCTIONS, *PCLRES_V1_FUNCTIONS;

Members

Open
Pointer to the Open entry point.
Close
Pointer to the Close entry point.
Online
Pointer to the Online entry point.
Offline
Pointer to the Offline entry point.
Terminate
Pointer to the Terminate entry point.
LooksAlive
Pointer to the LooksAlive entry point.
IsAlive
Pointer to the IsAlive entry point.
Arbitrate
Pointer to the Arbitrate entry point.
Release
Pointer to the Release entry point.
ResourceControl
Pointer to the ResourceControl entry point.
ResourceTypeControl
Pointer to the ResourceTypeControl entry point.

Remarks

The CLRES_V1_FUNCTIONS structure is the function table that is returned by the Startup function in Resource API 1.0. Resource DLLs that support multiple resource types must provide one function table for each resource type. All function pointers must be non-NULL except for the following entry points:

  • Arbitrate
  • Release
  • ResourceControl
  • ResourceTypeControl

For more information, see Implementing Resource DLLs.

To create a function table for version 1.0 of the Resource API, use the CLRES_V1_FUNCTION_TABLE macro.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Arbitrate, Close, CLRES_V1_FUNCTION_TABLE, IsAlive, LooksAlive, Offline, Online, Open, Release, ResourceControl, ResourceControl, ResourceTypeControl, Startup, Terminate


RESOURCE_STATUS

The RESOURCE_STATUS structure contains information about a resource that is being brought online or taken offline. This structure is used as a parameter to the callback function SetResourceStatus.

typedef struct _RESOURCE_STATUS {
  CLUSTER_RESOURCE_STATE  ResourceState;
  DWORD                   CheckPoint;
  DWORD                   WaitHint;
  HANDLE                  EventHandle;
} RESOURCE_STATUS, *PRESOURCE_STATUS;

Members

ResourceState
A value describing the state of a resource. Valid values are.
State value | Description
ClusterResourceUnknown | An error occurred while trying to retrieve the state, typically because the server is no longer available. For more information, the caller should call the Win32 function GetLastError.
ClusterResourceOnline | The resource is online and available.
ClusterResourceOffline | The resource is offline and unavailable.
ClusterResourceFailed | The resource has failed.
ClusterResourceOnlinePending | The resource is in the process of being placed online. The CheckPoint member should be greater than the previous value of this member.
ClusterResourceOfflinePending | The resource is in the process of being taken offline.

CheckPoint
A value set by the resource DLL to flag a status report as new.
WaitHint
This member is not being used at this time.
EventHandle
Handle to an event that indicates when the resource has failed.

Remarks

Resource DLLs typically set the ResourceState member to ClusterResourceOnline or ClusterResourceOffline. However, if ResourceState is set to ClusterResourceOnlinePending or ClusterResourceOfflinePending, the CheckPoint member should be greater than the previous value reported for CheckPoint.

Resource DLLs initially set CheckPoint to zero, then increment it by 1 for each call to SetResourceStatus. Resource Monitors detect new status reports by comparing the current value of CheckPoint to the previous value. If the value has changed, the Resource Monitor reads the new status information.

Before returning the ClusterResourceUnknown state in the ResourceState member, a resource DLL should call the Win32 function SetLastError.

Resource DLLs set the EventHandle member to a handle that is signaled when a resource fails.

For more information, see Implementing Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

SetLastError, SetResourceStatus


Macros

The following macros are used to work with data structures and property lists.

Macro | Description
ALIGN_CLUSPROP | Aligns structures properly within value lists.
CLRES_V1_FUNCTION_TABLE | Creates a function table for Resource API version 1.0.
CLUSCTL_GET_ACCESS_MODE | Extracts the access code from a control code.
CLUSCTL_GET_CONTROL_FUNCTION | Extracts the operation code from a control code.
CLUSCTL_GET_CONTROL_OBJECT | Extracts the object code from a control code.
CLUSCTL_USER_CODE | Creates a user-defined control code.
CLUSPROP_BINARY_DECLARE | Initializes a CLUSPROP_BINARY structure.
CLUSPROP_PROPERTY_NAME_DECLARE | Initializes a CLUSPROP_PROPERTY_NAME structure.
CLUSPROP_SZ_DECLARE | Initializes a CLUSPROP_SZ structure.
CLUSTER_GET_MAJOR_VERSION | Extracts the major version portion of a Cluster service version number.
CLUSTER_GET_MINOR_VERSION | Extracts the minor version portion of a Cluster service version number.
CLUSTER_MAKE_VERSION | Creates a Cluster service version number.


ALIGN_CLUSPROP

The ALIGN_CLUSPROP macro is used to align structures properly within value lists.

ALIGN_CLUSPROP(
  count
)

Parameters

count
Size, in bytes, of the data to align. This value must be a constant.

Remarks

ALIGN_CLUSPROP returns a value that is greater than or equal to count. The value represents the total byte size of the data plus the padding required for proper alignment.

Clusapi.h defines ALIGN_CLUSPROP as follows:

#define ALIGN_CLUSPROP( count ) ((count + 3) & ~3)

Example

The following example illustrates how to use ALIGN_CLUSPROP to calculate the size of a value list entry. For additional examples, see Using Lists and Tables.

WCHAR szData[] = L"StringData";
DWORD cbSizeofValueListEntry;

cbSizeofValueListEntry = sizeof( CLUSPROP_VALUE ) +
                         ALIGN_CLUSPROP( sizeof( szData ) );

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLRES_V1_FUNCTION_TABLE

The CLRES_V1_FUNCTION_TABLE macro initializes a function table for version 1.0 of the Resource API.

CLRES_V1_FUNCTION_TABLE(
  _Name,
  _Version,
  _Prefix,
  _Arbitrate,
  _Release,
  _ResControl,
  _ResTypeControl
)

Parameters

_Name
Label for the function table.
_Version
Defines the exact version, such as CLRES_VERSION_V1_00.
_Prefix
Prefix to be appended to the front of each of the names of the entry points in the function table.
_Arbitrate
Name of the Arbitrate entry point.
_Release
Name of the Release entry point.
_ResControl
Name of the ResourceControl entry point.
_ResTypeControl
Name of the ResourceTypeControl entry point.

Remarks

The CLRES_V1_FUNCTION_TABLE macro creates a function table for version 1.0 of the Resource API using the version specified by the Version parameter and the label specified by the Name parameter. The actual names of the entry points are generated by combining the prefix specified in the Prefix parameter with the generic names as defined in the Resource API. For example, if Prefix is set to the string "FileShare," then the name of the Open function would be "FileShareOpen." Notice that the optional entry point functions may be NULL.

The resulting function table includes the following members.

Member | Description
PrefixOpen | Name of the Open entry point.
PrefixClose | Name of the Close entry point.
PrefixOnline | Name of the Online entry point.
PrefixOffline | Name of the Offline entry point.
PrefixTerminate | Name of the Terminate entry point.
PrefixLooksAlive | Name of the LooksAlive entry point.
PrefixIsAlive | Name of the IsAlive entry point.

To view the format of the function table, see the CLRES_FUNCTION_TABLE structure.

Example

See Defining Structures and Constants in Implementing Resource DLLs.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Resapi.h.

See Also

Arbitrate, CLRES_FUNCTION_TABLE, Release, ResourceControl, ResourceTypeControl


CLUSCTL_GET_ACCESS_MODE

The CLUSCTL_GET_ACCESS_MODE macro extracts the access code from a control code. For more information on the various codes that comprise a control code, see Control Code Architecture.

CLUSCTL_GET_ACCESS_MODE(
  ControlCode
)

Parameters

ControlCode
The control code to be analyzed.

Example

See the example under Creating Control Codes

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLUSCTL_GET_CONTROL_FUNCTION

The CLUSCTL_GET_CONTROL_FUNCTION macro extracts the operation code from a control code. For more information on the various codes that comprise a control code, see Control Code Architecture.

CLUSCTL_GET_CONTROL_FUNCTION(
  ControlCode
)

Parameters

ControlCode
The control code to be analyzed.

Example

See the example under Creating Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLUSCTL_GET_CONTROL_OBJECT

The CLUSCTL_GET_CONTROL_OBJECT macro extracts the object code from a control code. For more information on the various codes that comprise a control code, see Control Code Architecture.

CLUSCTL_GET_CONTROL_OBJECT(
  ControlCode
)

Paramters

ControlCode
The control code to be analyzed.

Example

See the example under Creating Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.


CLUSCTL_USER_CODE

The CLUSCTL_USER_CODE macro generates a correctly formatted user-defined control code. For more information on the bit layout of control codes, see Control Code Architecture.

CLUSCTL_USER_CODE(
  Function,
  Object
)

Parameters

Function
Value that specifies the operation code (bits 2-20) and, optionally, the access code (bits 0-1) of the resulting control code. The operation code can be any 19-bit value chosen by the caller. The access code (if specified) should be set to one of the following values.
Value | Constant | Description
0 | CLUS_ACCESS_ANY | The control code has no access requirements.
1 | CLUS_ACCESS_READ | Use of the control code requires read access.
2 | CLUS_ACCESS_WRITE | Use of the control code requires write access.

Object
An 8-bit value that specifies the object code (bits 24-31) of the resulting control code. For more information on the bit layout of control codes, see Control Code Architecture. The object code can be set to any value greater than CLUS_OBJECT_USER (128).

Remarks

Do not pass bit-shifted values for Function or Object. The macro performs the required bit shifts.

If no access code is specified, the control code will default to CLUS_ACCESS_ANY.

Example

See the example under Creating Control Codes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSCTL_GET_CONTROL_FUNCTION, CLUSCTL_GET_ACCESS_MODE, CLUSCTL_GET_CONTROL_OBJECT


CLUSPROP_BINARY_DECLARE

The CLUSPROP_BINARY_DECLARE macro creates a CLUSPROP_BINARY structure with the rgb member set to a size determined by the caller.

CLUSPROP_BINARY_DECLARE(
  name,
  cb
)

Parameters

name
Name of the CLUSPROP_BINARY structure to be created.
cb
The size (count of bytes) of the rgb member array. This value must be a constant.

Remarks

The following example shows how to use CLUSPROP_BINARY_DECLARE:

BYTE ByteData[] = { 'A', 1, 'B', 2, 'C' };
CLUSPROP_BINARY_DECLARE( ByteValue, sizeof( ByteData ) );
ByteValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
ByteValue.cbLength = sizeof( ByteData );
memcpy( ByteValue.rgb, ByteData, sizeof( ByteData ) );

Clusapi.h defines CLUSPROP_BINARY_DECLARE as follows:

#define CLUSPROP_BINARY_DECLARE( name, cch )    \
    struct {                                \
        CLUSPROP_SYNTAX Syntax;             \
        DWORD           cbLength;           \
        BYTE            rgb[(cch + 3) & ~3]; \
    } name

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_BINARY


CLUSPROP_PROPERTY_NAME_DECLARE

The CLUSPROP_PROPERTY_NAME_DECLARE macro creates a CLUSPROP_PROPERTY_NAME structure with the sz member set to a size determined by the caller.

CLUSPROP_PROPERTY_NAME_DECLARE(
  name,
  cch
)

Parameters

name
Name of the CLUSPROP_PROPERTY_NAME structure to be created.
cch
The size (that is, count of characters) of the sz member array. This value must be a constant.

Remarks

Clusapi.h defines CLUSPROP_PROPERTY_NAME_DECLARE as follows:

#define CLUSPROP_PROPERTY_NAME_DECLARE( name, cch )    \
    struct {                                \
        CLUSPROP_SYNTAX Syntax;             \
        DWORD           cbLength;           \
        WCHAR           sz[(cch + 1) & ~1]; \
    } name

Example

The following example shows how to use CLUSPROP_PROPERTY_NAME_DECLARE. For another example, see Creating Physical Disk Resources.

WCHAR szName[] = L"Name";
CLUSPROP_PROPERTY_NAME_DECLARE( PropName, sizeof( szName ) / sizeof( WCHAR ) );
PropName.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
PropName.cbLength  = sizeof( szName );
lstrcpyW( PropName.sz, szName );

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_PROPERTY_NAME


CLUSPROP_SZ_DECLARE

The CLUSPROP_SZ_DECLARE macro creates a CLUSPROP_SZ structure with the sz member set to a size determined by the caller.

CLUSPROP_SZ_DECLARE(
  name,
  cch
)

Parameters

name
Name of the CLUSPROP_SZ structure to be created.
cch
The size (that is, count of characters) of the sz member array. This value must be a constant.

Remarks

The following example shows how to use CLUSPROP_SZ_DECLARE:

WCHAR szNameData[] = L"Object Name";
CLUSPROP_SZ_DECLARE( NameValue, sizeof( szNameData ) / sizeof( WCHAR ) );
NameValue.Syntax.dw = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof( szNameData );
lstrcpyW( NameValue.sz, szNameData );

Clusapi.h defines CLUSPROP_SZ_DECLARE as follows:

#define CLUSPROP_SZ_DECLARE( name, cch )    \
    struct {                                \
        CLUSPROP_SYNTAX Syntax;             \
        DWORD           cbLength;           \
        WCHAR           sz[(cch + 1) & ~1]; \
    } name

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSPROP_SZ


CLUSTER_GET_MAJOR_VERSION

The CLUSTER_GET_MAJOR_VERSION macro extracts the major version portion of a Cluster service version number.

CLUSTER_GET_MAJOR_VERSION(
  _ver
)

Parameters

_ver
Cluster service version number.

Remarks

Cluster service version numbers are obtained from the NodeHighestVersion and NodeLowestVersion properties as well as the function GetClusterInformation. For more information, see Version Compatibility.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSTER_GET_MINOR_VERSION, CLUSTER_MAKE_VERSION


CLUSTER_GET_MINOR_VERSION

The CLUSTER_GET_MINOR_VERSION macro extracts the minor version portion of a Cluster service version number.

CLUSTER_GET_MINOR_VERSION(
  _ver
)

Parameters

_ver
Cluster service version number.

Remarks

Cluster service version numbers are obtained from the NodeHighestVersion and NodeLowestVersion properties as well as the function GetClusterInformation. For more information, see Version Compatibility.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSTER_GET_MAJOR_VERSION, CLUSTER_MAKE_VERSION


CLUSTER_MAKE_VERSION

The CLUSTER_MAKE_VERSION macro creates a Cluster service version number.

CLUSTER_MAKE_VERSION(
  _maj,
  _min
)

Parameters

_maj
Major version number.
_min
Minor version number.

Remarks

Cluster service version numbers are obtained from the NodeHighestVersion and NodeLowestVersion properties as well as the function GetClusterInformation. For more information, see Version Compatibility.

Requirements

Version: Requires Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Declared in Clusapi.h.

See Also

CLUSTER_GET_MAJOR_VERSION, CLUSTER_GET_MINOR_VERSION


Resource Object

[This is preliminary documentation and subject to change.]

The Resource object is an object automatically created by the Generic Script resource DLL for each instance of a scripted resource. Your script can use the methods and properties of the Resource object to identify the resource, log information about the resource, and manipulate private properties.

The Resource object has the following methods.

Method | Description
AddProperty | Adds a new private property to the resource instance.
Name | Returns the name of the resource instance.
LogInformation | Writes a string to the cluster event log.
RemoveProperty | Removes a private property from this resource instance.

Requirements

Version: Requires Whistler.


Resource.AddProperty

[This is preliminary documentation and subject to change.]

The AddProperty method adds a new private property to the resource instance.

Resource.AddProperty(strName)

Parameters

strName
String specifying the name of the new private property.

Return Values

None

Remarks

To access the value of any private property, use Resource.<Name of private property>.

Example

See the Scripted Resource Example.

Requirements

Version: Requires Whistler.

See Also

Resource


Resource.LogInformation

[This is preliminary documentation and subject to change.]

The LogInformation method writes the specified string to the cluster event log.

Resource.LogInformation(strMessage)

Parameters

strMessage
String describing the event to log.

Return Values

None

Example

See the Scripted Resource Example.

Requirements

Version: Requires Whistler.

See Also

Resource


Resource.Name

[This is preliminary documentation and subject to change.]

The Name method returns the name of the resource instance. Note that you cannot use this method to set the name of the resource.

strName = Resource.Name

Parameters

strName
String that receives the name of the resource.

Return Values

The name of the resource.

Example

See the Scripted Resource Example.

Requirements

Version: Requires Whistler.

See Also

Resource


Resource.RemoveProperty

[This is preliminary documentation and subject to change.]

The RemoveProperty method removes a private property from the resource instance.

Resource.RemoveProperty(strName)

Parameters

strName
String specifying the name of the private property to remove.

Return Values

None

Remarks

To access the value of any private property, use Resource.<Name of private property>.

Example

See the Scripted Resource Example.

Requirements

Version: Requires Whistler.

See Also

Resource


Cluster Automation Server Reference

The Microsoft® Cluster Automation Server, MSCLUS.DLL, exposes a set of Component Object Model (COM) objects to high-level and scripting languages. Cluster Automation Server lets you quickly and easily create a cluster management application using the properties and methods associated with each Cluster Automation Server object.

The Cluster Automation Server reference is organized according to the following table. For more information on the relationships between objects, see Object Hierarchy.

Section | Contents
Application Management Objects | Objects and collections for meta-cluster operations.
Cluster Management Objects | Objects and collections for cluster-level operations.
Disk Management Objects | Objects and collections for working with Physical Disks.
Group Management Objects | Objects and collections for working with groups.
Network Management Objects | Objects and collections for working with networks.
Network Interface Management Objects | Objects and collections for working with network interfaces.
Node Management Objects | Objects and collections for working with nodes
Property Management Objects | Objects and collections for working with cluster object properties.
Resource Management Objects | Objects and collections for working with resources.
Resource Type Management Objects | Objects and collections for working with resource types.

For information on programming with Cluster Automation Server, see Using Cluster Automation Server.


Application Management Objects

The application management objects provide high-level access to multiple domains and clusters.

  • ClusApplication Object
  • ClusterNames Collection
  • DomainNames Collection


ClusApplication Object

The ClusApplication object provides access to the DomainNames and ClusterNames collections and opens a connection to a specified cluster.

Properties and Methods

Method or property | Description
ClusterNames Property | Returns the names of all the clusters in a domain.
DomainNames Property | Returns the names of all available domains.
OpenCluster Method | Opens a connection to a cluster.

Remarks

ClusApplication is a top-level object, allowing new object instances to be created. For example:

Dim objApplication as ClusApplication
Set objApplication = New ClusApplication

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Application Management Objects


ClusApplication.ClusterNames

The ClusterNames property returns the names of all the clusters in a domain.

Set colClusterNames = object.ClusterNames( strDomainName )

Parameters

colClusterNames
A ClusterNames collection that receives the names of the clusters in the specified domain.
object
Object expression that resolves to a ClusApplication object.
strDomainName
String containing the name of a domain available to the ClusApplication object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusApplication, ClusterNames


ClusApplication.DomainNames

The DomainNames property returns the names of all domains available to a ClusApplication object.

Set colDomainNames = object.DomainNames

Parameters

olDomainNames
DomainNames collection that receives the names of the domains.
object
Object expression that resolves to a ClusApplication object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusApplication, DomainNames


ClusApplication.OpenCluster

The OpenCluster method opens a connection to a cluster.

Set objCluster = object.OpenCluster( strClusterName )

Parameters

objCluster
A Cluster object that receives the opened connection.
object
Object expression that resolves to a ClusApplication object.
strClusterName
String containing the name of the cluster to open. If set to a zero-length string (""), the method will open a connection to the local node's cluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusApplication, Cluster


ClusterNames Collection

A ClusterNames collection provides access to the names of the clusters in a domain.

Properties and Methods

Method or property | Description
Count Property | Returns the number of clusters in the domain.
DomainName Property | Returns the name of the domain that is the source of the collection.
Item Property | Returns a name of a cluster from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusterNames collection:

  • Contains cluster names.
  • Is obtained from ClusApplication.ClusterNames.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Application Management Objects


ClusterNames.Count

The Count property returns the number of objects in the ClusterNames collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusterNames collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusterNames


ClusterNames.DomainName

The DomainName property returns the name of the domain from which the ClusterNames collection came.

strDomainName = object.DomainName

Parameters

strDomainName
String that receives the name of the current domain.
object
Object expression that resolves to a ClusterNames collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusterNames


ClusterNames.Item

The Item property returns a name of a cluster from the ClusterNames collection.

strClusterName = object.Item( varIndex )

Parameters

strClusterName
String that receives the name of a cluster in the collection.
object
Object expression that resolves to a ClusterNames collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusterNames, ClusterNames.Count


ClusterNames.Refresh

The Refresh method refreshes the data in the ClusterNames collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusterNames collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusterNames


DomainNames Collection

The DomainNames collection provides access to the names of the domains on a network.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a name of a domain from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A DomainNames collection:

  • Contains domain names.
  • Is obtained from ClusApplication.DomainNames.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Application Management Objects


DomainNames.Count

The Count property returns the number of objects in the DomainNames collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a DomainNames collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

DomainNames


DomainNames.Item

The Item property returns a single domain name from a DomainNames collection.

strDomainName = object.Item( varIndex )

Parameters

strDomainName
String that receives the name of a domain from the collection.
object
Object expression that resolves to a DomainNames collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

DomainNames.Count, DomainNames


DomainNames.Refresh

The Refresh method refreshes the data in the DomainNames collection.

object.Refresh

Parameters

object
Object expression that resolves to a DomainNames collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

DomainNames


Cluster Management Objects

The cluster management objects enable top-level control of a cluster and the objects owned by the cluster.

  • Cluster Object
  • ClusNetworks Collection
  • ClusNetInterfaces Collection
  • ClusNodes Collection
  • ClusResGroups Collection
  • ClusResources Collection
  • ClusResTypes Collection
  • ClusVersion Object


Cluster Object

The Cluster object enables operations on the cluster and provides access to all of the objects in the cluster.

Properties and Methods

Method or property | Description
CommonProperties Property | Returns the read/write common properties of the cluster.
CommonROProperties Property | Returns the read-only common properties of the cluster.
Name Property | Returns the current name of a cluster or allows a new name to be assigned.
NetInterfaces Property | Returns a ClusNetInterfaces collection providing access to the network interfaces in a cluster.
Networks Property | Returns a ClusNetworks collection providing access to the networks in a cluster.
Nodes Property | Returns a ClusNodes collection providing access to the nodes in a cluster.
Open Method | Opens a connection to a cluster.
PrivateROProperties Property | Returns the read/write private properties of the cluster.
PrivateProperties Property | Returns the read-only private properties of the cluster.
QuorumLogSize Property | Sets or returns the maximum size of the log file maintained by the quorum resource.
QuorumPath Property | Sets or returns the path to the log file maintained by the quorum resource.
QuorumResource Property | Specifies or returns a ClusResource object representing the current quorum resource for a cluster.
ResourceGroups Property | Returns a ClusResGroups collection providing access to the groups in a cluster.
Resources Property | Returns a ClusResources collection providing access to the resources in a cluster.
ResourceTypes Property | Returns a ClusResTypes collection providing access to the resource types in a cluster.
Version Property | Returns a ClusVersion object describing the cluster version.

Remarks

Cluster is a top-level object, allowing new object instances to be created. For example:

Dim objCluster as Cluster
Set objCluster = New Cluster

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


Cluster.CommonProperties

The CommonProperties property returns the read/write common properties of a cluster.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a Cluster object.
colClusProperties
ClusProperties collection that receives the read/write common properties of the cluster.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster


Cluster.CommonROProperties

The CommonROProperties property returns the read-only common properties of a cluster.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a Cluster object.
colClusProperties
A ClusProperties collection that receives the read-only common properties of the cluster.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, Cluster


Cluster.Name

The Name retrieves or sets the name of the cluster.

object.Name [ = strName ]

Parameters

object
Object expression that resolves to a Cluster object.
strName
String containing the new name of the cluster.

Access

Read/write

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster


Cluster.NetInterfaces

The NetInterfaces property returns a ClusNetInterfaces collection providing access to the network interfaces in a cluster.

Set colNetInterfaces = object.NetInterfaces

Parameters

colNetInterfaces
A ClusNetInterfaces collection.
object
Object expression that resolves to a Cluster object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterfaces, Cluster


Cluster.Networks

The Networks property returns a ClusNetworks collection providing access to the networks in a cluster.

Set colNetworks = object.Networks

Parameters

colNetworks
A ClusNetworks collection.
object
Object expression that resolves to a Cluster object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetworks, Cluster


Cluster.Nodes

The Nodes property returns a ClusNodes collection providing access to the nodes in a cluster.

Set colNodes = object.Nodes

Parameters

colNodes
A ClusNodes collection.
object
Object expression that resolves to a Cluster object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNodes, Cluster


Cluster.Open

The Open method opens a connection to a cluster.

object.Open( strClusterName )

Parameters

object
Object expression that resolves to a Cluster object.
strClusterName
String specifying the name of the cluster to open. If set to a zero-length string (""), the method connects to the local machine's cluster.

Example Code

The following example illustrates the Open method. For more examples see Using Cluster Automation Server.

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
'  opendemo.vbs  (use with cscript.exe)
'  Run from the command line using the following syntax:
'        opendemo [clustername]
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
Dim objArgs, objCluster
Set objArgs = WScript.Arguments
Set objCluster = CreateObject("MSCluster.Cluster")
If objArgs.Count > 0 Then
    objCluster.Open objArgs(0)
Else
    objCluster.Open ""
End If
WScript.Echo "Successfully opened " & objCluster.Name
Set objCluster = Nothing
Set objArgs = Nothing

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster


Cluster.PrivateProperties

The PrivateProperties property returns the read/write private properties of a cluster.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a Cluster object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the cluster.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster


Cluster.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a cluster.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a Cluster object.
colClusProperties
A ClusProperties collection that receives the read-only private properties of the cluster.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, Cluster


Cluster.QuorumLogSize

The QuorumLogSize property returns or sets the maximum size of the log file maintained by the quorum resource.

lLogSize = object.QuorumLogSize

object.QuorumLogSize = lNewLogSize

Parameters

lLogSize
Long that receives the current maximum log file size.
object
Object expression that resolves to a Cluster object.
lNewLogSize
Long specifying a new maximum log file size.

Access

Read/write

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster, Cluster.QuorumResource


Cluster.QuorumPath

The QuorumPath property retrieves or sets the path to the log file maintained by the quorum resource.

strDevicePath = object.QuorumPath

object.QuorumPath = strNewPath

Parameters

strDevicePath
String that receives the current path to the quorum log file.
object
Object expression that resolves to a Cluster object.
strNewPath
String containing the new path to the quorum log file

Access

Read/write

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster, Cluster.QuorumLogSize, Cluster.QuorumResource


Cluster.QuorumResource

The QuorumResource property returns the current quorum resource for a cluster or allows a new quorum resource to be designated.

Set objResource = object.QuorumResource

Set object.QuorumResource = objNewResource

Parameters

objResource
A ClusResource object currently representing the cluster's quorum resource.
object
Object expression that resolves to a Cluster object.
objNewResource
A ClusResource object representing the resource to become the cluster's new quorum resource.

Access

Read/write

Remarks

An alternate way to assign a quorum resource is to call that resource's ClusResource.BecomeQuorumResource method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResource.BecomeQuorumResource, Cluster


Cluster.ResourceGroups

The ResourceGroups property returns the groups in a cluster.

Set colResGroups = object.ResourceGroups

Parameters

colResGroups
A ClusResGroups collection providing access to all of the groups in the cluster.
object
Object expression that resolves to a Cluster object.

Access

Read-only

Remarks

To access all of the groups for a particular node, use the ClusNode.ResourceGroups property for that node.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode.ResourceGroups, ClusResGroups, Cluster


Cluster.Resources

The Resources property returns a ClusResources collection providing access to the resources in a cluster.

Set colResources = object.Resources

Parameters

colResources
A ClusResources collection that receives the cluster resources.
object
Object expression that resolves to a Cluster object.

Access

Read-only

Remarks

The ClusResources collection returned by the Cluster object's Resources property provides access to all the resources in the cluster. To retrieve information about all of the resources owned by a particular group, use the ClusResGroup.Resources property.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup.Resources, ClusResources, Cluster


Cluster.ResourceTypes

The ResourceTypes property returns a ClusResTypes collection providing access to the resource types in a cluster.

Set colResTypes = object.ResourceTypes

Parameters

colResTypes
A ClusResTypes collection that receives the resource types.
object
Object expression that resolves to a Cluster object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster, ClusResTypes


Cluster.Version

The Version property returns a ClusVersion object describing the operating system and Cluster service versions running on the local node.

Set objVersion = object.Version

Parameters

object
Object expression that resolves to a Cluster object.
objVersion
A ClusVersion object that receives the version information.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster, ClusVersion


ClusNetInterfaces Collection

The ClusNetInterfaces collection provides access to the network interfaces in a cluster.

Properties and Methods

Method or propertyd | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single network interface from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusNetInterfaces collection:

  • Contains ClusNetInterface objects.
  • Is obtained from Cluster.NetInterfaces.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusNetInterfaces.Count

The Count property returns the number of objects in the ClusNetInterfaces collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusNetInterfaces collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterfaces


ClusNetInterfaces.Item

The Item property retrieves a single network interface from a ClusNetInterfaces collection.

Set objNetInterface = object.Item( varIndex )

Parameters

objNetInterface
A ClusNetInterface object that receives the specified network interface.
object
Object expression that resolves to a ClusNetInterfaces collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, ClusNetInterfaces, ClusNetInterfaces.Count


ClusNetInterfaces.Refresh

The Refresh method refreshes the data in the ClusNetInterfaces collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusNetInterfaces collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterfaces


ClusNetworks Collection

The ClusNetworks collection provides access to the networks in a cluster.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single network from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusNetworks collection:

  • Contains ClusNetwork objects.
  • Is obtained from Cluster.Networks.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusNetworks.Count

The Count property returns the number of objects in the ClusNetworks collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the ClusNetworks collection.
object
Object expression that resolves to a ClusNetworks collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetworks


ClusNetworks.Item

The Item property retrieves a single ClusNetwork object from the ClusNetworks collection.

Set objNetwork =  object.Item( varIndex )

Parameters

objNetwork
A ClusNetwork object that receives the specified network.
object
Object expression that resolves to a ClusNetworks collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, ClusNetworks, ClusNetworks.Count


ClusNetworks.Refresh

The Refresh method refreshes the data in the ClusNetworks collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusNetworks collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetworks


ClusNodes Collection

The ClusNodes collection provides access to the nodes in a cluster.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single node from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusNodes collection:

  • Contains ClusNode objects.
  • Is obtained from Cluster.Nodes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusNodes.Count

The Count property returns the number of objects in the ClusNodes collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusNodes collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNodes


ClusNodes.Item

The Item property returns a single node from a ClusNodes collection.

Set objNode = object.Item( varIndex )

Parameters

objNode
A ClusNode object that receives the specified node.
object
Object expression that resolves to a ClusNodes collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object.Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusNodes, ClusNodes.Count


ClusNodes.Refresh

The Refresh method refreshes the data in the ClusNodes collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNodes


ClusResGroups Collection

The ClusResGroups collection provides access to all cluster groups belonging either to a cluster or to a particular node in a cluster.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
CreateItem Method | Creates a new group and adds it to the collection.
DeleteItem Method | Deletes a group from the collection.
Item Property | Returns a single group from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResGroups collection:

  • Contains ClusResGroup objects.
  • Is obtained from Cluster.ResourceGroups or ClusNode.ResourceGroups.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusResGroups.Count

The Count property returns the number of objects in the ClusResGroups collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusResGroups collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroups


ClusResGroups.CreateItem

The CreateItem method creates a new group in the cluster and adds it to the ClusResGroups collection.

Set objResGroup =  object.CreateItem( GroupName )

Parameters

objResGroup
A ClusResGroup object that receives the new group.
object
Object expression that resolves to a ClusResGroups collection.
GroupName
String containing the name of the group to create.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup, ClusResGroups


ClusResGroups.DeleteItem

The DeleteItem method deletes a group from the cluster as well as from the ClusResGroups collection.

object.DeleteItem( index )

Parameters

object
Object expression that resolves to a ClusResGroups collection.
varIndex
Integer that identifies an object in the collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroups


ClusResGroups.Item

The Item property retrieves a single group from a ClusResGroups collection.

Set objGroup = object.Item( varIndex )

Parameters

objGroup
A ClusResGroup object that receives the specified group.
object
Object expression that resolves to a ClusResGroups collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup, ClusResGroups, ClusResGroups.Count


ClusResGroups.Refresh

The Refresh method refreshes the data in the ClusResGroups collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResGroups collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroups


ClusResources Collection

A ClusResources collection provides access to the resources that belong to a cluster.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
CreateItem Method | Creates a new resource and adds it to the collection.
DeleteItem Method | Deletes a resource from the cluster.
Item Property | Returns a single resource from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResources collection:

  • Contains ClusResource objects.
  • Is obtained from Cluster.Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusResources.Count

The Count property returns the number of objects in the ClusResources collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusResources collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResources


ClusResources.CreateItem

The CreateItem method creates a new resource and adds it to a ClusResources collection.

Set objResource =  object.CreateItem( strResourceName, _
                                      strResourceType, _
                                      strGroupName, _
                                      lFlag )

Parameters

object
Object expression that resolves to a ClusResources collection.
strResourceName
String containing the name of the resource to create.
strResourceType
String specifying the type of resource to create.
strGroupName
String containing the name of the group to which the new resource will belong.
lFlag
Value indicating how to create the resource. lFlag can be set to.
Value | Constant | Description
0 | CLUSTER_RESOURCE_DEFAULT_MONITOR | The Cluster service determines the resource monitor to which the new resource will be assigned.
1 | CLUSTER_RESOURCE_SEPARATE_MONITOR | Causes the Cluster service to create a separate Resource Monitor dedicated exclusively to the new resource.

objResource
Object that receives contains the new ClusResource object representing the new resource.

Remarks

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResources


ClusResources.DeleteItem

The DeleteItem method deletes a resource from the cluster and removes it from a ClusResources collection.

object.DeleteItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResources collection.
varIndex
Integer that identifies an object in the collection by name or numeric index.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResources


ClusResources.Item

The Item property retrieves a single ClusResource object from the ClusResources collection.

Set objResource = object.Item( varIndex )

Parameters

object
Object expression that resolves to a ClusResources collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.
objResource
A ClusResource object that receives the specified resource.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResources, ClusResources.Count


ClusResources.Refresh

The Refresh method refreshes the data in the ClusResources collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResources collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResources


ClusResTypes Collection

The ClusResTypes collection provides access to the resource types in a cluster.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
CreateItem Method | Creates a new resource type in the cluster.
DeleteItem Method | Deletes a resource type from the cluster.
Item Property | Returns a single resource type from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResTypes collection:

  • Contains ClusResType objects.
  • Is obtained from Cluster.ResourceTypes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusResTypes.Count

The Count property returns the number of objects in the ClusResTypes collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusResTypes collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypes


ClusResTypes.CreateItem

The CreateItem method creates a new resource type in the cluster and adds it to a ClusResTypes collection.

Set objResType =  object.CreateItem( strResTypeName, _
                                     strDisplayName, _
                                     strResTypeDll, _
                                     lLooksAlivePollInterval,
                                     lIsAlivePollInterval )

Parameters

object
Object expression that resolves to a ClusResTypes collection.
strResTypeName
String containing the name of the new resource type.
strDisplayName
String containing the display name of the new resource type.
strResTypeDll
String containing the file name of the library containing the new resource type.
lLooksAlivePollInterval
Length of time in milliseconds that should occur between calls to the new resource type's LooksAlive entry point function.
lIsAlivePollInterval
Length of time in milliseconds that should occur between calls to the new resource type's IsAlive entry point function.
objResType
A ClusResType object that receives the newly added resource type.

Remarks

The new resource type must be supported by a resource DLL. For more information, see Creating a Custom Resource Type.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResType, ClusResTypes, IsAlive, LooksAlive


ClusResTypes.DeleteItem

The DeleteItem method deletes a resource type from the cluster and removes it from the ClusResTypes collection.

object.DeleteItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResTypes collection.
varIndex
Integer that identifies an object in the collection by name or numeric index.

Remarks

If there are any resources of the specified type present in the cluster, the DeleteItem method fails for that resource type. In other words, you cannot delete a resource type if there are resources of that type present in the cluster.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypes


ClusResTypes.Item

The Item property returns a single ClusResType object from a ClusResTypes collection.

Set objResType = object.Item( varIndex )

Parameters

object
Object expression that resolves to a ClusResTypes collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.
objResType
A ClusResType object that receives the specified resource type.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResType, ClusResTypes, ClusResTypes.Count


ClusResTypes.Refresh

The Refresh method refreshes the data in the ClusResTypes collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResTypes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypes


ClusVersion Object

The ClusVersion object provides version information about the operating system and the Cluster service. For more information on cluster versions and version numbers, see Version Compatibility.

Properties and Methods

Method or property | Description
BuildNumber Property | Returns the build number of Microsoft® Windows NT®/Windows® 2000 installed on the local node.
ClusterHighestVersion Property | Returns the current value of ClusterHighestVersion.
ClusterLowestVersion Property | Returns the current value of ClusterLowestVersion
CSDVersion Property | Returns the number of the latest Service Pack installed on the local node.
Flags Property | Returns any cluster version flags set in the cluster.
MajorVersion Property | Returns the major version number of Windows NT/Windows 2000 installed on the local node.
MinorVersion Property | Returns the major version number of Windows NT/Windows 2000 installed on the local node.
MixedVersion Property | Indicates whether different versions of the Cluster service are present in the cluster.
Name Property | Returns the name of the cluster
VendorId Property | Returns vendor identification information for the version of Cluster service installed on the local node.

Relationships

A ClusVersion collection:

  • Is obtained from Cluster.Version.

Remarks

Some of the ClusVersion properties correspond to dynamic values maintained internally by the cluster. A ClusVersion object is instantiated with a snapshot of those values and stores them statically. Therefore, the ClusVersion property values represent the state of the cluster when the object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

For more information about the versioning process see Version Compatibility.

Example Code

The following script instantiates and uses a ClusVersion object.

'---------------------------------------------------------------------
' ClusVersion.vbs
' Uses the ClusVersion object to display version information about
' the local cluster.
'---------------------------------------------------------------------
Option Explicit
Const LOW16 = 65535
Dim objClus, objVers
Dim strVersion, strOSVersion, strHighest, strLowest

' Connect to the local cluster and get a ClusVersion object.
Set objClus = CreateObject("MSCluster.Cluster")
objClus.Open ""
Set objVers = objClus.Version

' Format a string describing the current version
strOSVersion = CStr(objVers.MajorVersion) & "." & _
               CStr(objVers.MinorVersion) & "." & _
               CStr(objVers.BuildNumber)

' Format a string describing the highest compatible version.
' We must extract the upper and lower 16 bits of the 32-bit value.
strHighest = CStr(CLng(objVers.ClusterHighestVersion / (2 ^ 15))) & _
             ".0." & _
             CStr(CLng(objVers.ClusterHighestVersion And LOW16))

' Format a string describing the lowest compatible version.
' We must extract the upper and lower 16 bits of the 32-bit value.
strLowest = CStr(CLng(objVers.ClusterLowestVersion / (2 ^ 15))) & _
            ".0." & _
            CStr(CLng(objVers.ClusterLowestVersion And LOW16))

' Format and display the output string.
strVersion = objVers.Name & vbCrLf & _
             objVers.VendorID & " version " & _
             strOSVersion & vbCrLf & "Compatible with versions: " & _
             strLowest & " and " & strHighest & vbCrLf
WScript.Echo strVersion

Set objVers = Nothing
Set objClus = Nothing

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster Management Objects


ClusVersion.BuildNumber

The BuildNumber property returns the build number of Windows NT/Windows 2000 installed on the local node.

intOSBuild = object.BuildNumber

Parameters

object
Object expression that resolves to a ClusVersion object.
intOSBuild
Short that receives the build number.

Access

Read-only

Remarks

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion, ClusVersion.CSDVersion, ClusVersion.MajorVersion, ClusVersion.MinorVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.ClusterHighestVersion

The ClusterHighestVersion property returns a value containing the highest version of the Cluster service with which the current cluster is compatible.

lCHV = object.ClusterHighestVersion

Parameters

object
Object expression that resolves to a ClusVersion object.
lCHV
Long that receives the version value. The upper 16 bits of the value indicate the release number of the Cluster service. The lower 16 bits specify the build number of the Cluster service.

Access

Read-only

Remarks

All ClusVersion properties are static values corresponding to the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

The cluster dynamically maintains the ClusterHighestVersion and ClusVersion.ClusterLowestVersion values based on the versions of the Cluster service running on the active nodes. A node can join the cluster only if its version of the Cluster service is compatible with ClusterHighestVersion and ClusterLowestVersion. For more information, see Version Compatibility.

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion, ClusVersion.ClusterLowestVersion, ClusVersion.MixedVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.ClusterLowestVersion

The ClusterLowestVersion property returns a value containing the lowest version of the Cluster service with which the current cluster is compatible.

lCLV = object.ClusterLowestVersion

Parameters

object
Object expression that resolves to a ClusVersion object.
lCLV
Long that receives the version value. The upper 16 bits of the value indicate the release number of the Cluster service. The lower 16 bits specify the build number of the Cluster service.

Access

Read-only

Remarks

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

The cluster dynamically maintains the ClusVersion.ClusterHighestVersion and ClusterLowestVersion values based on the versions of the Cluster service running on the active cluster nodes. A node can join the cluster only if its version of the Cluster service is compatible with ClusterHighestVersion and ClusterLowestVersion. For more information, see Version Compatibility.

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion, ClusVersion.ClusterLowestVersion, ClusVersion.MixedVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.CSDVersion

The CSDVersion property returns the number of the latest Service Pack of Windows NT/Windows 2000 installed on the local node.

strCSDVersion = object.CSDVersion

Parameters

object
Object expression that resolves to a ClusVersion object.
strCSDVersion
String that receives the build number.

Access

Read-only

Remarks

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

SeeAlso

ClusVersion, ClusVersion.CSDVersion, ClusVersion.MajorVersion, ClusVersion.MinorVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.Flags

The BuildNumber property returns flags associated with the cluster version.

lFlags = object.Flags

Parameters

object
Object expression that resolves to a ClusVersion object.
lFlags
Long that receives the flags. Only one flag is defined by Msclus.h:
CLUSTER_VERSION_FLAG_MIXED_MODE
There is more than one version of the Cluster service running on the cluster nodes.

Access

Read-only

Remarks

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

SeeAlso

ClusVersion, ClusVersion.CSDVersion, ClusVersion.MajorVersion, ClusVersion.MinorVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.MajorVersion

The MajorVersion property returns the integer portion of the Windows NT/Windows 2000 version installed on the local node.

lMajorVersion = object.MajorVersion

Parameters

object
Object expression that resolves to a ClusVersion object.
lMajorVersion
Long that receives the major version.

Access

Read-only

Remarks

The MajorVersion and ClusVersion.MinorVersion properties together form a complete Windows version number.

Version = X.Y
MajorVersion = X
MinorVersion = Y

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion, ClusVersion.CSDVersion, ClusVersion.MajorVersion, ClusVersion.MinorVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.MinorVersion

The MinorVersion property returns the decimal portion of the Windows NT/Windows 2000 version installed on the local node.

lMinorVersion = object.MinorVersion

Parameters

object
Object expression that resolves to a ClusVersion object.
lMinorVersion
Long that receives the minor version.

Access

Read-only

Remarks

The ClusVersion.MajorVersion and MinorVersion properties together form a complete Windows version number.

Version = X.Y
MajorVersion = X
MinorVersion = Y

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion, ClusVersion.CSDVersion, ClusVersion.MinorVersion, ClusVersion.MinorVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.MixedVersion

The MixedVersion property indicates whether more than one version of the Cluster service is present in the cluster, a state described as mixed mode.

varMixed = object.MixedVersion

Parameters

object
Object expression that resolves to a ClusVersion object.
varMixed
A Variant set to TRUE if the cluster version is mixed.

Access

Read-only

Remarks

For more information on mixed mode clusters and compatibility between nodes running different versions of the Cluster service, see Version Compatibility.

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

SeeAlso

ClusVersion, ClusVersion.ClusterLowestVersion, ClusVersion.MixedVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.Name

The Name property returns the name of the cluster.

strName = object.Name

Parameters

object
Object expression that resolves to a ClusVersion object.
strName
String that receives the name.

Access

Read-only

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion, ClusVersion.CSDVersion, ClusVersion.MajorVersion, ClusVersion.MinorVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusVersion.VendorId

The VendorID property returns vendor information about the Cluster service installed on the local node.

strVendor = object.VendorID

Parameters

object
Object expression that resolves to a ClusVersion object.
strVendor
String that receives the vendor information.

Access

Read-only

Remarks

All ClusVersion properties are static values corresponding the state of the cluster when the ClusVersion object was first created. To obtain the latest version information from the cluster, create a new ClusVersion object.

Example Code

See ClusVersion for an example.

SeeAlso

ClusVersion

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


Disk Management Objects

The disk management objects are used to work with Physical Disk resources.

  • ClusDisk Object
  • ClusPartition Object
  • ClusPartitions Collection
  • ClusScsiAddress Object


ClusDisk Object

The ClusDisk object provides access to identification and configuration data about a Physical Disk.

Properties and Methods

Method or property | Description
DiskNumber Property | Returns the disk number of the disk.
Partitions Property | Returns a ClusPartitions collection containing partition data for the disk.
ScsiAddress Property | Returns a ClusScsiAddress object describing SCSI information about the disk.
Signature Property | Returns the signature of the disk.

Relationships

A ClusDisk object:

  • Is obtained from ClusDisks.Item or ClusResource.Disk.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusDisk.DiskNumber

The ClusDisk.DiskNumber property returns the disk number of a Physical Disk.

lDiskNumber = object.DiskNumber

Parameters

lDiskNumber
A Variant that receives the disk number of the disk.
object
Object expression that resolves to a ClusDisk object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusDisk.Partitions, ClusDisk.ScsiAddress, ClusDisk.Signature


ClusDisk.Partitions

The Partitions property returns a ClusPartitions collection containing partition information about a Physical Disk.

colPartitions = object.Partitions

Parameters

colPartitions
A ClusPartitions collection that receives the partition information.
object
Object expression that resolves to a ClusDisk object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusDisk.ScsiAddress, ClusDisk.Signature


ClusDisk.ScsiAddress

The ScsiAddress property returns a ClusScsiAddress object describing SCSI information about a Physical Disk.

colScsiInfo = object.ScsiAddress

Parameters

colScsiInfo
A ClusScsiAddress object that receives the SCSI information.
object
Object expression that resolves to a ClusDisk object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusDisk.Partitions, ClusDisk.ScsiAddress, ClusDisk.Signature


ClusDisk.Signature

The Signature property returns the signature of a Physical Disk.

lSignature = object.Signature

Parameters

lSignature
Long that receives the signature of the disk.
object
Object expression that resolves to a ClusDisk object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusDisk.DiskNumber, ClusDisk.Partitions, ClusDisk.ScsiAddress


ClusPartitions Collection

The ClusPartitions collection provides access to the partitions of a Physical Disk.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single object from the collection.

Relationships

A ClusPartitions collection:

  • Contains ClusPartition objects.
  • Is obtained from ClusDisk.Partitions.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusPartitions.Count

The Count property returns the number of partitions in the ClusPartitions collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of partitions in the collection.
object
Object expression that resolves to a ClusPartitions collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartitions


ClusPartitions.Item

The Item property returns a single partition from a ClusPartitions collection.

Set objPartition =  object.Item( varIndex )

Parameters

objPartition
A ClusPartition object that receives the specified properties.
object
Object expression that resolves to a ClusPartitions collection.
varIndex
A Variant that identifies an object in the collection by numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition, ClusPartitions, ClusPartitions.Count


ClusPartition Object

The ClusPartition object provides information about a partition on a Physical Disk resource.

Properties and Methods

Method or property | Description
DeviceName Property | Returns the partition's device name.
FileSystem Property | Returns the partition's file system.
FileSystemFlags Property | Returns any descriptive flags associated with the partition's file system.
Flags Property | Returns any descriptive flags associated with the partition.
MaximumComponentLength Property | Returns the maximum length allowed by the file system for a file name component.
SerialNumber Property | Returns the partition's serial number.
VolumeLabel Property | Returns the volume label of the partition.

Relationships

A ClusPartition object:

  • Is obtained from ClusPartitions.Item.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Management Objects


ClusPartition.DeviceName

The DeviceName property returns the device name of a storage class resource partition.

strDeviceName = object.DeviceName

Parameters

strDeviceName
String that receives the device name of the partition.
object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Remarks

The device name returned contains no backslashes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition


ClusPartition.FileSystem

The FileSystem property returns the name of the file system residing on a storage class resource partition (FAT, HPFS, NTFS, etc.).

strFileSystem = object.FileSystem

Parameters

strFileSystem
String that receives the file system of the storage class resource.
object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition, ClusPartition.FileSystemFlags


ClusPartition.FileSystemFlags

The FileSystemFlags property returns flags describing the file system of a storage class resource partition.

lngFileSystemFlags = object.FileSystemFlags

Parameters

lngFileSystemFlags
Long that receives the file system flags of the partition. The following flags are valid.
Flag | Description
FS_CASE_IS_PRESERVED | The file system preserves the case of file names when it places a name on the storage class resource.
FS_CASE_SENSITIVE | The file system supports case-sensitive file names.
FS_UNICODE_STORED_ON_DISK | The file system supports Unicode in file names as they appear on the storage class resource.
FS_PERSISTENT_ACLS | The file system preserves and enforces access control lists (ACLs).

object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition


ClusPartition.Flags

The Flags property returns the flags set for a storage class resource partition.

lFlags = object.Flags

Parameters

lFlags
Long that receives the flags of the storage class resource. The following values are valid.
Value | Constant | Description
1 | CLUSPROP_PIFLAG_STICKY | The drive letter is sticky.
2 | CLUSPROP_PIFLAG_REMOVABLE | The storage class resource is removable.
4 | CLUSPROP_PIFLAG_USABLE | The storage class resource is formatted with a file system that is usable by the Cluster service.

object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Remarks

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition


ClusPartition.MaximumComponentLength

The MaximumComponentLength property returns the maximum component length of a storage class resource partition.

lngMaximumComponentLength = object.MaximumComponentLength

Parameters

lngMaximumComponentLength
Long that receives the maximum component length of the partition.
object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Remarks

The maximum component length is the maximum number of characters allowed between backslashes in a file or path name.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition


ClusPartition.SerialNumber

The SerialNumber property returns the serial number of a storage class resource partition.

lSerialNumber = object.SerialNumber

Parameters

lSerialNumber
Long receiving the serial number of the partition.
object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition


ClusPartition.VolumeLabel

The VolumeLabel property returns the volume label of a storage class resource partition.

strVolumeLabel = object.VolumeLabel

Parameters

strVolumeLabel
String that receives the volume label of the partition.
object
Object expression that resolves to a ClusPartition object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPartition


ClusScsiAddress Object

The ClusScsiAddress object provides access to SCSI information about a Physical Disk.

Properties and Methods

Method or property | Description
Lun Property | Returns the Lun of the disk.
PathId Property | Returns the path ID of the disk.
PortNumber Property | Returns the port ID of the disk.
TargetId Property | Returns the target ID of the disk.

Relationships

A ClusScsiAddress object:

• Is obtained from ClusDisk.ScsiAddress.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.


ClusScsiAddress.Lun

The Lun property returns the SCSI Lun of the Physical Disk.

varLun = object.Lun

Parameters

varLun
A variant that receives the Lun of the disk.
object
Object expression that resolves to a ClusScsiAddress object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusScsiAddress, ClusScsiAddress.PathId, ClusScsiAddress.PortNumber, ClusScsiAddress.TargetId


ClusScsiAddress.PathId

The PathId property returns the SCSI path ID of the Physical Disk.

varPathId = object.PathId

Parameters

varPathId
A variant that receives the path ID of the disk.
object
Object expression that resolves to a ClusScsiAddress object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusScsiAddress, ClusScsiAddress.Lun, ClusScsiAddress.PortNumber, ClusScsiAddress.TargetId


ClusScsiAddress.PortNumber

The PortNumber property returns the SCSI port number of the Physical Disk.

varPortNumber = object.PortNumber

Parameters

varPortNumber
A variant that receives the port number of the disk.
object
Object expression that resolves to a ClusScsiAddress object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusScsiAddress, ClusScsiAddress.Lun, ClusScsiAddress.PathId, ClusScsiAddress.TargetId


ClusScsiAddress.TargetId

The TargetId property returns the SCSI target ID of the Physical Disk.

varTargetId = object.TargetId

Parameters

varTargetId
A variant that receives the target ID of the disk.
object
Object expression that resolves to a ClusScsiAddress object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusScsiAddress, ClusScsiAddress.Lun, ClusScsiAddress.PathId, ClusScsiAddress.PortNumber


Group Management Objects

Group management objects support operations on individual groups, their properties, and related objects.

  • ClusResGroup Object
  • ClusResGroupPreferredOwnerNodes Collection
  • ClusResGroupResources Collection

Note The Cluster Automation Server originally used the term resource group instead of the term group. Therefore, all of the group-related object names start with ClusResGroup rather than ClusGroup.


ClusResGroup Object

A ClusResGroup object enables operations on a group, its properties, and related objects. Use ClusResGroup to move groups between nodes, bring groups online and offline, access the resources in the group, and perform other group-related tasks.

Properties and Methods

Method or property | Description
Cluster Property | Returns the cluster associated with a group.
CommonProperties Property | Returns a ClusProperties collection containing the group's read/write common properties.
CommonROProperties Property | Returns a ClusProperties collection containing the group's read-only common properties.
Delete Method | Deletes a group from the collection.
Move Method | Moves a group to the most preferred possible node.
Name Property | Read/write property that sets the name of a group.
Offline Method | Takes a group offline.
Online Method | Brings a group online.
OwnerNode Property | Returns a group's node.
PreferredOwnerNodes Property | Returns a ClusResGroupPreferredOwnerNodes collection providing access to the nodes that belong in a group's preferred owner list.
PrivateProperties Property | Returns a ClusProperties collection containing the group's read/write private properties.
PrivateROProperties Property | Returns a ClusProperties collection containing the group's read-only private properties.
Resources Property | Returns a ClusResGroupResources collection providing access to the resources in a group.
State Property | Returns the state of a group.

Relationships

A ClusResGroup object:

  • Is obtained from ClusResGroups.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Group Management Objects


ClusResGroup.Cluster

The Cluster property returns the cluster associated with the group.

Set objCluster = object.Cluster

Parameters

object
Object expression that resolves to a ClusResGroup object.
objCluster
A Cluster object that receives the group's cluster.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup, Cluster


ClusResGroup.CommonProperties

The CommonProperties property returns the read/write common properties of a group.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a ClusResGroup object.
colClusProperties
A ClusProperties collection that receives the read/write common properties of the group.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup


ClusResGroup.CommonROProperties

The CommonROProperties property returns the read-only common properties of a group.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a ClusResGroup object.
colClusProperties
A ClusProperties collection that receives the read-only common properties of the group.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResGroup


ClusResGroup.Delete

The Delete method deletes a group from the cluster.

object.Delete

Parameters

object
Object expression that resolves to a ClusResGroup object.

Remarks

A group cannot be deleted while it contains resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup


ClusResGroup.Move

The Move method moves a group and all of its resources from one node to another.

varPending = object.Move( varTimeout [ ,objNode ] )

Parameters

object
Object expression that resolves to a ClusResGroup object.
varTimeout
A Variant that specifies how long (in seconds) the method should wait for the move to complete before setting varPending to TRUE and returning.
objNode
Optional. A ClusNode object that represents the node to which the group should be moved. If no node is specified, the Move method moves the group to the best available node.
varPending
A Variant that is set to TRUE if the request is still pending.

Remarks

Unless a node is specified, Move automatically selects the destination node on the basis of the following data:

  • The set of currently active nodes.
  • The group's prioritized list of preferred owner nodes (see ClusResGroup.PreferredOwnerNodes).
  • The set of nodes listed as possible owners by all resources in the group. To access the possible owners list for a resource, use the ClusResource.PossibleOwnerNodes property.

Move selects the most preferred node from the set of possible active nodes. If no active nodes are listed as possible owners by all resources in the group, Move fails.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroup


ClusResGroup.Name

The Name property retrieves or sets the name of a group.

object.Name [ = strName ]

Parameters

object
Object expression that resolves to a ClusResGroup object.
strName
String containing the new name for the group.

Access

Read/write

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup


ClusResGroup.Offline

The Offline method takes a group offline.

object.Offline( varTimeout, varPending )

Parameters

object
Object expression that resolves to a ClusResGroup object.
varTimeout
A Variant that specifies how long (in seconds) the method should wait for the group to come offline before setting varPending to TRUE and returning.
varPending
A Variant set to TRUE if the request is still pending.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup, Offline


ClusResGroup.Online

The Online method brings a group online.

varPending = object.Online( varTimeout[ , objNode  )

Parameters

object
Object expression that resolves to a ClusResGroup object.
varTimeout
A Variant that specifies how long (in seconds) the method should wait for the group to come online before setting varPending to TRUE and returning.
objNode
Optional ClusNode object specifying the node on which the group should be brought online. If no node is specified, the Online method brings the group online on the best possible node.
varPending
A Variant set to TRUE if the request is still pending.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroup, Online


ClusResGroup.OwnerNode

The OwnerNode property returns the node currently hosting a group.

Set objNode = object.OwnerNode

Parameters

object
Object expression that resolves to a ClusResGroup object.
objNode
A ClusNode object that receives the node that is currently hosting the group.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroup


ClusResGroup.PreferredOwnerNodes

The PreferredOwnerNodes property returns a ClusResGroupPreferredOwnerNodes collection providing access to all nodes on which a group prefers to run.

Set colGroupOwners = object.PreferredOwnerNodes

Parameters

object
Object expression that resolves to a ClusResGroup object.
colGroupOwners
A ClusResGroupPreferredOwnerNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes, ClusResGroup


ClusResGroup.PrivateProperties

The PrivateProperties property returns the read/write private properties of a group.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a ClusResGroup object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the group.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResGroup


ClusResGroup.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a group.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a ClusResGroup object.
colClusProperties
ClusProperties collection to receive the read-only private properties of the group.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResGroup


ClusResGroup.Resources

The Resources property provides access to the resources in a group.

Set colResources = object.Resources

Parameters

object
Object expression that resolves to a ClusResGroup object.
colResources
ClusResGroupResources collection that receives the resources in the group.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupResources, ClusResGroup


ClusResGroup.State

The State property returns the state of a group.

State = object.State

Parameters

object
Object expression that resolves to a ClusResGroup object.
State
Object that receives contains the group's current state.

Access

Read-only

Remarks

The State property returns one of the following values.

Value | Constant | Description
-1 | ClusterGroupStateUnknown | The State property has failed; the state of the group is unknown.
0 | ClusterGroupOnline | All of the resources in the group are online.
1 | ClusterGroupOffline | All of the resources in the group are offline or there are no resources in the group.
2 | ClusterGroupFailed | At least one resource in the group has failed.
3 | ClusterGroupPartialOnline | At least one resource in the group is online. No resources are pending or failed.
4 | ClusterGroupPending | At least one resource in the group is in a pending state. There are no failed resources.

To retrieve the state of a node or resource, use the State property of the appropriate ClusNode or ClusResource object.

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroup, ClusResource


ClusResGroupPreferredOwnerNodes Collection

The ClusResGroupPreferredOwnerNodes collection provides access to the nodes that belong to the preferred owner list for a group.

Properties and Methods

Method or property | Description
AddItem Method | Adds a node to the preferred owners list.
Count Property | Returns the number of objects in the collection.
InsertItem Method | Adds a node to the preferred owners list.
Item Property | Returns a single node from the collection.
Modified Property | Reports whether any of the nodes in the collection have changed.
Refresh Method | Refreshes the data in the collection.
RemoveItem Method | Removes a node from preferred owners list.
SaveChanges Method | Saves the list of preferred owner nodes to the cluster database.

Relationships

A ClusResGroupPreferredOwnerNodes collection:

  • Contains ClusNode objects.
  • Is obtained from ClusResGroup.PreferredOwnerNodes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Group Management Objects


ClusResGroupPreferredOwnerNodes.AddItem

The AddItem method adds a node to the ClusResGroupPreferredOwnerNodes collection.

object.AddItem( objNode )

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.
objNode
A ClusNode object to be added to the collection.

Remarks

Adding a node to a group's ClusResGroupPreferredOwnerNodes collection means that the node is listed as a preferred owner node for the group.

The AddItem method always adds a node at the end of the list, giving it the lowest priority. To add a node and specify its priority in the list, see ClusResGroupPreferredOwnerNodes.InsertItem.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroupPreferredOwnerNodes, ClusResGroupPreferredOwnerNodes.InsertItem


ClusResGroupPreferredOwnerNodes.Count

The Count property returns the number of nodes in the ClusResGroupPreferredOwnerNodes collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of nodes in the collection.
object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes


ClusResGroupPreferredOwnerNodes.InsertItem

The InsertItem method adds a node to the ClusResGroupPreferredOwnerNodes collection.

object.InsertItem( objNode, lPosition )

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.
objNode
A ClusNode object to be added to the collection.
lPosition
Optional. Long that identifies the location within the collection to add the new node. Highly preferred, high-priority nodes have low position values (that is, they occur first in the list).

Remarks

Adding a node to a group's ClusResGroupPreferredOwnerNodes collection means that the node is listed as a preferred owner node for the group. Use lPosition to specify an order of preference, with low values corresponding to highly preferred, high-priority nodes.

To add a node to the end of the list, use the ClusResGroupPreferredOwnerNodes.AddItem method.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes, ClusResGroupPreferredOwnerNodes.AddItem, ClusNode


ClusResGroupPreferredOwnerNodes.Item

The Item property returns a single node from the ClusResGroupPreferredOwnerNodes collection.

Set objNode = object.Item( varIndex )

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.
varIndex
A Variant that identifies a node in the collection by name or numeric index. Index numbers range from 1 to object. Count.
objNode
A ClusNode object that receives the specified node.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroupPreferredOwnerNodes, ClusResGroupPreferredOwnerNodes.Count


ClusResGroupPreferredOwnerNodes.Modified

The Modified property reports whether the an instance of the ClusResGroupPreferredOwnerNodes collection has been modified since it was created.

object.Modified( varFlag )

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.
varFlag
A Variant that receives a flag that indicates whether the collection has been modified. If Flag is set to TRUE, the collection has been modified. If Flag is set to FALSE, the collection has not been modified.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes


ClusResGroupPreferredOwnerNodes.Refresh

The Refresh method refreshes the data in the ClusResGroupPreferredOwnerNodes collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.

Remarks

Any unsaved changes to the collection will be lost when the Refresh method is called. Use the ClusResGroupPreferredOwnerNodes.SaveChanges method to save changes to the collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes


ClusResGroupPreferredOwnerNodes.RemoveItem

The RemoveItem method removes a node from the ClusResGroupPreferredOwnerNodes collection.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.
varIndex
A Variant identifying the node to be removed either by name or numeric index. Index numbers range from 1 to ClusResGroupPreferredOwnerNodes.Count.

Remarks

Removing a node from a group's ClusResGroupPreferredOwnerNodes collection removes the node from the group's preferred owners list.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes


ClusResGroupPreferredOwnerNodes.SaveChanges

The SaveChanges method saves the list of preferred owner nodes to the cluster database.

object.SaveChanges

Parameters

object
Object expression that resolves to a ClusResGroupPreferredOwnerNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupPreferredOwnerNodes


ClusResGroupResources Collection

The ClusResGroupResources collection provides access to the resources that are current members of a group and allows a resource to be added to or deleted from the group.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
CreateItem Method | Creates a new cluster resource and adds it to the group.
DeleteItem Method | Removes a resource from the group and deletes it from the cluster.
Item Property | Returns a single resource from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResGroupResources collection:

  • Contains ClusResource objects.
  • Is obtained from ClusResGroup.Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Group Management Objects


ClusResGroupResources.Count

The Count property returns the number of resources in the ClusResGroupResources collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of resources in the collection.
object
Object expression that resolves to a ClusResGroupResources collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupResources


ClusResGroupResources.CreateItem

The CreateItem method creates a new resource in the cluster and adds it to the ClusResGroupResources collection.

Set objResource =  object.CreateItem( ResourceName, ResourceType, Flag )

Parameters

object
Object expression that resolves to a ClusResGroupResources collection.
objResource
Object that receives ClusResource object that represents the newly added resource.
ResourceName
String containing the name of the resource to add.
ResourceType
String containing the type the resource to add.
Flag
Value indicating how to create the resource. Flag can be set to:

CLUSTER_RESOURCE_SEPARATE_MONITOR

This value indicates that a separate Resource Monitor should be assigned to the newly created resource.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupResources, ClusResource


ClusResGroupResources.DeleteItem

The DeleteItem method removes a resource from a ClusResGroupResources collection and deletes it from the cluster.

object.DeleteItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResGroupResources collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupResources


ClusResGroupResources.Item

The Item property returns a single resource from the ClusResGroupResources collection.

Set objResource =  object.Item( varIndex )

Parameters

objResource
A ClusResource object that receives the specified resource.
object
Object expression that resolves to a ClusResGroupResources collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupResources, ClusResource, ClusResGroupResources.Count


ClusResGroupResources.Refresh

The Refresh method refreshes the data in the ClusResGroupResources collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResGroupResources collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroupResources


Network Management Objects

Network management objects support operations on individual networks, their properties, and related objects.

  • ClusNetwork Object
  • ClusNetworkNetInterfaces Collection


ClusNetwork Object

The ClusNetwork object enables operations on a network, its properties, and related objects.

Properties and Methods

Method or property | Description
Cluster Property | Returns a Cluster object providing access to the cluster operating over the network.
CommonProperties Property | Returns a ClusProperties collection containing the network's read/write common properties.
CommonROProperties Property | Returns a ClusProperties collection containing the network's read-only common properties.
Name Property | Returns the name of the network.
NetInterfaces Property | Returns a ClusNetworkNetInterfaces collection providing access to the network interfaces in the network.
NetworkID Property | Returns the network identifier for the network.
PrivateProperties Property | Returns a ClusProperties collection containing the network's read/write private properties.
PrivateROProperties Property | Returns a ClusProperties collection containing the network's read-only private properties.
State Property | Returns the state of the network.

Relationships

A ClusNetwork object:

  • Is obtained from ClusNetworks.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Network Management Objects


ClusNetwork.Cluster

The Cluster property returns a Cluster object providing access to the cluster that owns the network.

Set objCluster = object.Cluster

Parameters

objCluster
A Cluster object that receives the cluster.
object
Object expression that resolves to a ClusNetwork object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, Cluster


ClusNetwork.CommonProperties

The CommonProperties property returns the read/write common properties of a network.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a ClusNetwork object.
colClusProperties
A ClusProperties collection that receives the read/write common properties of the network.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Cluster, ClusProperties


ClusNetwork.CommonROProperties

The CommonROProperties property returns the read-only common properties of a network.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a ClusNetwork object.
colClusProperties
A ClusProperties collection that receives the read-only common properties of the network.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, ClusProperties


ClusNetwork.Name

The Name property retrieves or sets the name of a network.

object.Name [ = strName ]

Parameters

object
Object expression that resolves to a ClusNetwork object.
strName
String that receives the new network name.

Access

Write-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, ClusNetwork.Name, Cluster


ClusNetwork.NetInterfaces

The NetInterfaces property returns a ClusNetworkNetInterfaces collection providing access to the network interfaces in the network.

Set colNetworkNetInterfaces = object.NetInterfaces

Parameters

colNetworkNetInterfaces
A ClusNetworkNetInterfaces collection.
object
Object expression that resolves to a ClusNetwork object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, ClusNetworkNetInterfaces, Cluster Object


ClusNetwork.NetworkID

The NetworkID property returns the unique network identifier for a network.

strNetworkID = object.NetworkID

Parameters

object
Object expression that resolves to a ClusNetwork object.
strNetworkID
String that receives the GUID identifying the network.

Access

Read-only

Remarks

TheNetworkID of a network is stored in the cluster database under HKEY_LOCAL_MACHINE\Cluster\Networks\.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

CLUSCTL_NETWORK_GET_ID, ClusNetwork


ClusNetwork.PrivateProperties

The PrivateProperties property returns the read/write private properties of a network.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a ClusNetwork object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the network.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, ClusProperties


ClusNetwork.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a network.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a ClusNetwork object.
colClusProperties
A ClusProperties collection to receive the read-only private properties of the network.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetwork, ClusProperties


ClusNetwork.State

The State property returns the state of a network.

lState = object.State

Parameters

object
Object expression that resolves to a ClusNetwork object.
State
Long that receives a constant representing the network's current state. One of the following values is returned.
Value | Constant | Description
-1 | ClusterNetworkStateUnknown | The State property has failed; the state of the network is unknown.
0 | ClusterNetworkUnavailable | State information for the network is unavailable.
1 | ClusterNetworkDown | The network is not operational; none of the nodes on the network can communicate.
2 | ClusterNetworkPartitioned | The network is operational, but two or more nodes on the network cannot communicate. Typically a path-specific problem has occurred.
3 | ClusterNetworkUp | The network is operational; all of the nodes in the cluster can communicate.

Access

Read-only

Remarks

for information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

GetClusterNetworkState, ClusNetwork


ClusNetworkNetInterfaces Collection

A ClusNetworkNetInterfaces collection provides access to the network interfaces available to a network.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single network interface from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusNetworkNetInterfaces collection:

  • Contains ClusNetInterface objects.
  • Is obtained from ClusNetwork.NetInterfaces.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Network Management Objects


ClusNetworkNetInterfaces.Count

The Count property returns the number of objects in the ClusNetworkNetInterfaces collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusNetworkNetInterfaces collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetworkNetInterfaces


ClusNetworkNetInterfaces.Item

The Item property retrieves a single network interface from a ClusNetworkNetInterfaces collection.

Set objNetInterface = object.Item( varIndex )

Parameters

objNetInterface
A ClusNetInterface object that receives the specified network interface.
object
Object expression that resolves to a ClusNetworkNetInterfaces collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetworkNetInterfaces, ClusNetInterface, ClusNetworkNetInterfaces.Count


ClusNetworkNetInterfaces.Refresh

The Refresh method refreshes the data in the ClusNetworkNetInterfaces collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusNetworkNetInterfaces collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetworkNetInterfaces


Network Interface Management Objects

Network interface management objects support operations on individual network interfaces.

  • ClusNetInterface Object


ClusNetInterface Object

The ClusNetInterface object enables operations on a network interface, its properties, and related objects.

Properties and Methods

Method or property | Description
Cluster Property | Returns a Cluster object providing access to the cluster that owns the network interface.
CommonProperties Property | Returns a ClusProperties collection containing the network interface's read/write common properties.
CommonROProperties Property | Returns a ClusProperties collection containing the network interface's read-only common properties.
Name Property | Returns the name of the network interface.
PrivateProperties Property | Returns a ClusProperties collection containing the network interface's read/write private properties.
PrivateROProperties Property | Returns a ClusProperties collection containing the network interface's read-only private properties.
State Property | Returns the state of the network interface.

Relationships

A ClusNetInterface object:

  • Is obtained from the following collections:

    ClusNetInterfaces

    ClusNetworkNetInterfaces

    ClusNodeNetInterfaces

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Network Interface Management Objects


ClusNetInterface.Cluster

The Cluster property returns a Cluster object providing access to the cluster associated with a network interface.

Set objCluster = object.Cluster

Parameters

objCluster
A Cluster object that receives the cluster associated with the network interface.
object
Object expression that resolves to a ClusNetInterface object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, Cluster Object


ClusNetInterface.CommonProperties

The CommonProperties property returns the read/write common properties of a network interface.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a ClusNetInterface object.
colClusProperties
A ClusProperties collection that receives the read/write common properties of the network interface.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, ClusProperties


ClusNetInterface.CommonROProperties

The CommonROProperties property returns the read-only common properties of a network interface.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a ClusNetInterface object.
colClusProperties
A ClusProperties collection that receives the read-only common properties of the network interface.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, ClusProperties


ClusNetInterface.Name

The Name property retrieves or sets the name of a network interface.

object.Name [ = strName ]

Parameters

object
Object expression that resolves to a ClusNetInterface object.
strName
String that specifies the new network interface name.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, Cluster


ClusNetInterface.PrivateProperties

The PrivateProperties property returns the read/write private properties of a network interface.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a ClusNetInterface object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the network interface.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, ClusProperties


ClusNetInterface.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a network interface.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a ClusNetInterface object.
colClusProperties
A ClusProperties collection to receive the read-only private properties of the network interface.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, ClusProperties


ClusNetInterface.State

The State property returns information about the state of a network interface.

lState = object.State

Parameters

object
Object expression that resolves to a ClusNetInterface object.
lState
Long representing the network interface's state with one of the following values.
Value | Constant | Description
-1 | ClusterNetInterfaceStateUnknown | The State property failed; the state of the network interface is unknown.
0 | ClusterNetInterfaceUnavailable | State information for the network interface is unavailable.
1 | ClusterNetInterfaceUnreachable | None of the active nodes in the cluster can access the network interface.
2 | ClusterNetInterfaceFailed | The network interface is not operational; typically a hardware failure has occurred.
3 | ClusterNetInterfaceUp | The network interface is operational.

Access

Read-only

Remarks

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, GetClusterNetworkState


Node Management Objects

Node management objects support operations on individual nodes, their properties, and related objects.

  • ClusNode Object
  • ClusNodeNetInterfaces Collection


ClusNode Object

The ClusNode object enables operations on a node, its properties, and related objects.

Method or property | Description
Cluster Property | Returns a Cluster object providing access to the cluster associated with the node.
CommonProperties Property | Returns a ClusProperties collection containing the node's read/write common properties.
CommonROProperties Property | Returns a ClusProperties collection containing the node's read-only common properties.
Evict Method | Removes a node from the cluster.
NetInterfaces Property | Returns a ClusNodeNetInterfaces collection providing access to the network interfaces available to the node.
NodeID Property | Returns the identifier of the node.
Pause Method | Temporarily suspends the cluster activity of the node.
PrivateProperties Property | Returns a ClusProperties collection containing the node's read/write private properties.
PrivateROProperties Property | Returns a ClusProperties collection containing the node's read-only private properties.
ResourceGroups Property | Returns a ClusResGroups collection providing access to the groups that are currently being hosted by the node.
Resume Method | Resumes the cluster activity of the node.
State Property | Returns the state of the node.

Relationships

A ClusNode object:

  • Is obtained from the following collections:

    ClusNodes

    ClusResGroupPreferredOwnerNodes

    ClusResPossibleOwnerNodes

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Node Management Objects


ClusNode.Cluster

The Cluster property returns a Cluster object providing access to the cluster associated with a node.

Set objCluster = object.Cluster

Parameters

objCluster
A Cluster object.
object
Object expression that resolves to a ClusNode object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, Cluster


ClusNode.CommonProperties

The CommonProperties property returns the read/write common properties of a node.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a ClusNode object.
colClusProperties
A ClusProperties collection that receives the read/write common properties of the node.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusProperties ClusNode.CommonROProperties


ClusNode.CommonROProperties

The CommonROProperties property returns the read-only common properties of a node.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a ClusNode object.
colClusProperties
A ClusProperties collection that receives the read-only common properties of the node.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusProperties, ClusNode.CommonProperties


ClusNode.Evict

The Evict method removes a node from the cluster.

object.Evict

Parameters

object
Object expression that resolves to a ClusNode object.

Remarks

An evicted node is no longer a member of the cluster. The Cluster service must be reinstalled on the node to reestablish the node's cluster membership.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, Cluster Object


ClusNode.Name

The Name property retrieves the name of a node.

object.Name = strName

Parameters

object
Object expression that resolves to a ClusNode object.
strName
String containing the new node name.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode


ClusNode.NetInterfaces

The NetInterfaces property returns a ClusNodeNetInterfaces collection providing access to the network interfaces installed on a node.

Set colNodeNetInterfaces = object.NetInterfaces

Parameters

object
Object expression that resolves to a ClusNode object.
colNodeNetInterfaces
A ClusNodeNetInterfaces collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusNodeNetInterfaces


ClusNode.NodeID

The NodeID property returns the unique identifier of a cluster node.

strNodeID = object.NodeID

Parameters

object
Object expression that resolves to a ClusNode object.
strNodeID
String that receives the node's unique identifier.

Access

Read-only

Remarks

The NodeID of a node is stored under HKEY_LOCAL_MACHINE\Cluster\Node\.

NodeID is not accessible through Cluster Administrator.

Changing the name of a node does not affect its NodeID.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

CLUSCTL_NODE_GET_ID, ClusNode


ClusNode.Pause

The Pause method suspends the cluster activity of a node.

object.Pause

Parameters

object
Object expression that resolves to a ClusNode object.

Remarks

Use the ClusNode.Resume method to return a paused node to active status.

While a node is paused, groups cannot be moved to the node either through the failover process or administrator action. A paused node returns ClusterNodePaused as the value for its ClusNode.State property.

Groups that are owned by a paused node remain owned by that node. A paused node's groups and resources can be taken offline, but they cannot be brought online. Because the paused state is persistent, a paused node continues to be paused when it is rebooted.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusNode.Resume, ClusNode.State


ClusNode.PrivateProperties

The PrivateProperties property returns the read/write private properties of a node.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a ClusNode object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the node.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusProperties


ClusNode.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a node.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a ClusNode object.
colClusProperties
A ClusProperties collection to receive the read-only private properties of the node.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusProperties


ClusNode.ResourceGroups

The ResourceGroups property returns a ClusResGroups collection providing access to the groups currently owned by the node.

Set colResourceGroups = object.ResourceGroups

Parameters

colResourceGroups
A ClusResGroups collection.
object
Object expression that resolves to a ClusNode object.

Access

Read-only

Remarks

To retrieve information about all of the groups in the cluster, use the Cluster.ResourceGroups property.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResGroups, Cluster.ResourceGroups


ClusNode.Resume

The Resume method resumes the cluster activity of a node after it has been paused by the ClusNode.Pause method.

object.Resume

Parameters

object
Object expression that resolves to a ClusNode object.

Remarks

When a node resumes cluster activity after it has been paused, it returns ClusterNodeUp as the value for its ClusNode.State property.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusNode.Pause, ClusNode.State


ClusNode.State

The State property retrieves the state of a node.

lState = object.State

Parameters

object
Object expression that resolves to a ClusNode object.
lState
Long that receives one of the following values describes the node's current state.
Value | Constant | Description
-1 | ClusterNodeStateUnknown | The State property has failed; the state of the node is unknown.
0 | ClusterNodeUp | Node is online.
1 | ClusterNodeDown | Node is offline.
2 | ClusterNodePaused | Node has temporarily suspended activity and is probably undergoing maintenance.
3 | ClusterNodeJoining | Node is attempting to join a cluster.

Access

Read-only

Remarks

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode


ClusNodeNetInterfaces Collection

A ClusNodeNetInterfaces collection provides access to the network interfaces installed in a node.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single node from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusNodeNetInterfaces collection:

  • Contains ClusNetInterface objects.
  • Is obtained from ClusNode.NetInterfaces.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Node Management Objects


ClusNodeNetInterfaces.Count

The Count property returns the number of objects in the ClusNodeNetInterfaces collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusNodeNetInterfaces collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNodeNetInterfaces


ClusNodeNetInterfaces.Item

The Item property returns a single network interface from a ClusNodeNetInterfaces collection.

Set objNetInterface = object.Item( varIndex )

Parameters

objNetInterface
A ClusNetInterface object that receives the specified network interface.
object
Object expression that resolves to a ClusNodeNetInterfaces collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNetInterface, ClusNodeNetInterfaces, ClusNodeNetInterfaces.Count


ClusNodeNetInterfaces.Refresh

The Refresh method refreshes the data in the ClusNodeNetInterfaces collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusNodeNetInterfaces collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNodeNetInterfaces


Property Management Objects

Property management objects store and retrieve properties for groups, networks, network interfaces, nodes, resources, and resource types.

  • ClusProperties Collection
  • ClusProperty Object
  • ClusPropertyValues Collection
  • ClusPropertyValue Object
  • ClusPropertyValueData Collection


ClusProperties Collection

A ClusProperties collection provides access to the properties of a cluster object, allowing individual property values to be changed.

Properties and Methods

Method or property | Description
Common Property | Indicates whether the properties in the collection are common properties.
Count Property | Returns the number of properties in the collection.
CreateItem Method | Creates a new ClusProperty object and adds it to the collection.
Item Property | Returns a single property from the collection.
Modified | Indicates whether any properties in the collection have been added, removed, or modified since the last Refresh or SaveChanges operation.
Private Property | Indicates whether the properties in the collection are private properties.
ReadOnly Property | Indicates whether the properties in the collection are read-only properties.
Refresh Method | Updates the collection with current property data from the cluster database.
UseDefaultValue Method | Deletes a property from the collection.
SaveChanges Method | Saves all property data in the collection to the cluster database.

Remarks

A ClusProperties collection is similar to a property list in that the data in the collection is a local copy of real data stored in the cluster database. When an instance of the ClusProperties collection is created, it receives a snapshot of the stored data. Changes to the ClusProperties collection do not take effect in the cluster until the SaveChanges method is invoked. Similarly, changes to the cluster database are not reflected in the collection until the Refresh method is called.

Relationships

A ClusProperties collection:

  • Contains ClusProperty objects.
  • Can be obtained from any of the following objects:

    ClusNetwork

    ClusNetInterface

    ClusNode

    ClusResGroup

    ClusResource

    ClusResType

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusProperties.Common

The Common property indicates whether the properties in a ClusProperties collection are common properties.

varContainsCommonProps = object.Refresh

Parameters

varContainsCommonProps
A Variant set to one of the following values.
Value | Meaning
VARIANT_TRUE | The collection consists entirely of common properties.
VARIANT_FALSE | The collection contains at least one private or unknown property.

object
Object expression that resolves to a ClusProperties collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusProperties.Private, ClusProperties.ReadOnly


ClusProperties.Count

The Count property returns the number of properties in the ClusProperties collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusProperties collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties


ClusProperties.CreateItem

The CreateItem method creates a new ClusProperty object and adds it to the ClusProperties collection.

Set objProperty =  object.CreateItem( strName, varValue )

Parameters

objProperty
A ClusProperty object that receives the added property.
object
Object expression that resolves to a ClusProperties collection.
strName
String. The name of the new property.
varValue
A Variant specifying the initial value of the new property.

Remarks

The CreateItem method causes a modification to the collection. For more information, see ClusProperties.Modified.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusProperty


ClusProperties.Item

The Item property returns a single property from a ClusProperties collection.

Set objProperty =  object.Item( varIndex )

Parameters

objProperty
A ClusProperty object that receives the specified propertie.
object
Object expression that resolves to a ClusProperties collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusProperty, ClusProperties.Count


ClusProperties.Modified

The Modified property indicates whether any properties in the ClusProperties collection have been added or removed, or if any properties have been changed, since the last ClusProperties.Refresh or ClusProperties.SaveChanges operation.

varModified = object.Modified

Parameters

varModified
A Variant set to one of the following values.
Value | Meaning
VARIANT_TRUE | At least one of the properties in the collection has been modified, added, or removed since the last ClusProperties.Refresh or ClusProperties.SaveChanges.
VARIANT_FALSE | None of the properties in the collection have been modified, added, or removed since the last ClusProperties.Refresh or ClusProperties.SaveChanges.

object
Object expression that resolves to a ClusProperties collection.

Remarks

To test whether a specific property has been modified, see ClusProperty.Modified.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusProperties.Refresh, ClusProperties.SaveChanges


ClusProperties.Private

The Private property indicates whether the properties in a ClusProperties collection are private properties.

varContainsPrivateProps = object.Refresh

Parameters

varContainsPrivateProps
A Variant set to one of the following values.
Value | Meaning
VARIANT_TRUE | The collection consists entirely of private properties.
VARIANT_FALSE | The collection contains at least one common or unknown property.

object
Object expression that resolves to a ClusProperties collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties


ClusProperties.ReadOnly

The ReadOnly property indicates whether the properties in a ClusProperties collection are read-only properties.

varContainsROProps = object.ReadOnly

Parameters

varContainsROProps
A Variant set to one of the following values.
Value | Meaning
VARIANT_TRUE | The collection consists entirely of read-only properties.
VARIANT_FALSE | The collection contains at least one read/write property.

object
Object expression that resolves to a ClusProperties collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties


ClusProperties.Refresh

The Refresh method reads the cluster database and updates the data in the ClusProperties collection to reflect the current cluster data.

object.Refresh

Parameters

object
Object expression that resolves to a ClusProperties collection.

Remarks

A ClusProperties collection contains a local copy of property data. The Refresh method updates the local copy with the current property data from the cluster. Any unsaved changes in the collection will be overwritten.

The Refresh method causes the ClusProperties.Modified property to return VARIANT_FALSE.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties


ClusProperties.UseDefaultValue

The UseDefaultValue method is used in conjunction with ClusProperties.SaveChanges to return a property to its default value.

object.UseDefaultValue( varIndex )

Parameters

object
Object expression that resolves to a ClusProperties collection.
varIndex
A Variant specifying a property by name or by numeric index.

Remarks

UseDefaultValue works in conjunction with ClusProperties.SaveChanges as follows:

  • UseDefaultValue sets the value of the property in the collection to empty and flags the property as "use default."
  • When the SaveChanges method is invoked, any property in the collection flagged as "use default" is not written to the cluster database. Instead, SaveChanges method clears the property value stored in the cluster database, causing the property to revert to its the hard-coded default value.
  • If SaveChanges is successful, it automatically calls ClusProperties.Refresh, which reads the default value from the cluster database into the collection.

The hard-coded default value of a property is defined by the Cluster service or by a resource DLL. The Cluster Properties reference section documents each of the properties defined by the Cluster service, including their default values.

The ClusProperties.Refresh method clears the "use default" flag without affecting cluster database.

Example Code

The following example uses UseDefaultValue to set all of an object's properties to their default values.

Option Explicit

Public Function RestoreDefaults(obj)
    Dim objProp
    Dim strOut

    For Each objProp in obj.CommonProperties
        objProp.UseDefaultValue
    Next
    objProp.CommonProperties.SaveChanges

    For Each objProp in obj.PrivateProperties
        objProp.UseDefaultValue
    Next
    objProp.PrivateProperties.SaveChanges

    For Each objProp in objProp.CommonProperties
        strOut = strOut & objProp.Name & " = " & _
                 CStr(objProp.Value) & vbCrLf
    Next

    For Each objProp in objProp.CommonProperties
        strOut = strOut & objProp.Name & " = " & _
                 CStr(objProp.Value) & vbCrLf
    Next

    WScript.Echo strOut

    Set objProp = Nothing

End Function

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties


ClusProperties.SaveChanges

The SaveChanges method updates the cluster database with the property data currently stored in the ClusProperties collection.

object.SaveChanges

Parameters

object
Object expression that resolves to a ClusProperties collection.

Remarks

A ClusProperties collection contains a local copy of property data. Changes to the data do not take effect in the cluster until ClusProperties.SaveChanges is called.

If the properties are successfully saved, ClusProperties.SaveChanges calls the ClusProperties.Refresh method.

The ClusProperties.SaveChanges method will fail if the properties in the collection are read-only.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties


ClusProperty Object

The ClusProperty object represents a single property within a ClusProperties collection.

Properties and Methods

Method or property | Description
Format Property | Returns or sets the format of the cluster object property.
Length Property | Returns the byte size of the cluster object property.
Modified Property | Indicates whether the value of the property has changed since the last Refresh or SaveChanges operation.
Name Property | Returns the name of the cluster object property.
Type Property | Returns or sets the type of the cluster object property.
Value Property | Returns or sets the property value of the cluster object property.
ValueCount Property | Returns the number of property values stored in the cluster object property.
Values Property | Returns a ClusPropertyValues collection containing all of the property values associated with the cluster object property.

Remarks

A ClusProperty object contains a local copy of real property data stored in the cluster database. Changes to the ClusProperty object do not take effect in the cluster until the parent ClusProperties.SaveChanges method is invoked. Similarly, changes to the cluster database are not reflected in the object until the ClusProperties.Refresh method is called.

Relationships

A ClusProperty object can only be obtained from a ClusProperties collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusProperty.Format

The ClusProperty.Format property returns or sets the format (data type) of a cluster object property.

object.Format [ = lFormat ]

Parameters

object
Object expression that resolves to a ClusProperty object.
lFormat
Long describing the format of the cluster object property. Msclus.h defines the following formats.
Value | Constant | Meaning
0 | CLUSPROP_FORMAT_UNKNOWN | Data is in an unknown format.
1 | CLUSPROP_FORMAT_BINARY | Data is a binary value.
2 | CLUSPROP_FORMAT_DWORD | Data is a DWORD value.
3 | CLUSPROP_FORMAT_SZ | Data is a null-terminated Unicode string.
4 | CLUSPROP_FORMAT_EXPAND_SZ | Data is a null-terminated Unicode string with unexpanded references to environment variables.
5 | CLUSPROP_FORMAT_MULTI_SZ | Data is an array of null-terminated Unicode strings.
6 | CLUSPROP_FORMAT_ULARGE_INTEGER | Data is an unsigned large integer.
7 | CLUSPROP_FORMAT_LONG | Data is a signed Long value.
8 | CLUSPROP_FORMAT_EXPANDED_SZ | Data is a null-terminated Unicode string with expanded references to environment variables.
9 | CLUSPROP_FORMAT_SECURITY_DESCRIPTOR | Data is a security descriptor.
10 | CLUSPROP_FORMAT_LARGE_INTEGER | Data is a signed large integer.
32768 | CLUSPROP_FORMAT_USER | Data is in a user-defined format.

Remarks

The ClusProperty.Format property corresponds to the wFormat member of a CLUSPROP_SYNTAX union.

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperty, ClusProperty.Type, CLUSPROP_SYNTAX


ClusProperty.Length

The ClusProperty.Length property returns the byte size of a cluster object property.

lLength = object.Length

Parameters

object
Object expression that resolves to a ClusProperty object.
lLength
Long that receives the length, in bytes, of the cluster object property.

Remarks

The ClusProperty.Length property corresponds to the cbLength member of a CLUSPROP_VALUE structure.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperty, CLUSPROP_VALUE


ClusProperty.Modified

The Modified property indicates whether the value of the property has changed since the last ClusProperties.Refresh or ClusProperties.SaveChanges operation.

varModified = object.Modified

Parameters

varModified
A Variant set to one of the following values.
Value | Meaning
VARIANT_TRUE | The property has been modified.
VARIANT_FALSE | The property has not been modified.

object
Object expression that resolves to ClusProperty object.

Remarks

A ClusProperty object operates on a local copy of cluster property data. Changes made to the local copy of the data do not take effect in the cluster until the parent ClusProperties collection invokes the ClusProperties.SaveChanges method. Any change to the local copy of the property value causes Modified to return VARIANT_TRUE.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusProperties, ClusProperties.Refresh, ClusProperties.SaveChanges


ClusProperty.Name

The ClusProperty.Name property returns the name of a cluster object property.

strPropertyName = object.Name

Parameters

object
Object expression that resolves to a ClusProperty object.
strPropertyName
String that receives the name of the cluster object property.

Access

Read-only

Remarks

The Name returned depends on the specific ClusProperty object and the associated cluster object. For detailed information about the properties associated with cluster objects, see Cluster Object Properties.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperty


ClusProperty.Type

The ClusProperty.Type property returns or sets the type of a cluster object property.

object.Type [ = lType ]

Parameters

object
Object expression that resolves to a ClusProperty object.
lType
Long describing the type of the cluster object property. Msclus.h defines the following types.
Value | Constant | Meaning
-1 | CLUSPROP_TYPE_UNKNOWN | Data is in an unknown format.
0 | CLUSPROP_TYPE_ENDMARK | Designates the data value as the last entry in a property list or value list.
1 | CLUSPROP_TYPE_LIST_VALUE | Describes a data value in a property list. For example, in the property list passed to a control code function for a property validation operation, CLUSPROP_TYPE_LIST_VALUE is the required type to be included with each property value.
2 | CLUSPROP_TYPE_RESCLASS | Describes resource class information. A resource class value is described with a CLUSPROP_RESOURCE_CLASS structure.
3 | CLUSPROP_TYPE_RESERVED1 | Reserved for future use.
4 | CLUSPROP_TYPE_NAME | Describes a data value used as a name, such as a property name. A name value is represented by a CLUSPROP_PROPERTY_NAME structure.
5 | CLUSPROP_TYPE_SIGNATURE | Describes a Signature property for a disk resource. A signature value is represented by a CLUSPROP_DISK_SIGNATURE structure.
6 | CLUSPROP_TYPE_SCSI_ADDRESS | Describes an Address property for an IP Address resource. A SCSI address value is represented by a CLUSPROP_SCSI_ADDRESS structure.
7 | CLUSPROP_TYPE_DISK_NUMBER | Describes the number value of a physical disk resource. A disk number value is represented by a CLUSPROP_DISK_NUMBER structure.
8 | CLUSPROP_TYPE_PARTITION_INFO | Describes a collection of information about a storage class resource, such as its device name and volume label. Partition data is represented by a CLUSPROP_PARTITION_INFO structure.
9 | CLUSPROP_TYPE_FTSET_INFO | Reserved for future use.
32768 | CLUSPROP_TYPE_USER | Data is in a user-defined format.

Remarks

The ClusProperty.Type property corresponds to the wType member of a CLUSPROP_SYNTAX union.

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperty, ClusProperty.Format, CLUSPROP_SYNTAX


ClusProperty.Value

The Value property sets or retrieves the locally stored copy of the property value of a cluster object property.

object.Value [ = varNewValue ]

Parameters

object
Object expression that resolves to a ClusProperty object.
varNewyValue
A Variant specifying the new object property value.

Remarks

A ClusProperty object operates on a local copy of cluster property data. Changes made to the local copy of the data do not take effect in the cluster until the parent ClusProperties collection invokes the ClusProperties.SaveChanges method. Any change to the local copy of the property value causes ClusProperties.Modified to return VARIANT_TRUE.

For detailed information about the properties associated with cluster objects, see Cluster Object Properties.

For cluster object properties that contain multiple values, use ClusProperty.ValueCount to find the number of property values, and ClusProperty.Values to obtain a ClusPropertyValues collection containing the property values.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusProperties.Modified, ClusProperties.SaveChanges, ClusProperty, ClusProperty.ValueCount, ClusProperty.Values, ClusPropertyValues


ClusProperty.ValueCount

The ClusProperty.Format property returns the number of property values associated with a cluster object property.

lValueCount = object.ValueCount

Parameters

object
Object expression that resolves to a ClusProperty object.
lLength
Long that receives the number of values assigned to the cluster object property.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperty, ClusProperty.Value, ClusProperty.Values


ClusProperty.Values

The Values property retrieves a ClusPropertyValues collection containing all of the property values associated with a multi-value cluster object property.

Set colPropValues = object.Values

Parameters

object
Object expression that resolves to a ClusProperty object.
colPropValues
A ClusPropertyValues collection to receive the property values.

Remarks

For detailed information about the properties associated with cluster objects, see Cluster Object Properties.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperty, ClusProperty.ValueCount, ClusProperty.Value


ClusPropertyValues Collection

The ClusPropertyValues collection contains all of the property values associated with a multi-value property, with each value represented by a ClusPropertyValue object.

Properties and Methods

Method or property | Description
Count Property | Returns the number of property values in the collection.
CreateItem Method | Adds a property value to the collection.
Item Property | Returns a single property value from the collection.
RemoveItem Method | Deletes a property value from the collection.

Relationships

A ClusPropertyValues collection:

  • Contains ClusPropertyValue objects.
  • Is obtained from ClusProperty.Values.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusPropertyValues.Count

The Count property returns the number of property values in the ClusPropertyValues collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusPropertyValues collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValues


ClusPropertyValues.CreateItem

The CreateItem method creates a new a property value and adds it to the ClusPropertyValues collection.

Set objPropertyValue =  object.CreateItem( strName, varValue )

Parameters

objPropertyValue
A ClusPropertyValue object that receives the new property value.
object
Object expression that resolves to a ClusPropertyValues collection.
strName
String. The name of the property to which this value applies.
varValue
A Variant specifying the new property value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValues, ClusProperty


ClusPropertyValues.Item

The Item property returns a single property value from a ClusPropertyValues collection.

Set objPropertyValue =  object.Item( varIndex )

Parameters

objPropertyValue
A ClusPropertyValue object that receives the specified property value.
object
Object expression that resolves to a ClusPropertyValues collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValues, ClusProperty, ClusPropertyValues.Count


ClusPropertyValues.RemoveItem

The RemoveItem method deletes a property value from a ClusPropertyValues collection.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusPropertyValues collection.
varIndex
A Variant specifying the property value to remove by name or by numeric index.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValues


ClusPropertyValue Object

The ClusPropertyValue object represents a single property value associated with a multi-value property. The property value consists of one or more data values.

Properties and Methods

Method or property | Description
Data Property | Returns a ClusPropertyValueData collection containing all of the data values for the property value.
Format Property | Returns or sets the format of the property value.
Length Property | Returns the byte size of the property value.
Type Property | Returns or sets the type of the property value.
Value Property | Returns or sets the value of the property value.
ValueCount Property | Returns the number of data values associated with the property value.

Relationships

A ClusPropertyValue object can only be obtained from ClusPropertyValues.Item.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusPropertyValue.Data

The Values property retrieves a ClusPropertyValueData collection containing all of the data values associated with a property value.

Set colPropValueData = object.Values

Parameters

object
Object expression that resolves to a ClusPropertyValue object.
colPropValues
A ClusPropertyValueData collection to receive the property values.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValue, ClusPropertyValue.DataCount, ClusPropertyValue.Value


ClusPropertyValue.DataCount

The ClusPropertyValue.DataCount property returns the number of data values currently assigned to a property value.

lValueCount = object.DataCount

Parameters

object
Object expression that resolves to a ClusPropertyValue object.
lLength
Long that receives the number of data values assigned to the property value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValue, ClusPropertyValue.Value


ClusPropertyValue.Format

The ClusPropertyValue.Format property returns or sets the format (data type) of a property value.

object.Format [ = lFormat ]

Parameters

object
Object expression that resolves to a ClusPropertyValue object.
lFormat
Long describing the format of the property value. Msclus.h defines the following formats.
Value | Constant | Meaning
0 | CLUSPROP_FORMAT_UNKNOWN | Data is in an unknown format.
1 | CLUSPROP_FORMAT_BINARY | Data is a binary value.
2 | CLUSPROP_FORMAT_DWORD | Data is a DWORD value.
3 | CLUSPROP_FORMAT_SZ | Data is a null-terminated Unicode string.
4 | CLUSPROP_FORMAT_EXPAND_SZ | Data is a null-terminated Unicode string with unexpanded references to environment variables.
5 | CLUSPROP_FORMAT_MULTI_SZ | Data is an array of null-terminated Unicode strings.
6 CLUSPROP_FORMAT_ULARGE_
INTEGER 		Data is an unsigned large integer.
7 | CLUSPROP_FORMAT_LONG | Data is a signed Long value.
8 | CLUSPROP_FORMAT_EXPANDED_SZ | Data is a null-terminated Unicode string with expanded references to environment variables.
9 | CLUSPROP_FORMAT_SECURITY_DESCRIPTOR | Data is a security descriptor.
10 CLUSPROP_FORMAT_LARGE_
INTEGER 		Data is a signed large integer.
32768 | CLUSPROP_FORMAT_USER | Data is in a user-defined format.

Remarks

The ClusPropertyValue.Format property corresponds to the wFormat member of a CLUSPROP_SYNTAX union.

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValue, ClusPropertyValue.Type, CLUSPROP_SYNTAX


ClusPropertyValue.Length

The ClusPropertyValue.Length property returns the byte size of a property value.

lLength = object.Length

Parameters

object
Object expression that resolves to a ClusPropertyValue object.
lLength
Long that receives the length, in bytes, of the property value.

Remarks

The ClusPropertyValue.Length property corresponds to the cbLength member of a CLUSPROP_VALUE structure.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValue, CLUSPROP_VALUE


ClusPropertyValue.Type

The ClusPropertyValue.Type property returns or sets the type of a property value.

object.Type [ = lType ]

Parameters

object
Object expression that resolves to a ClusPropertyValue object.
lType
Long describing the type of the property value. Msclus.h defines the following types.
Value | Constant | Meaning
-1 | CLUSPROP_TYPE_UNKNOWN | Data is in an unknown format.
0 | CLUSPROP_TYPE_ENDMARK | Designates the data value as the last entry in a property list or value list.
1 | CLUSPROP_TYPE_LIST_VALUE | Describes a data value in a property list. For example, in the property list passed to a control code function for a property validation operation, CLUSPROP_TYPE_LIST_VALUE is the required type to be included with each property value.
2 | CLUSPROP_TYPE_RESCLASS | Describes resource class information. A resource class value is described with a CLUSPROP_RESOURCE_CLASS structure.
3 | CLUSPROP_TYPE_RESERVED1 | Reserved for future use.
4 | CLUSPROP_TYPE_NAME | Describes a data value used as a name, such as a property name. A name value is represented by a CLUSPROP_PROPERTY_NAME structure.
5 | CLUSPROP_TYPE_SIGNATURE | Describes a Signature property for a disk resource. A signature value is represented by a CLUSPROP_DISK_SIGNATURE structure.
6 | CLUSPROP_TYPE_SCSI_ADDRESS | Describes an Address property for an IP Address resource. A SCSI address value is represented by a CLUSPROP_SCSI_ADDRESS structure.
7 | CLUSPROP_TYPE_DISK_NUMBER | Describes the number value of a physical disk resource. A disk number value is represented by a CLUSPROP_DISK_NUMBER structure.
8 | CLUSPROP_TYPE_PARTITION_INFO | Describes a collection of information about a storage class resource, such as its device name and volume label. Partition data is represented by a CLUSPROP_PARTITION_INFO structure.
9 | CLUSPROP_TYPE_FTSET_INFO | Reserved for future use.
32768 | CLUSPROP_TYPE_USER | Data is in a user-defined format.

Remarks

The ClusPropertyValue.Type property corresponds to the wType member of a CLUSPROP_SYNTAX union.

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValue, ClusPropertyValue.Format, CLUSPROP_SYNTAX


ClusPropertyValue.Value

The Value property sets or retrieves the data value of a property value.

object.Value [ = varNewValue ]

Parameters

object
Object expression that resolves to a ClusPropertyValue object.
varNewyValue
A Variant specifying the new data value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValue, ClusPropertyValue.DataCount


ClusPropertyValueData Collection

The ClusPropertyValueData collection contains all of the data values associated with a property value.

Properties and Methods

Method or property | Description
Count Property | Returns the number of data values in the collection.
CreateItem Method | Creates a new data value and adds it to the collection.
Item Property | Returns a single data value from the collection.
RemoveItem Method | Deletes a data value from the collection.

Relationships

A ClusPropertyValueData collection:

  • Contains data values.
  • Is obtained from ClusPropertyValue.Data.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusPropertyValueData.Count

The Count property returns the number of data values in the ClusPropertyValueData collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of data values in the collection.
object
Object expression that resolves to a ClusPropertyValueData collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValueData


ClusPropertyValueData.CreateItem

The CreateItem method creates a new data value and adds it to to a ClusPropertyValueData collection.

Set varData = object.CreateItem( varValue )

Parameters

varData
A Variant that receives the new data value.
object
Object expression that resolves to a ClusPropertyValueData collection.
varValue
A Variant specifying the new data value.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValueData, ClusProperty


ClusPropertyValueData.Item

The Item property returns a single data value from a ClusPropertyValueData collection.

Set varValue =  object.Item( varIndex )

Parameters

varValue
A Variant that receives the specified data value.
object
Object expression that resolves to a ClusPropertyValueData collection.
varIndex
A Variant that identifies an object in the collection by numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValueData, ClusProperty, ClusPropertyValueData.Count


ClusPropertyValueData.RemoveItem

The RemoveItem method deletes a data value from a ClusPropertyValueData collection.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusPropertyValueData collection.
varIndex
A Variant specifying the data value to remove by numeric index.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusPropertyValueData


Resource Management Objects

Resource management objects support operations on individual resources, their properties, and related objects.

  • ClusResource Object
  • ClusResDependencies Collection
  • ClusResPossibleOwnerNodes Collection


ClusResource Object

The ClusResource object enables operations on a resource, its properties, and related objects.

Method or property | Description
AddResourceNode Method | Adds a new node to the list of possible nodes that can host the resource.
BecomeQuorumResource Method | Sets the quorum resource.
CanResourceBeDependent Method | Determines if the resource can be dependent on another resource.
ChangeResourceGroup Method | Moves the resource from its current group to a different group.
ClassInfo Property | Returns the resource class of a resource.
Cluster Property | Returns the cluster that includes the resource.
CommonProperties Property | Returns a ClusProperties collection containing the resource's read/write common properties.
CommonROProperties Property | Returns a ClusProperties collection containing the resource's read-only common properties.
CryptoKeys Property | Returns a ClusCryptoKeys collection containing the resource's checkpointed crypto keys.
Delete Method | Deletes the resource from the cluster.
Dependencies Property | Returns a ClusResDependencies collection providing access to the resource's dependency list.
Disk Property | For Physical Disk resources, returns a ClusDisk object providing access to information about the disk.
Fail Method | initiates failure of the resource.
Group Property | Returns the group to which the resource belongs.
Name Property | Read/write property that either retrieves or modifies the name of the resource.
Offline Method | takes the resource offline.
Online Method | brings the resource online.
OwnerNode Property | Returns the node that is hosting the resource.
PossibleOwnerNodes Property | Returns the nodes that are members of the resource's possible owners list.
PrivateProperties Property | Returns a ClusProperties collection containing the resource's read/write private properties.
PrivateROProperties Property | Returns a ClusProperties collection containing the resource's read-only private properties.
RegistryKeys Property | Returns a ClusRegistryKeys collection containing the resource's checkpointed registry keys.
RemoveResourceNode Method | Removes a node from the list of possible nodes that can host the resource.
State Property | Returns information about the current state of the resource.
Type property | Returns the resource type of the resource as a ClusResType object.
TypeName property | Returns the resource type name of the resource.

Relationships

A ClusResource object:

  • Is obtained from the following collections:

    ClusResGroupResources

    ClusResDependencies

    ClusResources

    ClusResTypeResources

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Management Objects


ClusResource.AddResourceNode

The AddResourceNode method adds a new node to the list of possible nodes that can host the resource.

object.AddResourceNode( objNode )

Parameters

object
Object expression that resolves to a ClusResource object.
objNode
Object. The ClusNode object to add to the list.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResource


ClusResource.BecomeQuorumResource

The BecomeQuorumResource method establishes a resource as the quorum resource for the cluster.

object.BecomeQuorumResource( strDevicePath, lMaxLogSize )

Parameters

strDevicePath
String specifying the path to the quorum resource.
lMaxLogSize
Long specifying the maximum size that the cluster recovery log can attain, as determined by the storage capacity of the resource.
object
Object expression that resolves to a ClusResource object. The object must be capable of acting as a quorum resource (see Remarks).

Remarks

Server clusters only allow Physical Disk resources to operate as quorum resources. However, you can enable other storage devices to act as quorum resources by creating a custom resource type. For more information, see Creating a Custom Resource Type and Quorum Resource.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.CanResourceBeDependent

The CanResourceBeDependent method determines if the resource can be dependent on another resource.

varDependent = object.CanResourceBeDependent( objResource )

Parameters

object
Object expression that resolves to a ClusResource object.
objResource
The ClusResource object upon which this resource may or may not depend.
varDependent
A Variant set to TRUE if this resource can depend on the resource identified by objResource; otherwise, it is FALSE.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.ChangeResourceGroup

The ChangeResourceGroup method removes the resource from its current group and places it in a different group.

object.ChangeResourceGroup( objResGroup )

Parameters

object
Object expression that resolves to a ClusResource object.
objResGroup
The ClusResGroup object that should add the resource as a member.

Remarks

Both groups must be hosted by the same node at the time the resource is moved. If the resource is currently online, then the group identified by objResGroup must also be online.

If the resource is involved in a dependency relationship with one or more resources, all the resources in the dependency tree will change to the new group as well. For example, in the situation shown in the following diagram, changing resource B to group 2 will move the entire dependency tree (resources A, X, and Y) to group 2.

For more information, see Resource Dependencies.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup, ClusResource


ClusResource.ClassInfo

The ClassInfo property returns the resource class of the resource.

lClass = object.ClassInfo

Parameters

lClass
Long that receives the class information. ClassInfo returns one of the following values.
Value | Constant | Meaning
0 | CLUS_RESCLASS_UNKNOWN | Resource class is unknown.
1 | CLUS_RESCLASS_STORAGE | Resource is a storage device, such as a Physical Disk resource.
32768 | CLUS_RESCLASS_USER | Resource belongs to a user-defined class. CLUS_RESCLASS_USER specifies the beginning of the range for user-defined resource classes.

object
Object expression that resolves to a ClusResource object.

Access

Read-only

Remarks

A resource DLL that defines its own resource class should provide a unique identifier for the class that is set to a value greater than CLUS_RESCLASS_USER. CLUS_RESCLASS_USER specifies the beginning for user-defined resource class identifiers. To obtain a resource class identifier from Microsoft that is guaranteed to be unique, resource DLL writers send mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, Cluster


ClusResource.Cluster

The Cluster property provides access to the cluster associated with the resource.

Set objCluster = object.Cluster

Parameters

objCluster
Object that receives the Cluster object.
object
Object expression that resolves to a ClusResource object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, Cluster


ClusResource.CommonProperties

The CommonProperties property returns the read/write common properties of a resource.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a ClusResource object.
colClusProperties
A ClusProperties collection that receives the read/write common properties of the resource.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResource, ClusResource.CommonROProperties


ClusResource.CommonROProperties

The CommonROProperties property returns the read-only common properties of a resource.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a ClusResource object.
colClusProperties
A ClusProperties collection that receives the read-only resource common properties.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResource, ClusResource.CommonProperties


ClusResource.CryptoKeys

The CryptoKeys property returns a ClusCryptoKeys collection containing the checkpointed crypto keys for the resource.

Set colCryptoKeys = object.CryptoKeys

Parameters

colCryptoKeys
A ClusCryptoKeys collection that receives the checkpointed keys.
object
Object expression that resolves to a ClusResource object.

Remarks

Use the collection obtained from the CryptoKeys property to add, remove, and list a resource's checkpointed crypto keys.

For more information, see Checkpointing.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusCryptoKeys, ClusResource, ClusResource.CryptoKeys


ClusResource.Delete

The Delete method deletes the resource from the cluster.

object.Delete

Parameters

object
Object expression that resolves to a ClusResource object.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, CreateItem


ClusResource.Dependencies

The Dependencies property retrieves the dependencies of a resource.

Set colResources = object.Dependencies

Parameters

colResources
On successful return, contains a ClusResDependencies collection.
object
Object expression that resolves to a ClusResource object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies, ClusResource, ClusResources


ClusResource.Disk

For Physical Disk, the Disk property returns a ClusDisk object providing access to information about the disk. For other types of resources, the Disk property returns nothing.

Set objDisk = object.Disk

Parameters

objDisk
A ClusDisk object that receives the disk information.
object
Object expression that resolves to a ClusResource object

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisk, ClusResource


ClusResource.Fail

The Fail method initiates failure of the resource.

object.Fail

Parameters

object
Object expression that resolves to a ClusResource object.

Remarks

The Fail method causes the cluster to initiate the same procedures that would result if the resource had actually failed. Use the Fail method to test failover policies for resources and groups. For more information about resource failure policies, see Resource Failure.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.Group

The Group property returns the group to which a resource belongs.

Set objGroup = object.Group

Parameters

objGroup
A ClusResGroup object that receives the the group containing the resource.
object
Object expression that resolves to a ClusResource object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResGroup, ClusResource


ClusResource.Name

The Name property retrieves or sets the name of a resource.

object.Name [ = strName ]

Parameters

strName
String containing the new name for the resource
object
Object expression that resolves to a ClusResource object.

Access

Read/write

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.Offline

The Offline method takes the resource offline.

object.Offline( varTimeout, varPending )

Parameters

object
Object expression that resolves to a ClusResource object.
varTimeout
A Variant that specifies how long (in seconds) the method should wait for the resource to come offline before setting varPending to TRUE and returning.
varPending
A Variant set to TRUE if the request is still pending.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.Online

The Online method brings the resource online.

object.Online( varTimeout, varPending )

Parameters

object
Object expression that resolves to a ClusResource object.
varTimeout
A Variant that specifies how long (in seconds) the method should wait for the resource to come online before setting varPending to TRUE and returning.
varPending
A Variant set to TRUE if the request is still pending.

Remarks

Any resources that the resource depends on are brought online first.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.OwnerNode

The OwnerNode property returns a resource's current owner node.

Set objNode = object.OwnerNode

Parameters

object
Object expression that resolves to a ClusResource object.
objNode
A ClusNode object that receives the node currently hosting the resource.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResource


ClusResource.PossibleOwnerNodes

The PossibleOwnerNodes property returns the nodes specified as possible owners of a resource.

Set colResOwners = object.PossibleOwnerNodes

Parameters

object
Object expression that resolves to a ClusResource object.
colResOwners
A ClusResPossibleOwnerNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResPossibleOwnerNodes


ClusResource.PrivateProperties

The PrivateProperties property returns the read/write private properties of a resource.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a ClusResource object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the resource.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResource


ClusResource.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a resource.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a ClusResource object.
colClusProperties
A ClusProperties collection to receive the read-only private properties of the resource.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResource


ClusResource.RegistryKeys

The RegistryKeys property returns a ClusRegistryKeys collection containing the checkpointed registry keys for the resource.

Set colRegKeys = object.RegistryKeys

Parameters

colRegKeys
A ClusRegistryKeys collection that receives the checkpointed keys.
object
Object expression that resolves to a ClusResource object.

Remarks

Use the collection obtained from the RegistryKeys property to add, remove, and list a resource's checkpointed keys.

For more information, see Checkpointing.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusRegistryKeys, ClusResource, ClusResource.CryptoKeys


ClusResource.RemoveResourceNode

The RemoveResourceNode method removes a node from the list of possible nodes that can host the resource.

object.RemoveResourceNode( Node )

Parameters

object
Object expression that resolves to a ClusResource object.
Node
The ClusNode object to be removed.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResource


ClusResource.State

The State property returns a description of the operational condition of a resource.

lState = object.State

Parameters

object
Object expression that resolves to a ClusResource object.
lState
Long that receives a constant describing the state of the resource.
Value | Constant | Meaning
-1 | ClusterResourceStateUnknown | The State property failed. The state of the resource is unknown.
1 | ClusterResourceInitializing | The resource is performing initialization.
2 | ClusterResourceOnline | The resource is operational and functioning normally.
3 | ClusterResourceOffline | The resource is not operational.
4 | ClusterResourceFailed | The resource has failed.
128 | ClusterResourcePending | The resource is in the process of coming online or going offline.
129 | ClusterResourceOnlinePending | The resource is in the process of coming online.
130 | ClusterResourceOfflinePending | The resource is in the process of going offline.

Access

Read-only

Remarks

For information on making constants defined by the Cluster Automation Server type library (MSCLUS.tlb) available to scripts, see Creating a Cluster Automation Server Script.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource


ClusResource.Type

The Type property returns a ClusResType object representing the resource type of the resource.

Set objResType = object.Type

Parameters

object
Object expression that resolves to a ClusResource object.
objResType
A ClusResType object that receives the resource type of the resource.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResource.TypeName, ClusResType


ClusResource.TypeName

The TypeName property returns the resource type name of the resource.

strResTypeName = object.Type

Parameters

object
Object expression that resolves to a ClusResource object.
strResTypeName
String that receives the resource type name.

Remarks

The name returned is the name of the resource type as registered with the Cluster service, for example: "File Share" or "Physical Disk".

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResource.Type


ClusCryptoKeys Collection

The ClusCryptoKeys collection provides access to the checkpointed crypto keys of a resource. Crypto keys are created using the Crypto API. Checkpointed keys are moved to the resource's new host node during failover.

Properties and Methods

Method or property | Description
AddItem Method | Adds an object to the ClusCryptoKeys collection.
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single object from the collection.
Refresh Method | Refreshes the data in the collection.
RemoveItem Method | Deletes an object from the collection.

Relationships

A ClusCryptoKeys collection:

  • Contains crypto keys (registry keys) as strings.
  • Is obtained from ClusResource.CryptoKeys.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusCryptoKeys.AddItem

The AddItem method adds a crypto key to a ClusCryptoKeys collection.

Set objCryptoKey =  object.AddItem( strName )

Parameters

objCryptoKey
A string that receives the added key.
object
Object expression that resolves to a ClusCryptoKeys collection.
strName
String identifying the cryptographic service provider (CSP) key container to be checkpointed. The CSP key container must first be created with the CryptoAPI, and the keys in the container must be exportable. The string must specify the CSP provider type, provider name, and key container name using the following syntax:

Type\Name\Key

Note that the values must be separated by a '\'. The provider type should specify the decimal value of the type, not the constant that represents the value. For example, instead of "PROV_RSA_FULL" use "1". The provider name is optional, and if it is omitted, the default CSP provider name associated with the specified provider type will be used.

varValue
A Variant specifying the initial value of the key.

Remarks

For more information on the following points, see the CryptoAPI_Reference.

  • A key container is given a name when it is created using CryptAcquireContext with dwFlags set to CRYPT_NEWKEYSET.
  • Once a key container has been created, the key pairs for that key container must be created using CryptGenKey with the dwFlags parameter set to CRYPT_EXPORTABLE. Note that some CSPs do not allow key exports from their key containers. If a key is not exportable then the ClusterResourceControl call will fail with an NTE_BAD_KEY error.

For more information on checkpoints, see Checkpointing.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusCryptoKeys, ClusProperty


ClusCryptoKeys.Count

The Count property returns the number of crypto keys in the ClusCryptoKeys collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of crypto keys in the collection.
object
Object expression that resolves to a ClusCryptoKeys collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusCryptoKeys


ClusCryptoKeys.Item

The Item property returns a single crypto key from a ClusCryptoKeys collection.

strCryptoKey =  object.Item( varIndex )

Parameters

strCryptoKey
A string that receives the specified key.
object
Object expression that resolves to a ClusCryptoKeys collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusCryptoKeys, ClusProperty, ClusCryptoKeys.Count


ClusCryptoKeys.Refresh

The Refresh method refreshes the data in the ClusCryptoKeys collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusCryptoKeys collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusCryptoKeys


ClusCryptoKeys.RemoveItem

The RemoveItem method deletes a crypto key from a ClusCryptoKeys collection.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusCryptoKeys collection.
varIndex
A Variant specifying the object to remove by name or by numeric index.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusCryptoKeys


ClusRegistryKeys Collection

The ClusRegistryKeys collection represents the list of registry keys that are checkpointed for a resource.

Properties and Methods

Method or property | Description
AddItem Method | Adds an object to the ClusRegistryKeys collection.
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single object from the collection.
Refresh Method | Refreshes the data in the collection.
RemoveItem Method | Deletes an object from the collection.

Relationships

A ClusRegistryKeys collection:

  • Contains registry keys as strings.
  • Is obtained from ClusResource.RegistryKeys.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusRegistryKeys.AddItem

The AddItem method adds a registry key to a ClusRegistryKeys collection.

strKey =  object.AddItem( strName )

Parameters

strKey
A string that receives the added key.
object
Object expression that resolves to a ClusRegistryKeys collection.
strName
String identifying the new key.

Remarks

Use the AddItem method to add a registry key to a resource's list of checkpointed registry keys. For example:

Public Function AddKey(ByRef objRes as ClusResource, _
                       ByVal strKey as String)

    Dim colRegKeys as ClusRegistryKeys
    Set colRegKeys = objRes.RegistryKeys
    colRegKeys.AddItem( strKey )
    Set colRegKeys = Nothing

End Function

For more information on checkpoints, see Checkpointing.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusRegistryKeys, ClusProperty


ClusRegistryKeys.Count

The Count property returns the number of registry keys in the ClusRegistryKeys collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of registry keys in the collection.
object
Object expression that resolves to a ClusRegistryKeys collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusRegistryKeys


ClusRegistryKeys.Item

The Item property returns a single registry key from a ClusRegistryKeys collection.

strKey =  object.Item( varIndex )

Parameters

strKey
A string that receives the specified registry key.
object
Object expression that resolves to a ClusRegistryKeys collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusRegistryKeys, ClusProperty, ClusRegistryKeys.Count


ClusRegistryKeys.Refresh

The Refresh method refreshes the data in the ClusRegistryKeys collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusRegistryKeys collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusRegistryKeys


ClusRegistryKeys.RemoveItem

The RemoveItem method deletes a registry key from a ClusRegistryKeys collection.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusRegistryKeys collection.
varIndex
A Variant specifying the key to remove by name or by numeric index.

Remarks

Use the RemoveItem method to remove a registry key from a resource's list of checkpointed registry keys.

For more information on checkpoints, see Checkpointing.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusRegistryKeys


ClusResDependencies Collection

The ClusResDependencies collection provides access to the dependencies of a resource. Resources added to a ClusResDependencies collection become dependencies of the resource from which the collection was obtained.

Properties and Methods

Method or property | Description
AddItem Method | Adds an existing cluster resource to the dependency collection.
Count Property | Returns the number of dependencies in the collection.
CreateItem Method | Creates a new resource in the cluster and adds it to the dependency collection.
DeleteItem Method | Removes a resource from the dependency collection and deletes the resource from the cluster.
Item Property | Returns a single dependency from the collection.
Refresh Method | Refreshes the data in the collection.
RemoveItem Method | Removes a dependency from the collection.

Relationships

A ClusResDependencies collection:

  • Contains ClusResource objects.
  • Is obtained from ClusResource.Dependencies.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Management Objects


ClusResDependencies.AddItem

The AddItem method adds an existing cluster resource to the dependency collection.

object.AddItem( objResource )

Parameters

object
Object expression that resolves to a ClusResDependencies collection.
objResource
The ClusResource object to add to the collection.

Remarks

Resources added to a ClusResDependencies collection become dependencies of the resource from which the collection was obtained

Example Code

The following script uses the AddItem method to add a dependency to a resource.

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' adddependency.vbs
' Adds a dependency to a resource. Both resources must already exist
' and be able to form a dependency relationship. Run the script on
' the command line using the following syntax:
'     AddDependency Resourcename Dependencyname
' The resource identified by Resourcename will depend on the resource
' identified by Dependencyname.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
Dim objArgs, objCluster, objResource, objDependency
Set objArgs = WScript.Arguments
If objArgs.Count <> 2 Then
    WScript.Echo "Syntax:   AddDependency Resourcename Dependencyname"
    WScript.Quit
End If
Set objCluster = CreateObject("MSCluster.Cluster")
objClus.Open ""
Set objResource = objCluster.Resources.Item(objArgs(0))
Set objDependency = objCluster.Resources.Item(objArgs(1))
If objResource.CanResourceBeDependent(objDependency) Then
    objResource.Dependencies.AddItem(objDependency)
Else
    WScript.Echo objResource.Name & " cannot depend on " & objDependency.Name
End If
Set objResource = Nothing
Set objDependency = Nothing
Set objCluster = Nothing

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies, ClusResource


ClusResDependencies.Count

The Count property returns the number of resources in the collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of resources in the collection.
object
Object expression that resolves to a ClusResDependencies collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies


ClusResDependencies.CreateItem

The CreateItem method creates a new resource in the cluster and adds it to the dependency collection.

Set objResource =  object.CreateItem( ResourceName, ResourceType, GroupName, Flag )

Parameters

objResource
A ClusResource object that receives the new resource.
object
Object expression that resolves to a ClusResDependencies collection.
ResourceName
String containing the name of the resource to create.
ResourceType
String specifying the type of the resource to create.
GroupName
String containing the name of the group to which the new resource will belong.
Flag
Value indicating how to create the resource. Flag can be set to:

CLUSTER_RESOURCE_SEPARATE_MONITOR

This value indicates that a separate Resource Monitor should be assigned to the newly created resource.

Remarks

Resources added to a ClusResDependencies collection become dependencies of the resource from which the collection was obtained.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies, ClusResource


ClusResDependencies.DeleteItem

The DeleteItem method removes a resource from the dependency collection and deletes the resource from the cluster.

object.DeleteItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResDependencies collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to ClusResDependencies.Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies, ClusResDependencies.Count


ClusResDependencies.Item

The Item property retrieves a single resource from a ClusResDependencies collection.

Set objResource = object.Item( varIndex )

Parameters

objResource
A ClusResource object that receives the specified resource.
object
Object expression that resolves to a ClusResDependencies collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies, ClusResDependencies.Count, ClusResource


ClusResDependencies.Refresh

The Refresh method refreshes the data in the ClusResDependencies collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResDependencies collection object.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies


ClusResDependencies.RemoveItem

The RemoveItem method removes a resource from the dependency collection but does not delete it from the cluster.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResDependencies collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to ClusResDependencies.Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependencies, ClusResDependencies.Count


ClusResDependents Collection

The ClusResDependents collection provides access to the dependents of a resource. Resources added to a ClusResDependents collection become dependents of the resource from which the collection was obtained.

Properties and Methods

Method or property | Description
AddItem Method | Adds an existing cluster resource to the collection.
Count Property | Returns the number of dependents in the collection.
CreateItem Method | Creates a new resource in the cluster and adds it to the collection.
DeleteItem Method | Removes a resource from the collection and deletes the resource from the cluster.
Item Property | Returns a single resource from the collection.
Refresh Method | Refreshes the data in the collection.
RemoveItem Method | Removes a resource from the collection.

Relationships

A ClusResDependents collection:

  • Contains ClusResource objects.
  • Is obtained from ClusResource.Dependencies.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Management Objects


ClusResDependents.AddItem

The AddItem method adds an existing cluster resource to the ClusResDependents collection.

object.AddItem( objResource )

Parameters

object
Object expression that resolves to a ClusResDependents collection.
objResource
The ClusResource object to add to the collection.

Remarks

Resources added to a ClusResDependents collection become dependents of the resource from which the collection was obtained.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents, ClusResource


ClusResDependents.Count

The Count property returns the number of resources in the collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of resources in the collection.
object
Object expression that resolves to a ClusResDependents collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents


ClusResDependents.CreateItem

The CreateItem method creates a new resource in the cluster and adds it to the ClusResDependents collection.

Set objResource =  object.CreateItem( ResourceName, ResourceType, GroupName, Flag )

Parameters

objResource
A ClusResource object that receives the new resource.
object
Object expression that resolves to a ClusResDependents collection.
ResourceName
String containing the name of the resource to create.
ResourceType
String specifying the type of the resource to create.
GroupName
String containing the name of the group to which the new resource will belong.
Flag
Value indicating how to create the resource. Flag can be set to:

CLUSTER_RESOURCE_SEPARATE_MONITOR

This value indicates that a separate Resource Monitor should be assigned to the newly-created resource.

Remarks

Resources added to a ClusResDependents collection become dependents of the resource from which the collection was obtained.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents, ClusResource


ClusResDependents.DeleteItem

The DeleteItem method removes a resource from the ClusResDependents collection and deletes the resource from the cluster.

object.DeleteItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResDependents collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to ClusResDependents.Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents, ClusResDependents.Count


ClusResDependents.Item

The Item property retrieves a single resource from a ClusResDependents collection.

Set objResource = object.Item( varIndex )

Parameters

objResource
A ClusResource object that receives the specified resource.
object
Object expression that resolves to a ClusResDependents collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents, ClusResDependents.Count, ClusResource


ClusResDependents.Refresh

The Refresh method refreshes the data in the ClusResDependents collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResDependents collection object.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents


ClusResDependents.RemoveItem

The RemoveItem method removes a resource from the ClusResDependents collection but does not delete it from the cluster.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResDependents collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to ClusResDependents.Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResDependents, ClusResDependents.Count


ClusResPossibleOwnerNodes Collection

The ClusResPossibleOwnerNodes collection provides access to a resource's list of possible owner nodes.

Properties and Methods

Method or property | Description
AddItem Method | Adds a node to the list of possible owners of a resource.
Count Property | Returns the number of nodes in the collection.
Item Property | Returns a single node from the collection.
Modified Property | Reports whether the collection has been modified since instantiation.
RemoveItem Method | Removes a node from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResPossibleOwnerNodes collection:

  • Contains ClusNode objects.
  • Is obtained from ClusResource.PossibleOwnerNodes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Management Objects


ClusResPossibleOwnerNodes.AddItem

The AddItem method adds a node to a resource's possible owners list.

object.AddItem( objNode  )

Parameters

object
Object expression that resolves to a ClusResPossibleOwnerNodes collection.
objNode
A ClusNode object to add to the possible owners list.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResPossibleOwnerNodes


ClusResPossibleOwnerNodes.Count

The Count property returns the number of possible owner nodes listed for a resource,

lCount = object.Count

Parameters

lCount
Long indicating the number of nodes in the collection.
object
Object expression that resolves to a ClusResPossibleOwnerNodes collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResPossibleOwnerNodes


ClusResPossibleOwnerNodes.Item

The Item property returns a node from a resource's list of possible owner nodes.

Set objNode =  object.Item( varIndex )

Parameters

object
Object expression that resolves to a ClusResPossibleOwnerNodes collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count
objNode
A ClusNode object that receives the specified node.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusNode, ClusResPossibleOwnerNodes, ClusResPossibleOwnerNodes.Count


ClusResPossibleOwnerNodes.Modified

The Modified property reports whether this instance of the collection has been modified since it was created.

varFlag =  object.Modified

Parameters

object
Object expression that resolves to a ClusResPossibleOwnerNodes collection.
varFlag
A Variant that receives flag indicating whether the collection has been modified. If Flag is set to TRUE, the collection has been modified. If Flag is set to FALSE, the collection has not been modified.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResPossibleOwnerNodes


ClusResPossibleOwnerNodes.Refresh

The Refresh method refreshes the data in the ClusResPossibleOwnerNodes collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResPossibleOwnerNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResPossibleOwnerNodes


ClusResPossibleOwnerNodes.RemoveItem

The RemoveItem method removes a node from a resource's possible owners list.

object.RemoveItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResPossibleOwnerNodes collection.
varIndex
A Variant that identifies an object in the collection by name or numeric index. Index numbers range from 1 to ClusResPossibleOwnerNodes.Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResPossibleOwnerNodes, ClusResPossibleOwnerNodes.Count


Resource Type Management Objects

The resource type management objects support the following operations on individual resource types, their properties, and related objects.

  • ClusResType Object
  • ClusResTypeResources Collection
  • ClusResTypePossibleOwnerNodes


ClusResType Object

The ClusResType object enables operations on a resource type, its properties, and related objects.

Properties and Methods

Method or property | Description
AvailableDisks | Returns a ClusDisks collection representing the Physical Disks available to the resource type.
Cluster Property | Returns the cluster associated with the resource type.
CommonProperties Property | Returns a ClusProperties collection containing the resource type's read/write common properties.
CommonROProperties Property | Returns a ClusProperties collection containing the resource type's read-only common properties.
Delete Method | Deletes the resource type.
PossibleOwnerNodes Property | Returns a ClusResTypePossibleOwnerNodes collection containing the possible owner nodes of the resource type.
PrivateProperties Property | Returns a ClusProperties collection containing the resource type's read/write private properties.
PrivateROProperties Property | Returns a ClusProperties collection containing the resource type's read-only private properties.
Resources Property | Returns all resources of a given type that are present in the cluster.

Relationships

A ClusResType object:

  • Is obtained from ClusResTypes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Type Management Objects


ClusResType.AvailableDisks

The AvailableDisks property returns the ClusDisks collection representing the Physical Disks available to the resource type. A Physical Disk is available if it is cluster-capable and is currently not being used as a resource.

Set colAvDisks = object.AvailableDisks

Parameters

objAvDisks
Object that receives a ClusDisks collection.
object
Object expression that resolves to a ClusResType object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisks


ClusResType.Cluster

The Cluster property returns the Cluster object associated with the resource type.

Set objCluster = object.Cluster

Parameters

objCluster
Object that receives a Cluster object.
object
Object expression that resolves to a ClusResType object.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResType, Cluster


ClusResType.CommonProperties

The CommonProperties property returns the read/write common properties of a resource type.

Set colClusProperties = object.CommonProperties

Parameters

object
Object expression that resolves to a ClusResType object.
colClusProperties
A ClusProperties collection that receives the read/write common properties of the resource type.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResType


ClusResType.CommonROProperties

The CommonROProperties property returns the read-only common properties of a resource type.

Set colClusProperties = object.CommonROProperties

Parameters

object
Object expression that resolves to a ClusResType object.
colClusProperties
A ClusProperties collection that receives the read-only resource type common properties.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResType


ClusResType.Delete

The Delete method deletes the resource type from the cluster and unregisters the type with the Cluster service.

object.Delete

Parameters

object
Object expression that resolves to a ClusResType object.

Remarks

This method will fail if any resources of the specified type exist in the cluster. Once a resource type is deleted, no resources of that type can be created in the cluster until the resource type is re-created.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResType


ClusResType.Resources

The Resources property returns a ClusResTypeResources collection providing access to the resources of a particular type in the cluster.

Set colResources = object.Resources

Parameters

object
Object expression that resolves to a ClusResType object.
colResources
A ClusResTypeResources collection that receives the resources.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResType, ClusResTypeResources


ClusResType.PossibleOwnerNodes

The PossibleOwnerNodes property returns the nodes specified as possible owners of a resource type.

Set colResOwners = object.PossibleOwnerNodes

Parameters

object
Object expression that resolves to a ClusResType object.
colResOwners
A ClusResTypePossibleOwnerNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResType, ClusResTypePossibleOwnerNodes


ClusResType.PrivateProperties

The PrivateProperties property returns the read/write private properties of a resource type.

Set colClusProperties = object.PrivateProperties

Parameters

object
Object expression that resolves to a ClusResType object.
colClusProperties
A ClusProperties collection that receives the read/write private properties of the resource type.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResType


ClusResType.PrivateROProperties

The PrivateROProperties property returns the read-only private properties of a resource type.

Set colClusProperties = object.PrivateROProperties

Parameters

object
Object expression that resolves to a ClusResType object.
colClusProperties
A ClusProperties collection to receive the read-only private properties of the resource type.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusProperties, ClusResType


ClusDisks Collection

The ClusDisks collection provides access to the cluster-capable Physical Disks available to a resource type.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single object from the collection.

Relationships

A ClusDisks collection:

  • Contains ClusDisk objects.
  • Is obtained from ClusResType.AvailableDisks.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Property Management Objects


ClusDisks.Count

The Count property returns the number of disks in the ClusDisks collection.

lCount = object.Count

Parameters

lCount
Long indicating the number of disks in the collection.
object
Object expression that resolves to a ClusDisks collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisks


ClusDisks.Item

The Item property returns a single disk from a ClusDisks collection.

Set objDisk =  object.Item( varIndex )

Parameters

objDisk
A ClusDisk object that receives the specified properties.
object
Object expression that resolves to a ClusDisks collection.
varIndex
A Variant that identifies an object in the collection by numeric index. Index numbers range from 1 to object. Count.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusDisks, ClusDisk, ClusDisks.Count


ClusResTypeResources Collection

The ClusResTypeResources collection provides access to the resources of a particular type in a cluster.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
CreateItem Method | Creates a new cluster resource and adds it to the collection.
DeleteItem Method | Deletes a resource from the collection.
Item Property | Returns a single resource from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResPossibleOwnerNodes collection:

  • Contains ClusResource objects.
  • Is obtained from ClusResType.Resources.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Type Management Objects


ClusResTypeResources.Count

The Count property returns the number of objects in the collection (the number of resources of a particular type in the cluster).

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusResTypeResources collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypeResources


ClusResTypeResources.CreateItem

The CreateItem method creates a new resource in the cluster and adds it to the ClusResTypeResources collection.

Set objResource =  object.CreateItem( strResName, _
                                      strGroupName, _
                                      lFlag )

Parameters

object
Object expression that resolves to a ClusResTypeResources collection.
strResName
String containing the name of the new resource.
strGroupName
String containing the name of the group in which to place the new resource.
lFlag
Long indicating how to create the resource. Flag can be set to the following values.
Value | Meaning
CLUSTER_RESOURCE_DEFAULT_MONITOR | The Cluster service determines the Resource Monitor to which the new resource will be assigned.
CLUSTER_RESOURCE_SEPARATE_MONITOR | Causes the Cluster service to create a separate Resource Monitor dedicated exclusively to the new resource.

objResource
A ClusResource object that receives the newly added resource.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResTypeResources


ClusResTypeResources.DeleteItem

The DeleteItem method deletes a resource from the cluster and removes it from a ClusResTypeResources collection.

object.DeleteItem( varIndex )

Parameters

object
Object expression that resolves to a ClusResTypeResources collection.
varIndex
Integer that identifies an object in the collection by name or numeric index. Index numbers range from 1 to object. Count.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypeResources


ClusResTypeResources.Item

The Item property returns a single ClusResource object from a ClusResTypeResources collection.

Set objResource =  object.Item( varIndex )

Parameters

object
Object expression that resolves to a ClusResTypeResources collection.
varIndex
A Variant that identifies a resource in the collection by name or numeric index. Index numbers range from 1 to object. Count.
objResource
A ClusResource object that receives the specified resource.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResource, ClusResTypeResources, ClusResTypeResources.Count


ClusResTypeResources.Refresh

The Refresh method refreshes the data in the ClusResTypeResources collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResTypeResources collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypeResources


ClusResTypePossibleOwnerNodes Collection

The ClusResTypePossibleOwnerNodes collection provides access to the possible owner nodes of a resource type.

Properties and Methods

Method or property | Description
Count Property | Returns the number of objects in the collection.
Item Property | Returns a single node from the collection.
Refresh Method | Refreshes the data in the collection.

Relationships

A ClusResPossibleOwnerNodes collection:

  • Contains ClusNode objects.
  • Is obtained from ClusResType.PossibleOwnerNodes.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

Resource Type Management Objects


ClusResTypePossibleOwnerNodes.Count

The Count property returns the number of objects in the collection (the number of possible owner nodes listed for a resource type).

lCount = object.Count

Parameters

lCount
Long indicating the number of objects in the collection.
object
Object expression that resolves to a ClusResTypePossibleOwnerNodes collection.

Access

Read-only

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypePossibleOwnerNodes


ClusResTypePossibleOwnerNodes.Item

The Item property returns a possible owner node from the collection.

Set objNode =  object.Item( varIndex )

Parameters

object
Object expression that resolves to a ClusResTypePossibleOwnerNodes collection.
varIndex
A Variant that identifies a node in the collection by name or numeric index. Index numbers range from 1 to object. Count.
objNode
A ClusNode object that receives the specified node.

Access

Read-only

Remarks

A node obtained from Item is one of the possible owner nodes of the resource type from which the collection was obtained.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypePossibleOwnerNodes, ClusResTypePossibleOwnerNodes.Count


ClusResTypePossibleOwnerNodes.Refresh

The Refresh method refreshes the data in the ClusResTypePossibleOwnerNodes collection.

object.Refresh

Parameters

object
Object expression that resolves to a ClusResTypePossibleOwnerNodes collection.

Requirements

Version: Requires Windows NT Server Enterprise Edition 4.0 SP3; Windows NT Server Enterprise Edition 4.0 SP4; Windows 2000 Advanced Server; Windows 2000 Data Center.
Header: Msclus.idl.
Library: Use Msclus.tlb.

See Also

ClusResTypePossibleOwnerNodes


Cluster Configuration Reference

[This is preliminary documentation and subject to change.]

The cluster configuration interfaces allow you to detect, customize, and implement a variety of cluster configuration tasks including installation, upgrade, membership changes, and the creation of new resource types.

  • Cluster Configuration Server Interfaces
  • Cluster Configuration Wizard Interface


Cluster Configuration Server Interfaces

[This is preliminary documentation and subject to change.]

The cluster configuration server (defined in ClusCfgServer.idl and ClusCfgServer.h) defines the following interfaces.

Section | Content
Implemented Interfaces | Interfaces that you call to support configuration tasks.
User-Implemented Interfaces | Interfaces that you can implement to carry out configuration tasks.


Implemented Interfaces

[This is preliminary documentation and subject to change.]

You can call the following interfaces to support your configuration tasks.

Interface | Description
IClusCfgBaseCluster | Do not use. This is not a public interface. It will soon be removed from ClusCfgServer.idl.
IClusCfgCallback | Indicates the status of a task on the server.
IClusCfgClusterInfo | Sets and retrieves information about the cluster configuration.
IClusCfgCredentials | Sets and retrieves user credentials.
IClusCfgEvictCleanup | Do not use. This is not a public interface. It will soon be removed from ClusCfgServer.idl.
IClusCfgIPAddressInfo | Sets and retrieves information about an IP address.
IClusCfgNetworkInfo | Enumerates the networks on the computer.
IClusCfgNodeInfo | Sets and retrieves information about the node configuration.
IClusCfgPartitionInfo | Sets and retrieves information about disk partitions.
IClusCfgResourceCreate | Sets resource properties and performs resource control code operations.
IClusCfgResourcePostCreate | Renames resources and performs resource control code operations.
IClusCfgResourcePreCreate | Specifies resource dependencies, types, and classes.
IClusCfgResourceTypeCreate | Creates and registers new resource types.
IClusCfgServer | Gathers information about nodes, resources, and networks and allows a node to form or join a cluster.
IEnumClusCfgIPAddresses | Enumerates the IP addresses on an adapter.
IEnumClusCfgNetworks | Enumerates the network interfaces on a computer.
IEnumClusCfgPartitions | Enumerates the partitions on a cluster-manageable storage device.


IClusCfgBaseCluster

[This is preliminary documentation and subject to change.]

Do not use. This is not a public interface. It will soon be removed from ClusCfgServer.idl.


IClusCfgCallback

[This is preliminary documentation and subject to change.]

The IClusCfgCallback interface allows a server component to call back to the client to report the status of a task being completed on the server.

Methods in Vtable Order

The IClusCfgCallback interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgCallback method | Description
SendStatusReport | Sends a status report back to the client.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgCallback::SendStatusReport

[This is preliminary documentation and subject to change.]

The SendStatusReport method sends a status report back to the client and is also used to add entries to the client-side and server-side logs.

HRESULT SendStatusReport(
  BSTR bstrNodeNameIn,
  CLSID clsidTaskMajorIn
  CLSID clsidTaskMinorIn,
  ULONG ulMinIn,
  ULONG ulMaxIn,
  ULONG ulCurrentIn,
  HRESULT hrStatusIn,
  BSTR bstrDescriptionIn,
  FILETIME* pftTimeIn,
  BSTR bstrReferenceIn
);

Parameters

bstrNodeNameIn
[in] The name of the node (server) from which the report is sent. If specified as NULL, it will be filled in by the cluster configuration server.
clsidTaskMajorIn
[in] CLSID of the major task item to give the status of. For the wizard, this indicates which node in the tree view control to publish the status message under. If clsidTaskMajorIn equals IID_NULL, only a log entry will be made. The following TASKIDs are defined in ClusCfgGuids.h:
TASKID | Usage
TASKID_Major_Check_Cluster_Feasibility | For cluster use only—do not use.
TASKID_Major_Checking_For_Existing_Cluster | For cluster use only—do not use.
TASKID_Major_Client_And_Server_LogOnly | Log in the client and server side logs. The report will not show up in the UI, although it may be displayed by the cluster command.
TASKID_Major_Client_Log | Only log in the client-side log. This should never be used.
TASKID_Major_Configure_Cluster_Services | For cluster use only—do not use.
TASKID_Major_Configure_Resource_Types | Indicates that you are reporting the status of a resource type configuration.
TASKID_Major_Configure_Resources | Indicates that you are reporting the status of a resource configuration.
TASKID_Major_Establish_Connection | For cluster use only—do not use.
TASKID_Major_Find_Devices | For cluster use only—do not use.
TASKID_Major_Reanalyze | For cluster use only—do not use.
TASKID_Major_Server_Log | Only log in the server-side log. This report will not be transferred over the network and can be used for more verbose logging to the local server-side log.
clsidTaskMinorIn
[in] CLSID of the minor task to give the status of. This is defined by the individual component and will be included in the logs. The CLSID should be unique to each sub-task and message.
ulMinIn
[in] The minimum value of progress.
ulMaxIn
[in] The maximum value of progress.
ulCurrentIn
[in] The current value of progress.
hrStatusIn
[in] The current status.
bstrDescriptionIn
[in] The description of the status. Can be NULL to indicate that nothing needs to be passed.
pftTimeIn
[in] Indicates the time the event occurred; if specified as NULL, the cluster configuration server will fill it in.
bstrReferenceIn
[in] Indicates a reference to be displayed in the Cluster Configuration Wizard UI, for example a URL or some other text. May be specified as NULL.

Return Values

If the SendStatusReport method successfully sends a status report, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Example Code

DEFINE_GUID( TASKID_Minor_Configure_My_Resoure_Type,
0xbaadbeef, 0xbaad, 0xf00d, 0xba, 0xad, 0xf0, 0x0d, 0xba, 0xad, 0xbe, 0xef);

// Send a status report up to the UI.
// The callback pointer was obtained from IClusCfgInitialize::Initialize()
if ( m_cpcccCallback != NULL )
{
    hr = m_cpcccCallback->SendStatusReport(
              NULL
            , TASKID_Major_Configure_Resource_Types
            , TASKID_Minor_Configure_My_Resoure_Type
            , 0
            , 1
            , 0
            , hr
            , bstrStatusReportText
            , NULL
            , NULL
            );
} // if: the callback pointer is not NULL

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo

[This is preliminary documentation and subject to change.]

The IClusCfgClusterInfo interface sets and retrieves information about the cluster configuration.

Methods in Vtable Order

The IClusCfgClusterInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgClusterInfo Method | Description
IsForming | Returns whether the commit action will form a new cluster on the node.
IsJoining | Returns whether the commit action will add (join) the node to an existing cluster.
IsEvicted | Returns whether the commit action will remove the node from a cluster.
SetForming | Sets the commit action to form a new cluster.
SetJoining | Sets the commit action to join an existing cluster.
SetEvicted | Sets the commit action to remove a node from the cluster.
GetName | Retrieves the cluster name.
SetName | Sets the cluster name.
GetIPAddress | Retrieves the cluster IP address.
SetIPAddress | Sets the cluster IP address.
GetSubnetMask | Retrieves the cluster subnet mask .
SetSubnetMask | Sets the cluster subnet mask.
GetNetworkInfo | Retrieves an IClusCfgNetworkInfo interface describing the cluster IP address and name.
SetNetworkInfo | Sets the cluster IP address and name.
GetClusterServiceAccountCredentials | Retrieves the user account credentials used by the cluster for authentication.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::GetClusterServiceAccountCredentials

[This is preliminary documentation and subject to change.]

The GetClusterServiceAccountCredentials method retrieves the user account credentials used by the cluster for authentication.

HRESULT GetClusterServiceAccountCredentials(
  IClusCfgCredentials** ppicccCredentialsOut
);

Parameters

ppicccCredentialsOut
[out] Pointer to an IClusCfgCredentials interface that contains the cluster's user account credentials.

Return Values

The GetClusterServiceAccountCredentials method returns one of the following values:

S_OK.
The called succeeded.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Remarks

The cluster must run in a domain user account with administrative privileges on each cluster node. For more information refer to Whistler online help.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::GetIPAddress

[This is preliminary documentation and subject to change.]

The GetIPAddress method retrieves the cluster IP address.

HRESULT GetIPAddress(
  ULONG* pulDottedQuadOut
);

Parameters

pulDottedQuadOut
[out] Pointer to the IP address of the cluster in dotted decimal format.

Return Values

If the SendStatusReport method successfully retrieves the IP address, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the name of the cluster to be formed or joined.

HRESULT GetName(
  BSTR* pbstrNameOut
);

Parameters

pbstrNameOut
[out] Pointer to a BSTR containing the cluster name as a fully qualified domain name (for example, mycluster.microsoft.com). The caller must free this string by calling SysFreeString.

Return Values

The GetName method returns one of the following values:

S_OK.
Success.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::GetNetworkInfo

[This is preliminary documentation and subject to change.]

The GetNetworkInfo method retrieves an IClusCfgNetworkInfo interface describing the cluster IP address and name.

HRESULT GetNetworkInfo(
  IClusCfgNetworkInfo** ppiccniOut
);

Parameters

ppiccniOut
[out] Pointer to an IClusCfgNetworkInfo interface describing the cluster IP address and name.

Return Values

If the GetNetworkInfo method is successful, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::GetSubnetMask

[This is preliminary documentation and subject to change.]

The GetSubnetMask method retrieves the cluster subnet mask .

HRESULT GetSubnetMask(
  ULONG* pulDottedQuadOut
);

Parameters

pulDottedQuadOut
[out] Pointer to the cluster subnet mask in dotted quad format.

Return Values

If the GetSubnetMask method successfully retrieves the subnet mask, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::IsEvicted

[This is preliminary documentation and subject to change.]

The IsEvicted method returns whether the commit action is going to remove a node from the cluster.

HRESULT IsEvicted( void );

Parameters

This method has no parameters.

Return Values

The IsEvicted method returns one of the following values:

S_OK.
The call succeeded, and the commit action will remove the node from the cluster.
S_FALSE
The call succeeded, and the commit action will not remove the node from the cluster.

Any other HRESULT value indicates that the call failed.

Remarks

The commit action will always be one of the following operations:

  • Form a new cluster on this node.
  • Add (join) this node to an existing cluster.
  • Remove (evict) this node from the cluster.

Thus if IsEvicted returns S_OK, you know that IClusCfgClusterInfo::IsJoining and IClusCfgClusterInfo::IsForming will return S_FALSE.

When a user requests one of the above operations through the Cluster Configuration Wizard, the cluster sets the commit action and calls your implementation of IClusCfgMemberSetChangeListener::Notify. Your implementation can call the IsJoining, IsForming, and IsEvicted methods to determine what the commit action is going to be and perform the necessary operations in response. When your configuration tasks are complete, the Cluster Configuration Wizard allows the user to commit the action.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::IsForming

[This is preliminary documentation and subject to change.]

The IsForming method returns whether the commit action will create a new cluster.

HRESULT IsForming( void );

Parameters

This method has no parameters.

Return Values

The IsForming method returns one of the following values:

S_OK.
The call succeeded, and the commit action will create a new cluster.
S_FALSE
The call succeeded, and the commit action will not create a new cluster.

Any other HRESULT value indicates that the call failed.

Remarks

The commit action will always be one of the following operations:

  • Form a new cluster on this node.
  • Add (join) this node to an existing cluster.
  • Remove (evict) this node from the cluster.

Thus if IsForming returns S_OK, you know that IsEvicted and IsJoining will return S_FALSE.

When a user requests one of the above operations through the Cluster Configuration Wizard, the cluster sets the commit action and calls your implementation of IClusCfgMemberSetChangeListener.Notify. Your implementation can call the IsJoining, IsForming, and IsEvicted methods to determine what the commit action is going to be and perform the necessary operations in response. When your configuration tasks are complete, the Cluster Configuration Wizard allows the user to commit the action.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::IsJoining

[This is preliminary documentation and subject to change.]

The IsJoining method returns whether the commit action will add a node to the cluster.

HRESULT IsJoining( void );

Parameters

This method has no parameters.

Return Values

The IsJoining method returns one of the following values:

S_OK.
The call succeeded, and the commit action will add a node to the cluster.
S_FALSE
The call succeeded, and the commit action will not add a node to the cluster.

Any other HRESULT value indicates that the call failed.

Remarks

The commit action will always be one of the following operations:

  • Form a new cluster on this node.
  • Add (join) this node to an existing cluster.
  • Remove (evict) this node from the cluster.

Thus if IsJoining returns S_OK, you know that IClusCfgClusterInfo::IsEvicted and IClusCfgClusterInfo::IsForming will return S_FALSE.

When a user requests one of the above operations through the Cluster Configuration Wizard, the cluster sets the commit action and calls your implementation of IClusCfgMemberSetChangeListener::Notify. Your implementation can call the IsJoining, IsForming, and IsEvicted methods to determine what the commit action is going to be and perform the necessary operations in response. When your configuration tasks are complete, the Cluster Configuration Wizard allows the user to commit the action.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetEvicted

[This is preliminary documentation and subject to change.]

The SetEvicted method sets the commit action to remove a node from the cluster.

HRESULT SetEvicted(
  BOOL fEvictedIn
);

Parameters

fEvictedIn
[in]If TRUE, the node will perform the tasks that must be done when the node is evicted from a cluster, when the changes are committed.

Return Values

The SetEvicted method returns one of the following values:

S_OK.
Call succeed.
E_UNEXPECTED
IsForming or IsJoining is TRUE.

Any other HRESULT value indicates that the call failed.

Remarks

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetForming

[This is preliminary documentation and subject to change.]

The SetForming method sets the commit action to form a new cluster.

HRESULT SetForming(
  BOOL fFormingIn
);

Parameters

fFormingIn
[in] If TRUE, the node will form a new cluster when the changes are committed.

Return Values

The SetForming method returns one of the following values:

S_OK.
The call succeed, and the operation will be a forming operation.
E_UNEXPECTED
IClusCfgClusterInfo::IsJoining or IClusCfgClusterInfo::IsEvicted is TRUE.

Any other HRESULT value indicates that the call failed.

Remarks

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetIPAddress

[This is preliminary documentation and subject to change.]

The SetIPAddress method stores the IP address to be used to form the cluster.

HRESULT SetIPAddress(
  ULONG ulDottedQuadIn
);

Parameters

ulDottedQuadIn
[in] IP address in dotted quad format.

Return Values

If the SetIPAddress method successfully stores the IP address, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetJoining

[This is preliminary documentation and subject to change.]

The SetJoining method sets the commit action to add a node to the cluster.

HRESULT SetJoining(
  BOOL fJoiningIn
);

Parameters

fJoiningIn
[in] If TRUE, this will cause a node to join a cluster when the changes are committed.

Return Values

The SetJoining method returns one of the following values:

S_OK.
The call succeed, and the operation will be a joining operation.
E_UNEXPECTED
IClusCfgClusterInfo::IsForming or IClusCfgClusterInfo::IsEvicted is TRUE.

Any other HRESULT value indicate that the call failed.

Remarks

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetName

[This is preliminary documentation and subject to change.]

The SetName method stores a new name for the cluster, to take effect when the cluster configuration is committed. If the node is joining, this will be the cluster to be joined.

HRESULT SetName(
  BSTR bstrNameIn
);

Parameters

bstrNameIn
[in] The name of the user wants to assigned the cluster.

Return Values

The SetName method returns one of the following values:

S_OK.
Success.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the the call failed.

Remarks

The name assigned to the cluster is the fully qualified domain name—for example, example.microsoft.com. In forming the cluster, this is the resulting cluster name. In joining the cluster, this is the sponsor's cluster name.

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetNetworkInfo

[This is preliminary documentation and subject to change.]

The SetNetworkInfo method stores the network to be used for the cluster IP address and cluster name.

HRESULT SetNetworkInfo(
  IClusCfgNetworkInfo* piccniIn
);

Parameters

piccniIn
[in] Pointer to the network to use for the cluster IP address and name.

Return Values

If the SetNetworkInfo method successfully stores the network, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgClusterInfo::SetSubnetMask

[This is preliminary documentation and subject to change.]

The SetSubnetMask method stores the subnet mask to be used to form the cluster. In joining, this is the subnet mask of the sponsor.

HRESULT SetSubnetMask(
  ULONG ulDottedQuadIn
);

Parameters

ulDottedQuadIn
[in] Subnet mask in dotted quad format.

Return Values

If the SetSubnetMask method successfully stores the subnet mask, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

This method is typically called only by the cluster. Do not call this method from a component running on the server.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgCredentials

[This is preliminary documentation and subject to change.]

The IClusCfgCredentials interface sets and retrieves user credentials.

Methods in Vtable Order

The IClusCfgCredentials interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgCredentials Method | Description
SetCredentials | Sets user credentials.
GetCredentials | Gets user credentials.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgCredentials::GetCredentials

[This is preliminary documentation and subject to change.]

The GetCredentials method retrieves the user credentials.

HRESULT GetCredentials(
  BSTR* pbstrUserOut,
  BTSR* pbstrDomainOut,
  BTSR* pbstrPasswordOut
);

Parameters

pbstrUserOut
[out] Pointer to a BSTR that receives the user name.
pbstrDomainOut
[out] Pointer to a BSTR that receives the domain name.
pbstrPasswordOut
[out] Pointer to a BSTR that receives the user's password.

Return Values

If the GetCredentials method successfully retrieves the credentials, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgCredentials::SetCredentials

[This is preliminary documentation and subject to change.]

The SetCredentials method sets the user credentials.

HRESULT SetCredentials(
  BSTR bstrUserIn,
  BTSR bstrDomainIn,
  BTSR bstrPasswordIn
);

Parameters

bstrUserIn
[in] The user name.
bstrDomainIn
[in] The domain name.
bstrPasswordIn
[in] The user's password.

Return Values

If the SetCredentials method successfully sets the credentials, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgEvictCleanup

[This is preliminary documentation and subject to change.]

Do not use. This is not a public interface. It will soon be removed from ClusCfgServer.idl.


IClusCfgGroupCfg

[This is preliminary documentation and subject to change.]

The IClusCfgGroupCfg interface allows you to get and set the name of a resource's group after the resource has been created. When implementing IClusCfgManagedResourceCfg::PostCreate, use the IUnknown pointer passed to that method to query for the IClusCfgGroupCfg interface and call the appropriate method.

Methods in Vtable Order

The IClusCfgGroupCfg interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgGroupCfg Method | Description
SetName | Changes the name of the group in which the resource was created.
GetName | Retrieves the name of the group in which the resource was created.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgGroupCfg::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the name of the group in which the resource was created.

HRESULT GetName(
  DWORD* pcbSizeInout,
  LPWSTR pszNameOut
);

Parameters

pcbSizeInout
Pointer to the size of the pszNameOut string. On return, it is the size of the string in bytes (not WCHARs). If the provided buffer is too small, the required buffer size will be returned.
pszNameOut
The name to assign the group.

Return Values

The GetName method returns one of the following values:

S_OK.
GetName successfully retrieved the name of the group.
HRESULT_FROM_WIN32( ERROR_MORE_DATA )
The buffer size specified is too small.

Any other HRESULT value indicates that the call failed.

Remarks

Note that the name of group is the one set by the last resource. The ordering of the last resource is the resource that doesn't have anything depending on it. Do not cache this value as the name may change after control has been returned to the manager.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgGroupCfg::SetName

[This is preliminary documentation and subject to change.]

The SetName method sets the name of the group in which the resource was created.

HRESULT SetName(
  LPCWSTR pcszNameIn
);

Parameters

pcszNameIn
The name to assign the group.

Return Values

If the SetName method successfully sets the name of the group, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

Note that the name of group is the one set by the last resource. The ordering of the last resource is the resource that doesn't have anything depending on it.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgIPAddressInfo

[This is preliminary documentation and subject to change.]

The IClusCfgIPAddressInfo interface sets and retrieves information about an IP address.

Methods in Vtable Order

The IClusCfgIPAddressInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgIPAddressInfo Method | Description
GetUID | Retrieves the unique identifier for an IP address.
GetIPAddress | Retrieves an IP Address for the network interface.
SetIPAddress | Stores an IP Address of the network interface, to take effect when the cluster configuration is committed.
GetSubnetMask | Retrieves a subnet mask for the network interface.
SetSubnetMask | Stores a subnet mask for the network interface, to take effect when the cluster configuration is committed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgIPAddressInfo::GetIPAddress

[This is preliminary documentation and subject to change.]

The GetIPAddress method retrieves an IP address for the network interface.

HRESULT GetIPAddress(
  ULONG* pulDottedQuadOut
);

Parameters

pulDottedQuadOut
[out] Pointer to the IP address of the interface in dotted quad format.

Return Values

If the GetIPAddress method successfully retrieves the IP address, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgIPAddressInfo::GetSubnetMask

[This is preliminary documentation and subject to change.]

The GetSubnetMask method retrieves a subnet mask for the network interface.

HRESULT GetSubnetMask(
  ULONG* pulDottedQuadOut
);

Parameters

ulDottedQuadOut
[out] Pointer to the subnet mask of the interface in dotted quad format.

Return Values

If the GetSubnetMask method successfully retrieves the subnet mask, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgIPAddressInfo::GetUID

[This is preliminary documentation and subject to change.]

The GetUID method retrieve the unique identifier for the IP address. This is not a universally unique identifier (UUID or GUID). This identifier should match identifiers that can be generated on other nodes, but must be unique for the network the network interface card (NIC) is on.

HRESULT GetUID(
  BSTR* pbstrUIDOut
);

Parameters

pbstrUIDOut
[out] Pointer to a BSTR that receives the universally unique identifier. The caller should free this string by calling SysFreeString.

Return Values

The GetUID method returns one of the following values:

S_OK.
The method successfully retrieved the unique identifier.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgIPAddressInfo::SetIPAddress

[This is preliminary documentation and subject to change.]

The SetIPAddress method sets an IP address of the network interface, to take affect when the cluster configuration is committed.

HRESULT SetIPAddress(
  ULONG ulDottedQuadIn
);

Parameters

ulDottedQuadIn
[in] The IP address of the interface to be stored in dotted quad format.

Return Values

If the SetIPAddress method successfully sets the IP address, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgIPAddressInfo::SetSubnetMask

[This is preliminary documentation and subject to change.]

The SetSubnetMask method sets a subnet mask for the network interface, to take affect when the cluster configuration is committed.

HRESULT SetSubnetMask(
  ULONG ulDottedQuadIn
);

Parameters

ulDottedQuadIn
[in] The subnet mask of the interface to be stored in dotted quad format.

Return Values

If the SetSubnetMask method successfully sets the subnet mask, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo

[This is preliminary documentation and subject to change.]

The IClusCfgNetworkInfo interface enumerates the networks on the computer.

Methods in Vtable Order

The IClusCfgNetworkInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgNetworkInfo Method | Description
GetUID | Retrieves the unique identifier for the network.
GetName | Retrieves the user-friendly name of the network interface.
SetName | Sets a new name of the network interface, to take effect when the cluster configuration is committed.
GetDescription | Retrieves the description string for a network interface.
SetDescription | Stores a new description for the network interface, to take effect when the cluster configuration is committed.
GetPrimaryNetworkAddress | Get the primary network address.
SetPrimaryNetworkAddress | Set the primary network address.
IsPublic | Returns whether the network has been configured to be a public network.
SetPublic | Sets the "public property" of a network interface. The change will not take effect until the configuration has been committed.
IsPrivate | Returns whether the network has been configured to be a private network.
SetPrivate | Sets the "private property" of a network interface. The change will not take effect until the configuration has been committed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::GetDescription

[This is preliminary documentation and subject to change.]

The GetDescription method retrieves the description string for a network interface.

HRESULT GetDescription(
  BSTR* pbstrDescriptionOut
);

Parameters

pbstrDescription
[out] Pointer to a BSTR that receives the description of the network. The caller should free this string by calling SysFreeString.

Return Values

The GetDescription method returns one of the following values:

S_OK
The method successfully retrieved the description.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the user-friendly name of the interface.

HRESULT GetName(
  BSTR* pbstrNameOut
);

Parameters

pbstrNameOut
[out] Pointer to a BSTR that receives the network interface name. The caller should free this string by calling SysFreeString.

Return Values

The GetName method returns one of the following values:

S_OK
The method successfully retrieved the user-friendly name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::GetPrimaryNetworkAddress

[This is preliminary documentation and subject to change.]

The GetPrimaryNetworkAddress method retrieves the primary network address.

HRESULT GetPrimaryNetworkAddress(
  IClusCfgIPAddressInfo** ppIPAddressOut
);

Parameters

ppIPAddressOut
[out] Pointer to the IClusCfgIPAddressInfo interface.

Return Values

If the GetPrimaryNetworkAd method successfully retrieves the primary network address, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::GetUID

[This is preliminary documentation and subject to change.]

The GetUID method retrieves the unique identifier for the network. This is not a universally unique identifier (UUID or GUID). This identifier should match identifiers that can be generated on other nodes, but must be unique for the network the network interface card (NIC) is on.

HRESULT GetUID(
  BSTR* pbstrUIDOut
);

Parameters

pbstrUIDOut
[out] Pointer to a BSTR that receives the universally unique identifier. The caller should free this string by calling SysFreeString.

Return Values

The GetUID method returns one of the following values:

S_OK
The method successfully retrieved the unique identifier.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::IsPrivate

[This is preliminary documentation and subject to change.]

The IsPrivate method determines if the network has been configured to be a private network.

HRESULT IsPrivate( void );

Parameters

This method has no parameters.

Return Values

The IsPrivate method returns one of the following values:

S_OK.
The network has been configured to be a private network.
S_FALSE
The network has not been configured to be a private network

Any other HRESULT value indicates that the call failed.

Remarks

The IsPrivate and IClusCfgNetworkInfo::IsPublic methods allow you to determine the role of a network (see Role Property for Networks). Refer to the following table:

IsPublic | IsPrivate | Network role
S_OK | S_OK | ClusterNetworkRoleInternalAndClient
S_OK | S_FALSE | ClusterNetworkRoleClientAccess
S_FALSE | S_OK | ClusterNetworkRoleInternal
S_FALSE | S_FALSE | ClusterNetworkRoleNone

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::IsPublic

[This is preliminary documentation and subject to change.]

The IsPublic method determines if the network has been configured to be a public network. Note that a network interface can be both public and private.

HRESULT IsPublic( void );

Parameters

This method has no parameters.

Return Values

Return Values

The IsPublic method returns one of the following values:

S_OK.
The network has been configured to be a public network.
S_FALSE
The network has not been configured to be a public network.

Any other HRESULT value indicates that the call failed.

Remarks

The IsPublic and IClusCfgNetworkInfo::IsPrivate methods allow you to determine the role of a network (see Role Property for Networks). Refer to the following table:

IsPublic | IsPrivate | Network Role
S_OK | S_OK | ClusterNetworkRoleInternalAndClient
S_OK | S_FALSE | ClusterNetworkRoleClientAccess
S_FALSE | S_OK | ClusterNetworkRoleInternal
S_FALSE | S_FALSE | ClusterNetworkRoleNone

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::SetDescription

[This is preliminary documentation and subject to change.]

The SetDescription method sets a new description for the network interface, to take effect when the cluster configuration is committed.

HRESULT SetDescription(
  BSTR bstrDescriptionIn
);

Parameters

bstrDescriptionIn
[in] The description to be assigned to the interface.

Return Values

The SetDescription method returns one of the following values:

S_OK
The method successfully set a new description.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::SetName

[This is preliminary documentation and subject to change.]

The SetName method sets a new name for the network interface, to take effect when the cluster configuration is committed.

HRESULT SetName(
  BSTR bstrNameIn
);

Parameters

bstrNameIn
[in] The name of the user wants to assigned the interface.

Return Values

The SetName method returns one of the following values:

S_OK
The method successfully set a new name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::SetPrimaryNetworkAddress

[This is preliminary documentation and subject to change.]

The SetPrimaryNetworkAd method sets the primary network address.

HRESULT SetPrimaryNetworkAddress(
  IClusCfgIPAddressInfo* pIPAddressIn
);

Parameters

pIPAddressIn
[in] Pointer to the IClusCfgIPAddressInfo interface.

Return Values

If the SetPrimaryNetworkAd method successfully sets the address, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::SetPrivate

[This is preliminary documentation and subject to change.]

The SetPrivate method sets the private property of a network interface. The change will not take effect until the configuration has been committed.

HRESULT SetPrivate(
  BOOL fIsPrivateIn
);

Parameters

fIsPrivateIn
[in] Determines the network interface is private. If TRUE the interface will be marked as a private interface. If FALSE the interface will be marked as not a private interface.

Return Values

If the method successfully sets the private property, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNetworkInfo::SetPublic

[This is preliminary documentation and subject to change.]

The SetPublic method sets the public property of a network interface. The change will not take effect until the configuration has been committed.

HRESULT SetPublic(
  BOOL fIsPublicIn
);

Parameters

fIsPublicIn
[in] Determines if the network interface is public. If TRUE, the interface will be marked to be a public interface. If FALSE the interface will be marked as not a public interface.

Return Values

If the method successfully sets the public property, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo

[This is preliminary documentation and subject to change.]

The IClusCfgNodeInfo interface sets and retrieves information about the node configuration.

Methods in Vtable Order

The IClusCfgNodeInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgNodeInfo Method | Description
GetName | Retrieves the node's fully qualified domain name.
SetName | Stores the new name for the node. This does not take effect until after the changes have been committed.
IsMemberOfCluster | Returns whether the node is part of a cluster.
GetClusterConfigInfo | Returns a pointer to the IClusCfgClusterInfo interface if the node is part of a cluster.
GetOSVersion | Retrieves the version of the operating system.
GetClusterVersion | Retrieves the version of the cluster.
GetDriveLetterMappings | Retrieves the drive letter mappings on the node.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::GetClusterConfigInfo

[This is preliminary documentation and subject to change.]

The GetClusterConfigInfo method returns a pointer to the IClusCfgClusterInfo interface if the node is part of a cluster.

HRESULT GetClusterConfigInfo(
  IClusCfgClusterInfo** ppClusCfgClusterInfoOut
);

Parameters

ppClusCfgClusterInfoOut
[out] Pointer to the IClusCfgClusterInfo interface.

Return Values

If the GetClusterConfigInfo method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::GetClusterVersion

[This is preliminary documentation and subject to change.]

The GetClusterVersion method retrieves the version of the cluster.

HRESULT GetClusterVersion(
  DWORD* pdwNodeHighestVersion,
  DWORD* pdwNodeLowestVersion
);

Parameters

pdwNodeHighestVersion
[out] Pointer to the highest version in the cluster.
pdwNodeLowestVersion
[out] Pointer to the lowest version in the cluster.

Return Values

If the GetClusterVersion method successfully retrieves the cluster version, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::GetDriveLetterMappings

[This is preliminary documentation and subject to change.]

The GetDriveLetterMappings method retrieves the drive letter mappings on the node.

HRESULT GetDriveLetterMappings(
  SDriveLetterMapping dlmDriveLetterUsageOut
);

Parameters

rgDriveLetterUsage
[out] An array of flags representing A: through Z: (26) drive mappings to the device. These flags have one of the following values.
Value | Description
edluDriveLetterUnknown | The drive letter is mapped to an unknown device.
edluDriveLetterNoRootDirectory | There is no root directory for the drive letter.
edluDriveLetterRemovableDisk | The device mapped to the drive letter is removable.
edluDriveLetterFixedDisk | The drive letter is mapped to a fixed disk.
edluDriveLetterNetworkDrive | The drive letter is mapped to a network drive.
edluDriveLetterCompactDisc | The drive letter is mapped to a CD drive.
edluDriveLetterRAMDisk | The drive letter is mapped to a RAM disk.
edluDriveLetterSystem | The drive letter is mapped to a system device.
edluDriveLetterUnused | The drive letter is unused.
edluDriveLetterMax | The drive letter is the maximum value allowed.

Return Values

If the GetDriveLetterMappings method successfully retrieves the drive letter mappings, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves the node's fully qualified domain name—for example, example.microsoft.com.

HRESULT GetName(
  BSTR* pbstrNameOut
);

Parameter

pbstrNameOut
[out] Pointer to a BSTR that receives the name of the node. The caller must free this string by calling SysFreeString.

Return Values

The GetName method returns one of the following values:

S_OK.
The method successfully retrieved the name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::GetOSVersion

[This is preliminary documentation and subject to change.]

Retrieves the version of the operating system installed on the local computer.

HRESULT GetOSVersion(
  DWORD* pdwMajorVersionOut,
  DWORD* pdwMinorVersionOut,
  WORD* pwSuiteMaskOut,
  BYTE* pbProductTypeOut,
  BSTR* pbstrCSDVersionOut
);

Parameters

pdwMajorVersionOut
[out] Pointer to a DWORD that receives the major version of the operating system.
pdwMinorVersionOut
[out] Pointer to a DWORD that receives the major version of the operating system.
pwSuiteMaskOut
[out] Pointer to a WORD that receives the suite mask of the operating system.
pbProductTypeOut
[out] Byte array that receives the product type of the operating system.
pbstrCSDVersionOut
[out] Pointer to a BSTR that receives the CSD version of the operating system.

Return Values

Returns an HRESULT describing the results of the operation. Any value other than S_OK indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::IsMemberOfCluster

[This is preliminary documentation and subject to change.]

The IsMemberOfCluster method determines if the node is part of a cluster.

IsMemberOfCluster( void )

Parameters

This method has no parameters.

Return Values

The IsMemberOfCluster method returns one of the following values:

S_OK.
The node is part of a cluster.
S_FALSE
The node is not part of a cluster.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgNodeInfo::SetName

[This is preliminary documentation and subject to change.]

The SetName method is reserved for future use.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo

[This is preliminary documentation and subject to change.]

The IClusCfgPartitionInfo interface sets and retrieves partition information.

Methods in Vtable Order

The IClusCfgPartitionInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgPartitionInfo Method | Description
GetUID | Retrieves the unique identifier for the partition.
GetName | Retrieves the user-friendly name of the interface.
SetName | Stores a new name for the partition interface, to take effect when the cluster configuration is committed.
GetDescription | Retrieves the description string for a partition interface.
SetDescription | Stores a new name for the partition interface to, to take effect when the cluster configuration is committed.
GetDriveLetterMappings | Retrieves the drive letter mappings of the partition.
SetDriveLetterMappings | Stores the drive mappings for the device. The change will not take effect until the configuration has been committed.
GetSize | Retrieves the size of the partition in Megabytes.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::GetDescription

[This is preliminary documentation and subject to change.]

The GetDescription method retrieves the description string for a partition interface.

HRESULT GetDescription(
  BSTR* pbstrDescriptionOut
);

Parameters

pbstrDescription
[out] Pointer to a BSTR that receives the description of the partition. The caller must free this string by calling SysFreeString.

Return Values

The GetDescription method returns one of the following values:

S_OK
The method successfully retrieved the description.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::GetDriveLetterMappings

[This is preliminary documentation and subject to change.]

The GetDriveLetterMappings method retrieves the drive letter mappings of the partition.

HRESULT GetDriveLetterMappings(
  SDriveLetterMapping dlmDriveLetterUsageOut
);

Parameters

rgDriveLetterUsage
[out] An array of flags representing A: through Z: (26) drive mappings to the device. These flags have one of the following values.
Value | Description
edluDriveLetterUnknown | The drive letter is mapped to an unknown device.
edluDriveLetterNoRootDirectory | There is no root directory for the drive letter.
edluDriveLetterRemovableDisk | The device mapped to the drive letter is removable.
edluDriveLetterFixedDisk | The drive letter is mapped to a fixed disk.
edluDriveLetterNetworkDrive | The drive letter is mapped to a network drive.
edluDriveLetterCompactDisc | The drive letter is mapped to a CD drive.
edluDriveLetterRAMDisk | The drive letter is mapped to a RAM disk.
edluDriveLetterSystem | The drive letter is mapped to a system device.
edluDriveLetterUnused | The drive letter is unused.
edluDriveLetterMax | The drive letter is the maximum value allowed.

Return Values

If the method successfully retrieves the drive letter mappings, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves a user-friendly name of the partition.

HRESULT GetName(
  BSTR* pbstrNameOut
);

Parameters

pbstrNameOut
[out] Pointer to a BSTR that receives the partition name. The caller must free this string by calling SysFreeString.

Return Values

The GetName method returns one of the following values:

S_OK
The method successfully retrieved the name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::GetSize

[This is preliminary documentation and subject to change.]

The GetSize method retrieves the size of the partition in megabytes.

HRESULT GetSize(
  ULONG* pcMegaBytes
);

Parameters

pcMegaBytes
[out] Retrieves the partition size.

Return Values

If the GetSize method successfully retrieves the partition size, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::GetUID

[This is preliminary documentation and subject to change.]

The GetUID method retrieves the unique identifier for the partition. This is not a universally unique identifier (UUID or GUID). This identifier should match identifiers that can be generated on other nodes, but must be unique for the partition the network interface card (NIC) is on.

HRESULT GetUID(
  BSTR* pbstrUIDOut
);

Parameters

pbstrUIDOut
[out] Pointer to a BSTR that receives the universally unique identifier. The caller must free this string by calling SysFreeString.

Return Values

The GetUID method returns one of the following values:

S_OK
The method successfully retrieved the identifier.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::SetDescription

[This is preliminary documentation and subject to change.]

The SetDescription method sets a new name of the partition, to take effect when the cluster configuration is committed.

HRESULT SetDescription(
  BSTR bstrDescriptionIn
);

Parameters

bstrDescriptionIn
[in] The description to be assigned to the partition.

Return Values

The SetDescription method returns one of the following values:

S_OK
The method successfully set the new name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::SetDriveLetterMappings

[This is preliminary documentation and subject to change.]

The SetDriveLetterMappings method sets the drive mappings for the partition. The change will not take effect until the configuration has been committed.

HRESULT SetDriveLetterMappings(
  SDriveLetterMapping dlmDriveLetterMappingIn
);

Parameters

[in] rgDriveLetterMappings
An array of flags representing A: through Z: (26) drive mappings to the device. These flags have one of the following values.
Value Description
edluDriveLetterUnknown
edluDriveLetterNoRootDirectory
edluDriveLetterRemovableDisk
edluDriveLetterFixedDisk
edluDriveLetterNetworkDrive
edluDriveLetterCompactDisc
edluDriveLetterRAMDisk
edluDriveLetterSystem
edluDriveLetterUnused
edluDriveLetterMa

Return Values

If the method successfully sets the drive mappings, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgPartitionInfo::SetName

[This is preliminary documentation and subject to change.]

The SetName method sets a new name of the partition, to take effect when the cluster configuration is committed.

HRESULT SetName(
  BSTR bstrNameIn
);

Parameters

bstrNameIn
[in] The name of the user wants to assigned the interface.

Return Values

The SetName method returns one of the following values:

S_OK
The method successfully set the new name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate

[This is preliminary documentation and subject to change.]

The IClusCfgResourceCreate interface allows you to set properties and perform control code operations on resources while they are being created. When implementing IClusCfgManagedResourceCfg::Create, use the IUnknown pointer passed to that method to query for the IClusCfgResourceCreate interface and call the appropriate method.

Methods in Vtable Order

The IClusCfgResourceCreate interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgResourceCreate Method | Description
SetPropertyBinary | Sets a binary property.
SetPropertyDWORD | Sets a DWORD property.
SetPropertyString | Sets a string property.
SetPropertyExpandString | Sets an expandable string property.
SetPropertyMultiString | Sets a multiple string property.
SetPropertyUnsignedLargeInt | Sets an unsigned large integer property.
SetPropertyLong | Sets a long property.
SetPropertySecurityDescriptor | Sets a Security Descriptor property.
SetPropertyLargeInt | Sets a large integer property.
SendResourceControl | Safely performs a control code operation on a resource.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SendResourceControl

[This is preliminary documentation and subject to change.]

The SendResourceControl method safely performs a control code operation on the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SendResourceControl(
  DWORD dwControlCode,
  LPVOID lpInBuffer,
  DWORD cbInBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

dwControlCode
One of the resource control codes.
lpInBuffer
An input buffer appropriate to the control code. For more information see the description of lpInBuffer under ClusterResourceControl.
cbInBufferSize
Size in bytes of the input buffer.
lpOutBuffer
An output buffer appropriate to the control code. For more information see the description of lpInBuffer under ClusterResourceControl.
cbOutBufferSize
Size in bytes of the output buffer.
lpcbBytesReturned
Returns the actual size of the data returned in lpOutBuffer, if any. See the description of lpcbBytesReturned under ClusterResourceControl.

Return Values

If the SendResourceControl method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyBinary

[This is preliminary documentation and subject to change.]

The SetPropertyBinary method sets a binary property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyBinary(
  LPCWSTR pcszNameIn,
  const DWORD cbSizeIn,
  const BYTE* pbyteIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
cbSizeIn
Size in bytes of the property value.
pbyteIn
Pointer to a byte array containing the property value.

Return Values

If the SetPropertyBinary method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyDWORD

[This is preliminary documentation and subject to change.]

The SetPropertyDWORD method sets a DWORD property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyDWORD(
  LPCWSTR pcszNameIn,
  const DWORD dw
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
dw
The property value.

Return Values

If the SetPropertyDWORD method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyExpandString

[This is preliminary documentation and subject to change.]

The SetPropertyExpandString method sets an expandable string property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyExpandString(
  LPCWSTR pcszNameIn,
  LPCWSTR pcszStringIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
pcszStringIn
Expandable string containing the property value.

Return Values

If the SetPropertyExpandString method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyLargeInt

[This is preliminary documentation and subject to change.]

The SetPropertyLargeInt method sets a large integer property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyLargeInt(
  LPCWSTR pcszNameIn,
  const LARGE_INTEGER lIntIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
lIntIn
Large integer specifying the property value.

Return Values

If the SetPropertyLargeInt method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyLong

[This is preliminary documentation and subject to change.]

The SetPropertyLong method sets a long integer property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyLong(
  LPCWSTR pcszNameIn,
  const LONG lLongIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
lLongIn
Long integer specifying the property value.

Return Values

If the SetPropertyLong method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyMultiString

[This is preliminary documentation and subject to change.]

The SetPropertyMultiString method sets a multi-string property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyMultiString(
  LPCWSTR pcszNameIn,
  const DWORD cbMultiStringIn,
  LPCWSTR pcszMultiStringIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
cbMultiStringIn
Size in bytes of the buffer pointed to by the pcszMultiStringIn parameter.
pcszMultiStringIn
Pointer to a contiguous null-terminated series of null-terminated Unicode strings containing the property value.

Return Values

If the SetPropertyMultiString method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertySecurityDescriptor

[This is preliminary documentation and subject to change.]

The SetPropertySecurityDescriptor method sets a security descriptor property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertySecurityDescriptor(
  LPCWSTR pcszNameIn,
  const SECURITY_DESCRIPTOR* pcsdIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
pcsdIn
Pointer to a SECURITY_DESCRIPTOR structure specifying the property value.

Return Values

If the SetPropertySecurityDescriptor method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyString

[This is preliminary documentation and subject to change.]

The SetPropertyString method sets a string property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyString(
  LPCWSTR pcszNameIn,
  LPCWSTR pcszStringIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
pcszStringIn
Null-terminated Unicode string containing the property value.

Return Values

If the SetPropertyString method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceCreate::SetPropertyUnsignedLargeInt

[This is preliminary documentation and subject to change.]

The SetPropertyUnsignedLargeInt method sets an unsigned large integer property for the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SetPropertyUnsignedLargeInt(
  LPCWSTR pcszNameIn,
  const ULARGE_INTEGER ulIntIn
);

Parameters

pcszNameIn
Null-terminated Unicode string containing the property name.
ulIntIn
Unsigned large integer specifying the property value.

Return Values

If the SetPropertyUnsignedLargeInt method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

For a list of common resource properties see Resource Common Properties.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePostCreate

[This is preliminary documentation and subject to change.]

The IClusCfgResourcePostCreate interface allows you to rename and perform control code operations on resources after they are created. When implementing IClusCfgManagedResourceCfg::PostCreate, use the IUnknown pointer passed to that method to query for the IClusCfgResourcePostCreate interface and call the appropriate method.

Methods in Vtable Order

The IClusCfgResourcePostCreate interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgResourcePostCreate Method | Description
ChangeName | Changes the name of the resource.
SendResourceControl | Initiates a control code operation for the resource.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePostCreate::ChangeName

[This is preliminary documentation and subject to change.]

The ChangeName method changes the name of the resource being configured by IClusCfgManagedResourceCfg.

HRESULT ChangeName(
  LPCWSTR pcszNameIn
);

Parameters

pcszNameIn
Null-terminated Unicode string specifying the name to assign the resource.

Return Values

If the ChangeName method successfully changes the name, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePostCreate::SendResourceControl

[This is preliminary documentation and subject to change.]

The SendResourceControl method safely performs a control code operation on the resource being configured by IClusCfgManagedResourceCfg.

HRESULT SendResourceControl(
DWORD   dwControlCode,
LPVOID  lpInBuffer,
DWORD   cbInBufferSize,
LPVOID  lpOutBuffer,
DWORD   cbOutBufferSize,
LPDWORD lpcbBytesReturned
);

Parameters

dwControlCode
One of the resource control codes.
lpInBuffer
An input buffer appropriate to the control code. For more information see the description of lpInBuffer under ClusterResourceControl.
cbInBufferSize
Size in bytes of the input buffer.
lpOutBuffer
An output buffer appropriate to the control code. For more information see the description of lpInBuffer under ClusterResourceControl.
cbOutBufferSize
Size in bytes of the output buffer.
lpcbBytesReturned
Returns the actual size of the data returned in the lpOutBuffer parameter, if any. See the description of lpcbBytesReturned under ClusterResourceControl.

Return Values

If the SendResourceControl method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePreCreate

[This is preliminary documentation and subject to change.]

The IClusCfgResourcePreCreate interface allows you to specify a resource's type, class, and dependencies prior to its actual creation. When implementing IClusCfgManagedResourceCfg::PreCreate, use the IUnknown pointer passed to that method to query for the IClusCfgResourcePreCreate interface and call the appropriate method.

Methods in Vtable Order

The IClusCfgResourcePreCreate interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgResourcePreCreate Method | Description
SetDependency | Informs the post configuration manager that a resource has a dependency on another type of resource and if the resource needs the resource for shared access or exclusive access.
SetType | A managed resource must call this to indicate its resource type. Failure to call this during precreate will result in your resource not being created.
SetClassType | A managed resource sets this to indicate that its resource type can be considered to be of a class of resource. You may call this multiple times to indicate all the classes you belong to.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePreCreate::SetType

[This is preliminary documentation and subject to change.]

The SetType method sets the type of a managed resource. A managed resource must call this method. Failure to call this method during precreate will result in your resource not being created.

HRESULT SetType(
  CLSID* pclsidIn
);

Parameters

pclsidIn
Pointer to the GUID of the resource type.

Return Values

If the method successfully sets the resource type, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePreCreate::SetClassType

[This is preliminary documentation and subject to change.]

The SetClassType method sets the type of a class of managed resources. A managed resource calls this method to indicate that its resource type can be considered to be of a class of resource. A resource may call this method multiple times to indicate all the classes it belongs to.

HRESULT SetClassType(
  CLSID* pclsidIn
);

Parameters

pclsidIn
Pointer to the GUID of the resource class type.

Return Values

If the SetClassType method successfully sets the class type, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourcePreCreate::SetDependency

[This is preliminary documentation and subject to change.]

The SetDependency method informs the post configuration manager that a resource has a dependency on another type of resource. The method also indicates whether the resource needs the dependent resource for shared access or exclusive access.

HRESULT SetDependency(
  LPCLSID pclsidDepResTypeIn,
  EDependencyFlags dflagIn
);

Parameters

pclsidDepResTypeIn
The CLSID of the type of resource that a resource is requesting a dependency on. These are documented in the SDK or by the third-party resource.
dfIagIn
Flags to modify the dependency relationship. The following are defined flags.
Flag | Meaning
dfSHARED | The dependent resource can be shared.
dfEXCLUSIVE | The dependent resource can not be shared.

Return Values

If the method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeCreate

[This is preliminary documentation and subject to change.]

The IClusCfgResourceTypeCreate interface creates a resource type during cluster configuration. A pointer to this interface is provided to components that participate in resource type configuration during cluster configuration.

Methods in Vtable Order

The IClusCfgResourceTypeCreate interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgResourceTypeCreate Method | Description
Create | Creates a cluster resource type.
RegisterAdminExtensions | Registers the cluster administrator extension DLLs for a resource type.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeCreate::Create

[This is preliminary documentation and subject to change.]

The Create method creates a cluster resource type.

HRESULT Create(
  const WCHAR* pcszResTypeNameIn,
  const WCHAR* pcszResTypeDisplayNameIn,
  const WCHAR* pcszResDllNameIn,
  DWORD dwLooksAliveIntervalIn,
  DWORD dwIsAliveIntervalIn
);

Parameters

pcszResTypeNameIn
[in] Name of the resource type
pcszResTypeDisplayNameIn
[in] Display name of the resource type
pcszResDllNameIn
[in] Name (with or without path information) of DLL of the resource type.
dwLooksAliveIntervalIn
[in] Looks-alive interval for the resource type (in milliseconds).
dwIsAliveIntervalIn
[in] Is-alive interval for the resource type (in milliseconds).

Return Values

If the Create method successfully creates the resource type, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeCreate::RegisterAdminExtensions

[This is preliminary documentation and subject to change.]

The RegisterAdminExtensions method registers the cluster administrator extensions for a resource type.

HRESULT RegisterAdminExtensions(
  const WCHAR* pcszResDllNameIn,
  ULONG cExtClsidCountIn,
  const CLSID* rgclsidExtClsidsIn
);

Parameters

pcszResTypeNameIn
[in] Name of the resource type for which the extensions are to be registered.
cExtClsidCountIn
[in] Number of extension class identifiers in the rgclsidExtClsidsIn parameter.
rgclsidExtClsidsIn
[in] Pointer to an array of class identifiers of cluster administrator extension DLLs. This can be NULL if cExtClsidCountIn is 0.

Return Values

If the RegisterAdminExtensions method successfully registers the extension DLLs, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgServer

[This is preliminary documentation and subject to change.]

The IClusCfgServer interface gathers information about nodes, resources, and networks.

Methods in Vtable Order

The IClusCfgServer interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgServer Method | Description
GetClusterNodeInfo | Returns information about the cluster node on which an IClusCfgServer object is present.
GetManagedResourcesEnum | Retrieves an enumeration of the resources on the computer that can be managed by the Cluster service.
GetNetworksEnum | Retrieves an enumeration of all the networks on this computer.
CommitChanges | Commits the changes to the node.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgServer::CommitChanges

[This is preliminary documentation and subject to change.]

The CommitChanges method commits the changes to the node and allows the node to join or form a cluster.

HRESULT CommitChanges( void )

Parameters

This method has no parameters.

Return Values

If the CommitChanges method successfully commits the changes, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgServer::GetClusterNodeInfo

[This is preliminary documentation and subject to change.]

The GetClusterNodeInfo method returns information about the cluster node on which an IClusCfgServer object is present.

HRESULT GetClusterNodeInfo(
  IClusCfgNodeInfo** ppClusterNodeInfoOut
);

Paremeters

ppClusterNodeInfoOut
[out] Pointer to an IClusCfgNodeInfo interface.

Return Values

If the GetClusterNodeInfo method successfully returns the information, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgServer::GetManagedResourcesEnum

[This is preliminary documentation and subject to change.]

The GetManagedResourcesEnum method get an enumeration of the resources on this computer that can be managed by the Cluster service.

HRESULT GetManagedResourcesEnum(
  IEnumClusCfgManagedResources** ppEnumManagedResourcesOut
);

Parameters

ppEnumManagedResourcesEnumOut
[out] Pointer to an IEnumClusCfgManagedResources interface.

Return Values

If the GetManagedResourcesEnum method successfully gets the enumeration, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgServer::GetNetworksEnum

[This is preliminary documentation and subject to change.]

The GetNetworksEnum method gets an enumeration of all the networks on the computer.

HRESULT GetNetworksEnum(
  IEnumClusCfgNetworks** ppEnumNetworksOut
);

Parameter

ppEnumNetworksOut
[out] Pointer to an IEnumClusCfgNetworks interface.

Return Values

The GetNetworksEnum method successfully gets the enumeration, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgIPAddresses

[This is preliminary documentation and subject to change.]

The IEnumClusCfgIPAddresses interface enumerates the IP addresses on the adapter.

Methods in Vtable Order

The IEnumClusCfgIPAddresses interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IEnumClusCfgIPAddresses Method | Description
Next | Retrieves a specified number of items in the enumeration sequence.
Skip | Skips over a specified number of elements in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgIPAddresses::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumClusCfgIPAddresses** ppEnumIPAddressesOut
);

Parameters

ppEnumIPAddressesOut
[out] Pointer to a pointer that receives the address of IEnumClusCfgManagedResources pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined.

Return Values

The Clone method returns one of the following values:

S_OK
The method successfully created another enumerator.
E_INVALIDARG
The ppEnumIPAddressesOut parameter is invalid.
E_OUTOFMEMORY
Out of memory.
E_UNEXPECTED
Unknown error.

Remarks

A client can use Clone to record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgIPAddresses::Next

[This is preliminary documentation and subject to change.]

The Next method retrieves the next cNumberRequestedIn items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through the pcNumberFetchedOut parameter (unless the caller passed in NULL for that parameter).

HRESULT Next(
  ULONG cNumberRequestedIn,
  IClusCfgIPAddressInfo** rgpIPAddressInfoOut,
  ULONG* pcNumberFetchedOut
);

Parameters

cNumberRequestedIn
[in] number of elements being requested.
rgpIPAddressInfoOut
[out] Array of size cNumberRequestedIn (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
pcNumberFetchedOut
[out] Pointer to the number of elements actually supplied in the rgpIPAddressInfoOut parameter. Caller can pass in NULL if cNumberRequestedIn is one.

Return Values

The Next method returns one of the following values:

S_OK.
The method successfully retrieved the items, and the number of items supplied is cNumberRequestedIn.
S_FALSE
The number of items supplied is not cNumberRequestedIn.

Any other HRESULT value indicates that the call failed.

Remarks

There is no more data to enumerate when the pcNumberFetchedOut parameter is zero and HRESULT is S_FALSE.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgIPAddresses::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( void );

Parameters

This method has no parameters.

Return Values

If the Reset method successfully reset the enumeration sequence, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgIPAddresses::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of items in the enumeration sequence.

HRESULT Skip(
  ULONG cNumberToSkip
);

Parameters

cNumberToSkip
[in] The number of elements to be skipped.

Return Values

The Skip method returns one of the following values:

S_OK.
The specified number of items have been skipped.
S_FALSE
The method has reached the end of the enumeration sequence.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgNetworks

[This is preliminary documentation and subject to change.]

The IEnumClusCfgNetworks interface enumerates the networks on the computer.

Methods in Vtable Order

The IEnumClusCfgNetworks interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IEnumClusCfgNetworks Method | Description
Next | Retrieves a specified number of items in the enumeration sequence.
Skip | Resets the enumeration sequence to the beginning.
Reset | Skips over a specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgNetworks::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumClusCfgNetworks** ppEnumNetworksOut
);

Parameters

ppEnumNetworksOut
[out] Pointer to a pointer that receives the address of IEnumClusCfgManagedResources pointer variable that receives the interface pointer to the enumeration object. If the method is unsuccessful, the value of this output variable is undefined.

Return Values

The Clone method returns one of the following values:

S_OK
The method successfully created another enumerator.
E_INVALIDARG
The ppEnumIPAddressesOut parameter is invalid.
E_OUTOFMEMORY
Out of memory.
E_UNEXPECTED
Unknown error .

Remarks

A client can use Clone to record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgNetworks::Next

[This is preliminary documentation and subject to change.]

The Next method retrieves the next cNumberRequestedIn items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through the pcNumberFetchedOut parameter (unless the caller passed in NULL for that parameter).

HRESULT Next(
  ULONG cNumberRequestedIn,
  IClusCfgNetworkInfo** rgpNetworkInfoOut,
  ULONG* pcNumberFetchedOut
);

Parameters

cNumberRequestedIn
[in] Number of elements being requested.
rgpNetworkInfoOut
[out] Array of size cNumberRequestedIn (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
pcNumberFetchedOut
[out] Pointer to the number of elements actually supplied in the rgpNetworkInfoOut parameter. Caller can pass in NULL if cNumberRequestedIn is one.

Return Values

The Next method returns one of the following values:

S_OK.
The method successfully retrieved the items, and the number of items supplied is cNumberRequestedIn.
S_FALSE
The number of items supplied is not cNumberRequestedIn.

Any other HRESULT value indicates that the call failed.

Remarks

There is no more data to enumerate when the pcNumberFetchedOut parameter is zero and HRESULT is S_FALSE.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgNetworks::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( void );

Parameters

This method has no parameters.

Return Values

If the method successfully resets the enumeration sequence, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgNetworks::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG cNumberToSkip
);

Parameters

cNumberToSkip
[in] The number of elements to be skipped.

Return Values

The Skip method returns one of the following values:

S_OK.
The specified number of items have been skipped.
S_FALSE
The method has reached the end of the enumeration sequence.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgPartitions

[This is preliminary documentation and subject to change.]

The IEnumClusCfgPartitions interface enumerates the partitions on a storage device that the Cluster service can manage.

Methods in Vtable Order

The IEnumClusCfgPartitions interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IEnumClusCfgPartitions Method | Description
Next | Retrieves a specified number of items in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over a specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgPartitions::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumClusCfgPartitions** ppEnumPartitions
);

Parameters

ppEnumPartitions
[out] Pointer to a pointer that receives the address of an IEnumClusCfgPartitions interface containing the same enumeration state as the current interface.

Return Values

The Clone method returns one of the following values:

S_OK
The method successfully created another enumerator.
E_INVALIDARG
The ppEnumIPAddressesOut parameter is invalid.
E_OUTOFMEMORY
Out of memory.
E_UNEXPECTED
Unknown error.

Remarks

A client can use Clone to record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgPartitions::Next

[This is preliminary documentation and subject to change.]

The Next method retrieves the next cNumberRequestedIn items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through the pcNumberFetchedOut parameter (unless the caller passed in NULL for that parameter).

HRESULT Next(
  ULONG cNumberRequestedIn,
  IClusCfgPartitionInfo** rgpPartitionInfoOut,
  ULONG* pcNumberFetchedOut
);

Parameters

cNumberRequestedIn
[in] number of elements being requested.
rgpPartitionInfoOut
[out] Array of size cNumberRequestedIn (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
pcNumberFetchedOut
[out] Pointer to the number of elements actually supplied in the rgpPartitionInfoOut parameter. Caller can pass in NULL if cNumberRequestedIn is one.

Return Values

The Next method returns one of the following values:

S_OK.
The method successfully retrieved the items, and the number of items supplied is cNumberRequestedIn.
S_FALSE
The number of items supplied is not cNumberRequestedIn.

Any other HRESULT value indicates that the call failed.

Remarks

There is no more data to enumerate when the pcNumberFetchedOut parameter is zero and HRESULT is S_FALSE.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgPartitions::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning

HRESULT Reset( void );

Parameters

This method has no parameters

Return Values

If the method successfully resets the enumeration sequence, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgPartitions::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG cNumberToSkip
);

Parameters

cNumberToSkip

[in] The number of elements to be skipped.

Return Values

The Skip method returns one of the following values:

S_OK.
The specified number of items have been skipped.
S_FALSE
The method has reached the end of the enumeration sequence.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


User-Implemented Interfaces

[This is preliminary documentation and subject to change.]

The following interfaces can be implemented by a third-party components.

Interface | Description
IClusCfgCapabilities | Determines the capabilities of a node.
IClusCfgInitialize | Initializes a configuration object.
IClusCfgManagedResourceCfg | Creates and configures resources.
IClusCfgManagedResourceInfo | Provides information about managed resources to the cluster.
IClusCfgMemberSetChangeListener | Allows a component to be notified of when the local computer joins or leaves a cluster.
IClusCfgResourceTypeInfo | Allows a component to configure resource types during cluster configuration.
IClusCfgStartupListener | Allows a component to be notified when the Cluster service has started.
IClusCfgStartupNotify | Enumerates the startup listeners and informs them that the Cluster service has started on the local node.
IEnumClusCfgManagedResources | Enumerates managed resources.


IClusCfgCapabilities

[This is preliminary documentation and subject to change.]

The IClusCfgCapabilities interface allows you to cancel the pending installation of the Cluster service on a computer.

Methods in Vtable Order

The IClusCfgCapabilities interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgCapabilitiesmethod | Description
CanNodeBeClustered | Determines whether the Cluster service can be installed on the local computer.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgCapabilities::CanNodeBeClustered

[This is preliminary documentation and subject to change.]

The CanNodeBeClustered method allows or prevents the Cluster service from being installed on the local computer.

HRESULT CanNodeBeClustered( void );

Parameters

This method has no parameters.

Return Values

Return S_OK if it is okay for the Cluster service to be installed on the local computer. Return S_FALSE if you want to prevent the installation. You can also return E_NOTIMPL to indicate no preference one way or the other.

Remarks

The cluster calls this method when it is about to install the Cluster service on a computer. Implement this interface if there are circumstances under which you do not want a node to be clustered. For example, Terminal Services is incompatible with the Cluster service. Terminal Services can implement this interface to block all attempts to install the Cluster service

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgInitialize

[This is preliminary documentation and subject to change.]

The IClusCfgInitialize interface initializes a configuration object.

Methods in Vtable Order

The IClusCfgInitialize interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgInitialize Method | Description
Initialize | Registers callback functions, locale IDs, etc.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgInitialize::Initialize

[This is preliminary documentation and subject to change.]

The Initialize method registers callback functions, locale IDs, etc.

HRESULT Initialize(
  IUnknown* punkCallbackIn,
  LCID lcidIn
);

Parameters

punkCallbackIn
[in] Pointer to the callback interface.
lcidIn
[in] The locale ID to be used for strings that are passed.

Return Values

If the Initialize method successfully registers the callback function, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Example Code

The following example illustrates a typical implementation of Initialize.

STDMETHODIMP
CClusCfgMyResourceType::Initialize(
      IUnknown *   punkCallbackIn,
      LCID         lcidIn
    )
{
    HRESULT hr = S_OK;

    m_lcid = lcidIn;

    if ( punkCallbackIn != NULL )
    {
        IClusCfgCallback * pcccCallback = NULL;

        // Query for the IClusCfgCallback interface.
        hr = punkCallbackIn->QueryInterface( __uuidof( pcccCallback ), reinterpret_cast< void ** >( &pcccCallback ) );
        if ( SUCCEEDED( hr ) )
        {
            // Store the pointer to the IClusCfgCallback interface in the
            // member variable. Do not call pcccCallback->Release()
            m_cpcccCallback.Attach( pcccCallback );
        }
    } // if: the callback punk is not NULL

    return hr;

} //*** CClusCfgMyResourceType::Initialize()

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceCfg

[This is preliminary documentation and subject to change.]

Components implement the IClusCfgManagedResourceCfg interface to facilitate resource creation and configuration.

Methods in Vtable Order

The IClusCfgManagedResourceCfg interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgManagedResourceCfg Method | Description
PreCreate | Prepares for resource creation.
Create | Creates a resource.
PostCreate | Configures the resource after it has been created.
Evict | Cleans up a resource when a node is evicted from the cluster.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceCfg::Create

[This is preliminary documentation and subject to change.]

The Cluster Configuration Wizard calls the Create method to have the component create a new resource instance.

HRESULT Create(
  IUnknown* punkServicesIn
);

Parameters

punkServicesIn
[out] Pointer to an IUnknown interface that can be queried for creation services.

Return Values

Return S_OK if the resource is successfully created. Any other HRESULT value indicates that the call failed.

Remarks

Do not use any Cluster API (clusapi.h) functions when implementing this method. Your implementation should:

  1. Create the resource.
  2. Use the punkServicesIn pointer to obtain an IClusCfgResourceCreate interface to:
    • Set resource properties.
    • Perform control code operations.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceCfg::Evict

[This is preliminary documentation and subject to change.]

The cluster calls the Evict method to warn the component that a node has been evicted from the cluster.

HRESULT Evict(
  IUnknown* punkServicesIn
);

Parameters

punkServicesIn
[out] Pointer to an IUnknown interface that can be queried to access services to this interface.

Return Values

Return S_OK if the operation is successful. Any other HRESULT value indicates that the operation failed.

Remarks

Implement the Evict method in your component if you need to clean up or change any resources on the node being evicted.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceCfg::PostCreate

[This is preliminary documentation and subject to change.]

The cluster calls the PostCreate method to allow the component to configure a newly-created resource.

HRESULT PostCreate(
  IUnknown* punkServicesIn
);

Parameters

punkServicesIn
[out] Pointer to an IUnknown interface that can be queried for creation services.

Return Values

Return S_OK if the resource is successfully created. Any other HRESULT value indicates that the call failed.

Remarks

Do not use any Cluster API (clusapi.h) functions when implementing this method. Your implementation should:

  1. Create the resource.
  2. Use the IClusCfgResourceCreate interface to:
    • Set resource properties.
    • Perform control code operations.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceCfg::PreCreate

[This is preliminary documentation and subject to change.]

The PreCreate method is called by the post configuration manager to determine the requirements of the resource. Querying the punkServicesIn allows the managed resource to use services provided by the manager.

HRESULT PreCreate(
  IUnknown* punkServicesIn
);

Parameters

punkServicesIn
[out] Pointer to an IUnknown interface that can be queried for services provided by the post configuration manager and to set its dependencies.

Return Values

If the PreCreate method successfully determines the resource's requirements, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo

[This is preliminary documentation and subject to change.]

The IClusCfgManagedResourceInfo interface provides information about a single managed resource.

Methods in Vtable Order

The IClusCfgManagedResourceInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgManagedResourceInfo Method | Description
GetUID | Retrieves the unique identifier for a resource.
GetName | Retrieves the user-friendly name of the resource.
SetName | Stores a new name for the resource, to take effect when the cluster configuration is committed.
IsManaged | Returns whether the resource is managed by the cluster.
SetManaged | Sets a resource to be configured as being managed by the cluster.
IsQuorumDevice | Returns whether the resource is set as the quorum resource.
SetQuorumedDevice | Causes the resource to be configured as the quorum resource in the cluster.
IsQuorumCapable | Returns whether the resource is capable or being set as the quorum resource.
GetDriveLetterMappings | Retrieves the drive mappings for the resource (if any).
SetDriveLetterMappings | Stores the drive mappings for the resource. The change will not take effect until the configuration has been committed.
IsDeviceJoinable | Returns whether a managed resource is joinable.
SetDeviceJoinable | Sets a managed resource as joinable.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::GetDriveLetterMappings

[This is preliminary documentation and subject to change.]

The GetDriveLet method retrieves the drive mappings for the resource (if any).

HRESULT GetDriveLetterMappings(
  SDriveLetterMapping dlmDriveLetterMappingsOut
);

Parameters

rgDriveLetterMappings
[out] An array of flags representing A: through Z: (26) drive mappings to the resource. These flags have one of the following values.
Value | Description
edluDriveLetterUnknown | The drive letter maps to an unknown device.
edluDriveLetterNoRootDirectory | The drive letter does not map to a root directory.
edluDriveLetterRemovableDisk | The drive letter maps to a removable disk.
edluDriveLetterFixedDisk | The drive letter maps to a fixed disk.
edluDriveLetterNetworkDrive | The drive letter maps to a network drive.
edluDriveLetterCompactDisc | The drive letter maps to a CD drive.
edluDriveLetterRAMDisk | The drive letter maps to a RAM disk.
edluDriveLetterSystem | The drive letter maps to a system device.
edluDriveLetterUnused | The drive letter is not used.

Return Values

If the GetDriveLet method successfully retrieved the drive mappings, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::GetName

[This is preliminary documentation and subject to change.]

The GetName method retrieves a user-friendly name of the resource.

HRESULT GetName(
  BSTR* pbstrNameOut
);

Parameters

pbstrNameOut
[out] Pointer to a BSTR that receives the resource name. The caller should free this string by calling SysFreeString.

Return Values

The GetName method returns one of the following values:

S_OK
The method successfully retrieved the user-friendly name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::GetUID

[This is preliminary documentation and subject to change.]

The GetUID method retrieves the unique identifier for the resource. This is not a universally unique identifier (UUID or GUID). This identifier should match identifiers that can be generated on other nodes that can see this resource from a shared bus (such as a SCSI device).

HRESULT GetUID(
  BSTR* pbstrUIDOut
);

Parameters

pbstrUIDOut
[out] Pointer to a BSTR that receives the universally unique identifer. The caller should free this string by calling SysFreeString.

Return Values

The GetUID method returns one of the following values:

S_OK
The method successfully retrieved the unique identifier.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::IsDeviceJoinable

[This is preliminary documentation and subject to change.]

The IsDeviceJoinable method returns whether a managed resource is joinable.

HRESULT IsDeviceJoinable( void )

Parameters

This method has no parameters.

Return Values

The IsDeviceJoinable method returns one of the following values:

S_OK.
The call succeeded, and the result is TRUE.
S_FALSE
The call succeeded, and the result is FALSE.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::IsManaged

[This is preliminary documentation and subject to change.]

The IsManaged method determines if the resource is or will be managed by the cluster.

HRESULT IsManaged( void )

Parameters

This method has no parameters.

Return Values

The IsManaged method returns one of the following values:

S_OK.
The call succeeded, and the result is TRUE.
S_FALSE
The call succeeded, and the result is FALSE.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::IsQuorumCapable

[This is preliminary documentation and subject to change.]

The IsQuorumCapable method determines if the resource is capable of being set as the quorum resource.

HRESULT IsQuorumCapable( void );

Parameters

This method has no parameters.

Return Values

The IsQuorumCapable method returns one of the following values:

S_OK.
The call succeeded, and the result is TRUE.
S_FALSE
The call succeeded, and the result is FALSE.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::IsQuorumDevice

[This is preliminary documentation and subject to change.]

The IsQuorumDevice method determines if the resource is or will be set as the quorum resource.

HRESULT IsQuorumDevice( void )

Parameters

This method has no parameters.

Return Values

The IsQuorumDevice method returns one of the following values:

S_OK.
The call succeeded, and the result is TRUE.
S_FALSE
The call succeeded, and the result is FALSE.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::SetDeviceJoinable

[This is preliminary documentation and subject to change.]

The SetDeviceJoinable method sets a managed resource as joinable.

HRESULT SetDeviceJoinable( void )

Parameters

This method has no parameters.

Return Values

The SetDeviceJoinable method returns one of the following values:

S_OK.
The call succeeded, and the result is TRUE.
S_FALSE
The call succeeded, and the result is FALSE.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::SetDriveLetterMappings

[This is preliminary documentation and subject to change.]

The SetDriveLetterMappings method sets the drive mappings for the resource. The change will not take effect until the configuration has been committed.

HRESULT SetDriveLetterMappings(
  SDriveLetterMapping dlmDriveLetterMappingIn
);

Parameters

rgDriveLetterMappings
[in] An array of flags representing A: through Z: (26) drive mappings to the resource. These flags have one of the following values.
Value | Description
edluDriveLetterUnknown | The drive letter maps to an unknown device.
edluDriveLetterNoRootDirectory | The drive letter does not map to a root directory.
edluDriveLetterRemovableDisk | The drive letter maps to a removable disk.
edluDriveLetterFixedDisk | The drive letter maps to a fixed disk.
edluDriveLetterNetworkDrive | The drive letter maps to a network drive.
edluDriveLetterCompactDisc | The drive letter maps to a CD drive.
edluDriveLetterRAMDisk | The drive letter maps to a RAM disk.
edluDriveLetterSystem | The drive letter maps to a system device.
edluDriveLetterUnused | The drive letter is not used.

Return Values

If the SetDriveLetterMappings method successfully sets the drive mappings, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::SetManaged

[This is preliminary documentation and subject to change.]

The SetManaged method sets the resource to be configured as being managed by the cluster.

HRESULT SetManaged(
  BOOL fIsManagedIn
);

Parameters

fIsManagedIn
[in] If TRUE, the resource will be marked as being managed by the cluster.

Return Values

If the SetManaged method successfully sets the resource, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::SetName

[This is preliminary documentation and subject to change.]

The SetName method set a new name for the resource, to take effect when the cluster configuration is committed.

HRESULT SetName(
  BSTR bstrNameIn
);

Parameters

bstrNameIn
[in] The name of the user wants to assigned the resource.

Return Values

The SetName method returns one of the following values:

S_OK
The method successfully set a new name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgManagedResourceInfo::SetQuorumedDevice

[This is preliminary documentation and subject to change.]

The SetQuorumDevice method sets the resource to be configured as the quorum resource in the cluster.

HRESULT SetQuorumedDevice(
  BOOL fIsQuorumDeviceIn
);

Parameters

fIsQuorumDeviceIn
[in] If TRUE, the resource will be marked to be the quorum resource.

Return Values

The SetQuorumDevice method returns one of the following values:

S_OK
The method successfully set the resource.
E_UNEXPECTED
The resource is not capable of being a quorum resource.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgMemberSetChangeListener

[This is preliminary documentation and subject to change.]

The IClusCfgMemberSetChangeListener interface is implemented by a component in order to be notified when the local computer joins or leaves a cluster—in other words, when the member set of a cluster changes as a result of a cluster configuration operation on the local computer.

Methods in Vtable Order

The IClusCfgMemberSetChangeListener interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgMemberSetChangeListener Method | Description
Notify | Notifies a component that the computer has either joined or left a cluster.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgMemberSetChangeListener::Notify

[This is preliminary documentation and subject to change.]

The Notify method is called to notify a component that the local computer has either joined or left a cluster. During this call, a component typically performs operations that are required to switch it from the "clustered" to "non-clustered" mode or vice versa. For example, an application that implements this interface could use this function to create its resource type when the local computer joins a cluster. If the computer has just become part of a cluster, the Cluster service is guaranteed to be running when this method is called. Querying the IUnknown interface allows the listener to get more information about the event that caused the listener to be notified.

HRESULT Notify(
  IUnknown* punkClusterInfoIn
);

Parameters

punkClusterInfoIn
[in] Pointer to an IUnknown interface that can be queried for services provided by the caller of this function. Typically, the component that this IUnkown pointer refers to also implements the IClusCfgClusterInfo interface.

Return Values

If the method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeInfo

[This is preliminary documentation and subject to change.]

The IClusCfgResourceTypeInfo interface is implemented by components in order to configure resource types during cluster configuration.

Methods in Vtable Order

The IClusCfgResourceTypeInfo interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgResourceTypeInfo Method | Description
CommitChanges | Create or deletes resource types according to the state of the local computer.
GetTypeName | Provides the name of the resource type to the cluster.
GetTypeGUID | Provides the globally unique identifier of the resource type to the cluster.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeInfo::CommitChanges

[This is preliminary documentation and subject to change.]

Components implement the CommitChanges interface to create or delete resource types according to the state of the local computer.

HRESULT CommitChanges(
  IUnknown* punkClusterInfoIn,
  IUnknown* punkResTypeServicesIn
);

Parameters

punkClusterInfoIn
[in] Pointer to an IUnknown interface that the resource type can query for services provided by the caller of this function. Typically, the component that this IUnkown pointer refers to also implements the IClusCfgClusterInfo interface.
punkResTypeServicesIn
[in] Pointer to the IUnknown interface of a component that provides methods that help configuring a resource type. For example, during a join or a form, IUnknown can be queried for the IClusCfgResourceTypeCreate interface, which provides methods for resource type creation.

Return Values

If the method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Remarks

The cluster calls CommitChanges whenever the local computer joins, forms, or is evicted from a cluster. In the case of joining or forming, the implementer should create and register resource types using IClusCfgResourceTypeCreate methods obtained through the punkResTypeServicesIn pointer. When CommitChanges is called after the local computer has been evicted, the implementer should delete and deregister resource types.

Example Code

The following example illustrates how a component might implement CommitChanges.

HRESULT
CClusCfgMyResourceType::CommitChanges(
      IUnknown * punkClusterInfoIn
    , IUnknown * punkResTypeServicesIn
    )
{
    HRESULT     hr = S_OK;
    DWORD       dwError = ERROR_SUCCESS;
    CComBSTR    bstrStatusReportText( L"An error occurred trying to load the status report text" );
    bool        fForming;
    bool        fJoining;
    bool        fEvicted;

    // Set the thread locale.
    SetThreadLocale( m_lcid );

    // Load the status report text first
    // TODO: Customize this string for your resource type.
    if ( ! bstrStatusReportText.LoadString( IDS_CONFIGURING_MY_RESOURCE_TYPE ) )
    {
        hr = E_UNEXPECTED;
        goto Cleanup;
    } // if: we could not load the status report text

    //
    // Validate parameters
    //
    if ( ( punkClusterInfoIn == NULL ) || ( punkResTypeServicesIn == NULL ) )
    {
        hr = E_POINTER;
        goto Cleanup;
    } // if: one of the arguments is NULL

    // Send a status report up to the UI.
    if ( m_cpcccCallback != NULL )
    {
        hr = m_cpcccCallback->SendStatusReport(
                  NULL
                , TASKID_Major_Configure_Resource_Types
                , TASKID_Minor_Configure_My_Resoure_Type
                , 0
                , 1
                , 0
                , hr
                , bstrStatusReportText
                , NULL
                , NULL
                );
    } // if: the callback pointer is not NULL

    if ( FAILED( hr ) )
    {
        goto Cleanup;
    } // if: we could not send a status report

    //
    // Find out what event caused this call.
    //

    {
        CComQIPtr< IClusCfgClusterInfo >    cpClusterInfo( punkClusterInfoIn );

        hr = cpClusterInfo->IsForming();
        if ( FAILED( hr ) )
            goto Cleanup;
            break;
        } // if: we could not determine if a cluster in being formed on this node

        fForming = ( hr == S_OK );

        hr = cpClusterInfo->IsJoining();
        if ( FAILED( hr ) )
        {
            goto Cleanup;
        } // if: we could not determine if this node is joining a cluster

        fJoining = ( hr == S_OK );

        hr = cpClusterInfo->IsEvicted();
        if ( FAILED( hr ) )
        {
            goto Cleanup;
        } // if: we could not determine if this node has been evicted from a cluster

        fEvicted = ( hr == S_OK );

        // hr may be S_FALSE here, so reset it.
        hr = S_OK;
    }

    // Check if we are forming or joining (but not both)
    if ( fForming ^ fJoining )
    {
        // If we are forming or joining, create our resource type.

        CComQIPtr< IClusCfgResourceTypeCreate >     cpResTypeCreate( punkResTypeServicesIn );

        hr = S_HrCreateResType( cpResTypeCreate );
        if ( FAILED( hr ) )
        {
            goto Cleanup;
        } // if: something went wrong with the creation of this resource type
    } // if: we are either forming or joining ( but not both )
    else
    {
        // We have to be forming, joining or have been evicted.
        // Both fForming and fJoining are set or fEvicted is not set.
        // This is an error.
        if ( fForming || ! fEvicted )
        {
            hr = E_UNEXPECTED;
            goto Cleanup;
        } // if both fForming and fJoining are set or if fEvicted is not set

        // If we are here, then this node has been evicted.
        // By default, no resource type specific processing need be done
        // during eviction.
        // TODO: Code for any additional evict processing may be added here.

    } // else: both fForming and fJoining have the same value

Cleanup:
    // Complete the status report
    if ( m_cpcccCallback != NULL )
    {
        HRESULT hrTemp = m_cpcccCallback->SendStatusReport(
                              NULL
                            , TASKID_Major_Configure_Resource_Types
                            , TASKID_Minor_Configure_My_Resoure_Type
                            , 0
                            , 1
                            , 1
                            , hr
                            , bstrStatusReportText
                            , NULL
                            , NULL
                            );

        if ( FAILED( hrTemp ) )
        {
            if ( hr == S_OK )
            {
                hr = hrTemp;
            } // if: no error has occurred so far, consider this as an error.
        } // if: we could not send a status report
    } // if: the callback pointer is not NULL

    return hr;

} //*** CClusCfgMyResourceType::CommitChanges()

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeInfo::GetTypeGUID

[This is preliminary documentation and subject to change.]

The GetTypeGUID method retrieves the globally unique identifier of this resource type.

HRESULT GetTypeGUID(
  GUID* pguidGUIDOut
);

Parameters

pguidGUIDOut
[out] Pointer to the GUID object which will receive the GUID of this resource type.

Return Values

The GetTypeGUID method returns one of the following values:

S_OK.
The call succeeded, and the pguidGUIDOut parameter points to the type GUID.
S_FALSE
The call succeeded, but this resource type does not have a GUID. The value of the GUID object pointed to by pguidGUIDOut is undefined after this call.

Any other HRESULT value indicates that the call failed.

Example Code

The following example illustrates how a component might implement GetTypeGUID.

// TODO: Replace this GUID with a GUID that represents your resource type
// GUID that identifies this resource type.
// {BAADBEEF-BAAD-F00D-BAAD-F00DBAADBEEF}
DEFINE_GUID( GUID_MyResourceType,
0xbaadbeef, 0xbaad, 0xf00d, 0xba, 0xad, 0xf0, 0x0d, 0xba, 0xad, 0xbe, 0xef);

HRESULT
CClusCfgMyResourceType::GetTypeGUID(
    GUID * pguidGUIDOut
    )
{
    HRESULT     hr = S_OK;

    if ( pguidGUIDOut == NULL )
    {
        hr = E_POINTER;
    } // if: the output pointer is NULL
    else
    {
        *pguidGUIDOut = GUID_MyResourceType;
    } // else: the output pointer is valid

    return hr;

} //*** CClusCfgMyResourceType::GetTypeGUID()

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgResourceTypeInfo::GetTypeName

[This is preliminary documentation and subject to change.]

The GetTypeName method retrieves the resource type name of this resource type.

HRESULT GetTypeName(
  BSTR* pbstrTypeNameOut
);

Parameters

pbstrTypeNameOut
[out] Pointer to a BSTR that receives the name of the resource type. The caller must free this string by calling SysFreeString.

Return Values

The GetTypeName method returns one of the following values:

S_OK.
The method successfully retrieved the type name.
E_OUTOFMEMORY
Out of memory.

Any other HRESULT value indicates that the call failed.

Example Code

The following example illustrates how a component might implement GetTypeName.

HRESULT
CClusCfgMyResourceType::GetTypeName(
    BSTR * pbstrTypeNameOut
    )
{
    HRESULT     hr = S_OK;

    if ( pbstrTypeNameOut == NULL )
    {
        hr = E_POINTER;
        goto Cleanup;
    } // if: the output pointer is NULL

    *pbstrTypeNameOut = SysAllocString( MY_RESOURCE_TYPE_NAME );
    if ( *pbstrTypeNameOut == NULL )
    {
        hr = E_OUTOFMEMORY;
        goto Cleanup;
    } // if: memory for the resource type name could allocated

Cleanup:
    return hr;

} //*** CClusCfgMyResourceType::GetTypeName()

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgStartupListener

[This is preliminary documentation and subject to change.]

The IClusCfgStartupListener interface is implemented by a component in order to be notified when the Cluster service has started.

Methods in Vtable Order

The IClusCfgStartupListener interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgStartupListener Method | Description
Notify | Notifies a component that the Cluster service has started on the local node.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgStartupListener::Notify

[This is preliminary documentation and subject to change.]

The Notify method is called to inform a component that the Cluster service has started on the local node.

HRESULT Notify(
  IUnknown* punkIn);

Parameters

punkIn
[in] Pointer to an IUnknown interface. The component that implements this interfacemay also provide services that are useful to the implementer of this method. For example, this component usually implements the IClusCfgResourceTypeCreate interface.

Return Values

If the Notify method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgStartupNotify

[This is preliminary documentation and subject to change.]

The IClusCfgStartupNotify interface is implemented by a component that the Cluster service creates an instance of. When the Cluster service calls the SendNotificationsmethod of this interface, the component will enumerate the startup listeners and inform them that the Cluster service has started on the local node.

Methods in Vtable Order

The IClusCfgStartupNotify interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IClusCfgStartupNotify Method | Description
SendNotifications | Informs the component that the Cluster service has started up. The Cluster Service calls this method so the component can send out notifications.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IClusCfgStartupNotify::SendNotifications

[This is preliminary documentation and subject to change.]

The SendNotifications method is called by the Cluster service to inform the implementer of this interface to send out notification of Cluster service startup to interested listeners. If this method is being called for the first time, the method waits till the post configuration steps are complete before sending out the notifications.

HRESULT SendNotifications( void );

Parameters

This method has no parameters.

Return Values

If the method succeeds, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgManagedResources

[This is preliminary documentation and subject to change.]

The IEnumClusCfgManagedResources interface enumerates all resources on this computer that the Cluster service can manage.

Methods in Vtable Order

The IEnumClusCfgManagedResources interface inherits the methods of IUnknown in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IEnumClusCfgManagedResources Method | Description
Next | Retrieves a specified number of items in the enumeration sequence.
Reset | Resets the enumeration sequence to the beginning.
Skip | Skips over a specified number of elements in the enumeration sequence.
Clone | Creates another enumerator that contains the same enumeration state as the current one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgManagedResources::Clone

[This is preliminary documentation and subject to change.]

The Clone method creates another enumerator that contains the same enumeration state as the current one.

HRESULT Clone(
  IEnumClusCfgManagedResources** ppEnumManagedResources
);

Parameters

ppEnumManagedResources
[out] Pointer to a pointer that receives the address of a copy of the parent IEnumClusCfgManagedResources interface.

Return Values

The Clone method returns one of the following values:

S_OK
The method successfully created another enumerator.
E_INVALIDARG
The ppEnumManagedResources parameter is invalid.
E_OUTOFMEMORY
Out of memory.
E_UNEXPECTED
Unknown error.

Remarks

A client can use Clone to record a particular point in the enumeration sequence, and then return to that point at a later time. The new enumerator supports the same interface as the original one.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgManagedResources::Next

[This is preliminary documentation and subject to change.]

The Next method retrieves the next cNumberRequestedIn items in the enumeration sequence. If there are fewer than the requested number of elements left in the sequence, it retrieves the remaining elements. The number of elements actually retrieved is returned through the pcNumberFetchedOut parameter (unless the caller passed in NULL for that parameter).

HRESULT Next(
  ULONG cNumberRequestedIn,
  IClusCfgManagedResourceInfo** rgpManagedResourceInfoOut,
  ULONG* pcNumberFetchedOut
);

Parameters

cNumberRequestedIn
[in] Number of elements being requested.
rgpManagedResourceInfoOut
[out] Array of size cNumberRequestedIn (or larger) of the elements of interest. The type of this parameter depends on the item being enumerated.
pcNumberFetchedOut
[out] Pointer to the number of elements actually supplied in the rgpManagedResourceInfoOut parameter. Caller can pass in NULL if cNumberRequestedIn is one.

Return Values

The Next method returns one of the following values:

S_OK.
The method successfully retrieved the items, and the number of items supplied is cNumberRequestedIn.
S_FALSE
The number of items supplied is not cNumberRequestedIn.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgManagedResources::Reset

[This is preliminary documentation and subject to change.]

The Reset method resets the enumeration sequence to the beginning.

HRESULT Reset( void );

Parameters

This method has no parameters.

Return Values

If the method successfully resets the enumeration sequence, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


IEnumClusCfgManagedResources::Skip

[This is preliminary documentation and subject to change.]

The Skip method skips over the next specified number of elements in the enumeration sequence.

HRESULT Skip(
  ULONG cNumberToSkip
);

Parameters

cNumberToSkip
[in] The number of elements to be skipped.

Return Values

The Skip method returns one of the following values:

S_OK.
The specified number of items have been skipped.
S_FALSE
The method has reached the end of the enumeration sequence.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgServer.idl.


Cluster Configuration Wizard Interface

[This is preliminary documentation and subject to change.]

The cluster configuration wizard interface allows you to launch the Cluster Configuration Wizard in either Create Cluster or Add Cluster Nodes mode. The wizard has the following interface:

IClusCfgWizard


IClusCfgWizard

[This is preliminary documentation and subject to change.]

The IClusCfgWizard interface provides the functions required to launch the Cluster Configuration Wizard in either Create Cluster or Add Cluster Nodes mode.

Methods in Vtable Order

The IClusCfgWizard interface inherits the methods of IUnknown and IDispatch in addition to the methods it defines.

IUnknown method | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch method | Description
GetTypeInfoCount | Retrieves the number of type information interfaces that an object provides (either 0 or 1).
GetTypeInfo | Gets the type information for an object.
GetIDsOfNames | Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.
Invoke | Provides access to properties and methods exposed by an object.

IClusCfgWizard method | Description
CreateCluster | launches the Cluster Wizard in Create Cluster mode.
AddClusterNodes | launches the Cluster Wizard in Add Cluster Nodes mode.
get_ClusterName | Property method that retrieves the default value for the cluster name if Create Cluster mode.
put_ClusterName | Property method that sets a default value for the cluster name if Create Cluster mode.
get_ServiceAccountUserName | Property method that retrieves the default value for the user name in the Cluster service account.
put_ServiceAccountUserName | Property method that sets a default value for the user name in the Cluster service account.
get_ServiceAccountPassword | Property method that retrieves the default value for the password in the Cluster service account.
put_ServiceAccountPassword | Property method that sets a default value for the password in the Cluster service account.
get_ServiceAccountDomainName | Property method that retrieves the default value for the domain name in the Cluster service account.
put_ServiceAccountDomainName | Property method that sets a default value for the domain name in the Cluster service account.
get_ClusterIPAddress | Property method that retrieves the default value for the cluster IP address.
put_ClusterIPAddress | Property method that sets a default value for the cluster IP address.
get_ClusterIPSubnet | Property method that retrieves the default value for the cluster IP subnet mask.
put_ClusterIPSubnet | Property method that sets a default value for the cluster IP subnet mask.
get_ClusterIPAddressNetwork | Property method that retrieves the default value for the network on which the cluster IP address is to be offered.
put_ClusterIPAddressNetwork | Property method that sets a default value for the network on which the cluster IP address is to be offered.
AddComputer | Adds a computer to the list of nodes for a cluster.
RemoveComputer | Removes a computer from the list of nodes for a cluster.
ClearComputerList | Removes all computers from the list of nodes for a cluster.

Properties

The IClusCfgWizard interface has the following properties.

Property | Description
ClusterIPAddress | The default value for the cluster IP address.
ClusterIPAddressNetwork | The default value for the cluster IP address.
ClusterIPSubnet | The default value for the cluster IP subnet mask.
ClusterName | The default value for the cluster name if Create Cluster mode.
ServiceAccountDomainName | The default value for the domain name in the Cluster service account.
ServiceAccountPassword | The default value for the password in the Cluster service account.
ServiceAccountUserName | The default value for the user name in the Cluster service account.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.


IClusCfgWizard::AddClusterNodes

[This is preliminary documentation and subject to change.]

The AddClusterNodes method launches the Cluster Wizard in Add Cluster Nodes mode.

HRESULT AddClusterNodes(
  HWND ParentHwndIn,
  BOOL* pfDoneOut
);

Parameters

ParentHwndIn
[in, defaultvalue( 0 ) ] Handle to the parent window (default NULL). If not NULL, the wizard will be positioned in the center of this window.
pfDoneOut
[out] Returns TRUE if committed, FALSE if canceled.

Return Values

If the AddClusterNodes method successfully launches the Cluster Wizard, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::AddComputer

[This is preliminary documentation and subject to change.]

The AddComputer method adds a computer to the list of nodes to form or join a cluster. The computer must be specified by a fully qualified domain name.

HRESULT AddComputer(
  BSTR bstrFQDNNameIn
);

Parameters

bstrFQDNNameIn
[in] Specifies the hostname of the computer to be added as a node. This must be a fully qualified domain name—for example, a name in the form hostname.domain.com.

Return Values

If AddComputer successfully adds the computer, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ClearComputerList

[This is preliminary documentation and subject to change.]

The ClearComputerList method removes all computers from the list of nodes to form or join a cluster.

HRESULT ClearComputerList( void );

Parameters

This method has no parameters.

Return Values:

If ClearComputerList successfully removes all computers from the list, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ClusterIPAddress

[This is preliminary documentation and subject to change.]

The ClusterIPAddress property represents the default value for the cluster IP address. HRESULT put_ClusterIPAddress(

  BSTR bstrIPAddressIn
);
HRESULT get_ClusterIPAddress(
  BSTR* pbstrIPAddressOut
);

Parameters

bstrIPAddressIn
[in] Specifies the default cluster IP address.
pbstrIPAddressOut
[out] Pointer to a BSTR that receives the default cluster IP address.

Return Values

If the property methods put_ClusterIPAddress and get_ClusterIPAddress succeed, they returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ClusterIPAddressNetwork

[This is preliminary documentation and subject to change.]

The ClusterIPAddressNetwork property represents the default value for the network on which the cluster IP address is to be offered. HRESULT put_ClusterIPAddressNetwork(

  BSTR bstrNetworkNameIn
);
HRESULT get_ClusterIPAddressNetwork(
  BSTR* pbstrNetworkNameOut );

Parameters

bstrNetworkNameIn
[in] Specifies the default cluster IP address.
pbstrNetworkNameOut
[out] Pointer to a BSTR that receives the default cluster IP address.

Return Values

If the property methods put_ClusterIPAddressNetwork and get_ClusterIPAddressNetwork succeed, they returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ClusterIPSubnet

[This is preliminary documentation and subject to change.]

The ClusterIPSubnet property represents the default value for the cluster IP subnet mask. HRESULT put_ClusterIPSubnet(

  BSTR bstrSubnetIn
);
HRESULT get_ClusterIPSubnet(
  BSTR* pbstrIPSubnetOut
);

Parameters

bstrSubnetIn
[in] Specifies the default IP subnet mask.
pbstrIPSubnetOut
[out] Pointer to a BSTR that receives the default IP subnet mask.

Return Values

If the property methods put_ClusterIPSubnet and get_ClusterIPSubnet succeed, they return S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ClusterName

[This is preliminary documentation and subject to change.]

The ClusterName property represents the default value for the cluster name if Create Cluster mode. Provide the mandatory name of the cluster before calling IClusCfgWizard::AddClusterNodes. Return the cluster name for a newly created cluster. This must be a fully qualified domain name for the cluster. The domain default will be determined from this string.

HRESULT put_ClusterName(
  BSTR bstrFQDNNameIn
);
HRESULT get_ClusterName(
  BSTR* pbstrFQDNNameOut
);

Parameters

bstrFQDNNameIn
[in] Specifies the default name for the cluster.
pbstrFQDNNameOut
[out] Pointer to a BSTR that receives the default name for the cluster.

Return Values

If property methods put_ClusterName and get_ClusterName succeed, they return S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::CreateCluster

[This is preliminary documentation and subject to change.]

The CreateCluster method launches the Cluster Configuration Wizard in Create Cluster mode.

HRESULT CreateCluster(
  HWND ParentHwndIn,
  BOOL* pfDoneOut
);

Parameters

ParentHwndIn
[in] Handle to the parent window (default NULL). If not NULL, the wizard will be positioned in the center of this window.
pfDoneOut
[out] Returns TRUE if committed, FALSE if canceled.

Return Values

If the CreateCluster method successfully launches the Cluster Wizard, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::RemoveComputer

[This is preliminary documentation and subject to change.]

The RemoveComputer method removes a computer from the list of nodes to form or join a cluster. This string must be the fully qualified domain name of the computer to be removed.

HRESULT RemoveComputer(
  BSTR bstrFQDNNameIn
);

Parameters

bstrFQDNNameIn
[in] Specifies the hostname of the computer to be removed as a node. This must be a fully qualified domain name—for example, a name in the form hostname.domain.com.

Return Values

If RemoveComputer successfully removes the computer, it returns S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ServiceAccountDomainName

[This is preliminary documentation and subject to change.]

The ServiceAccountDomainName property represents the default value for the domain name in the Cluster service account. HRESULT put_ServiceAccountDomainName(

  BSTR bstrDomainIn
);
HRESULT get_ServiceAccountDomainName(
  BSTR* pbstrDomainOut
);

Parameters

bstrDomainIn
[in] Specifies the default domain name.
pbstrDomainOut
[out] Pointer to a BSTR that receives the default domain name.

Return Values

If the property methods put_ServiceAccountDomainName and get_ServiceAccountDomainName succeed, they return S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ServiceAccountPassword

[This is preliminary documentation and subject to change.]

The ServiceAccountPassword property represents the default value for the password in the Cluster service account. The default value is NULL.

HRESULT put_ServiceAccountPassword(
  BSTR bstrPasswordIn
);
HRESULT get_ServiceAccountPassword(
  BSTR* pbstrPasswordOut
);

Parameters

bstrPasswordIn
[in] Specifies the default password.
pbstrPasswordOut
[out] Pointer to a BSTR that receives the default password.

Return Values

If the property methods put_ServiceAccountPassword and get_ServiceAccountPassword succeed, they return S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


IClusCfgWizard::ServiceAccountUserName

[This is preliminary documentation and subject to change.]

The ServiceAccountUserName property represents the default value for the user name in the Cluster service account. The default value is NULL.

HRESULT put_ServiceAccountUserName(
  BSTR bstrAccountNameIn
);
HRESULT get_ServiceAccountUserName(
  BSTR* pbstrAccountNameOut
);

Parameters

bstrAccountNameIn
[in] Specifies the default user name.
pbstrAccountNameOut
[out] Pointer to a BSTR that receives default the user name.

Return Values

If the property methods put_ServiceAccountUserName and get_ServiceAccountUserName succeed, they return S_OK.

Any other HRESULT value indicates that the call failed.

Requirements

Version: Requires Whistler.
Header: ClusCfgWizard.idl.

See Also

IClusCfgWizard


Server Cluster Glossary

A

active
A node that is running and participating in cluster operations.
arbitration
Process of obtaining ownership of the quorum resource. A quorum resource implements the Arbitrate and Release entry point functions in its resource DLL to support arbitration.
available disk
A cluster-capable disk that is not associated with any existing Physical Disk resource and that is not being used as the quorum resource.


C

Checkpoint Manager
Software component in the Cluster service that is responsible for saving data in the log file maintained by the quorum resource.
CIM
See Common Information Model.
CIM class
See WMI class.
client application
Application software that gathers data from the user, prepares it for the server, and issues a request to the server. The client presents data received from the server to the user through its own user interface.

See also client-server model.

client-server model
Architecture that splits an application into a front-end client component and a back-end server component. The client component gathers data from the user, prepares it for the server, and issues a request to the server. On the back end, the server waits for requests from its clients. When the server receives a request, it processes the request and returns the requested information to the client. The client then presents the data to the user through its own user interface.
cluster
Windows Clustering defines a cluster as is a group of independent computer systems, referred to as nodes, working together as a unified computing resource. Windows Clustering provides two different types of clusters: server clusters and network load balancing clusters.
Cluster Administrator
An application included with Windows Clustering that is used to manage and administer a server cluster. Cluster Administrator can run on any member of the trusted domain regardless of whether the computer is a cluster node.
Cluster Administrator extension
A dynamic-link library (DLL) that enables Cluster Administrator to manage a custom resource type. A Cluster Administrator extension uses the Cluster Administrator Extension API and is implemented as an in-process COM server.
Cluster Automation Server
The library of COM-based interfaces that developers writing in Microsoft® Visual Basic® and various scripting languages use to create cluster management applications for server clusters.
cluster-aware application
An application that runs on a node, is managed as a cluster resource, and is designed to be aware of and interact with the server cluster environment.
cluster-capable disk
A disk that satisfies the definition of a storage class resource. Because it can be owned by only one node at a time, a cluster-capable disk is not a shared disk.

Also called a cluster disk.

cluster database
A database containing property and configuration data for all cluster objects. The cluster database is synchronized across all nodes.
cluster disk
A disk that satisfies the definition of a storage class resource. Because it can be owned by only one node at a time, a cluster disk is not a shared disk.

Also called a cluster-capable disk.

cluster management application
A cluster-aware application used to manage and administer a server cluster. Cluster Administrator is an example of such an application.
cluster network driver
Server cluster software component that monitors the status of network paths between nodes and detects communication failure by using periodic messages called heartbeats.
cluster object
A physical or logical unit managed by the Cluster service. The cluster objects are nodes, networks, network interfaces, groups, resources, and resource types.

Also called cluster object.

Cluster Server
One of the former names for the Server Cluster API.

Other former names or pseudonyms include MSCS, Wolfpack, and Clustering Service

Cluster service
The essential software component that controls all aspects of server cluster operation and manages the cluster database. Each node in a server cluster runs one instance of the Cluster service.
cluster-unaware application
An application that can run on a node and be managed as a cluster resource but has no inherent knowledge of its environment. Cluster-unaware applications function the same regardless of whether they are running on a node in a server cluster or on a non-clustered system.
cluster version
Two version numbers that describe the versions of the Cluster service that are compatible with all active nodes. The cluster version is compared to a node's node version before the node is allowed to join a cluster. The cluster version changes as nodes join and leave the cluster. The GetClusterInformation function retrieves the cluster version.
Clustering Service
Obsolete name referring to the collection of Microsoft® Windows NT®/Windows 2000® software components and APIs that work together to implement server clusters.

See also Cluster Server, MSCS, Wolfpack.

Common Information Model (CIM)
A programming paradigm that describes how to represent real-world managed objects. Used for WMI class specification.
common property
An attribute possessed by every instance of a cluster object. For example, each node has a NodeName property
control code
A 32-bit value defined by the Server Cluster API used to initiate an operation on a cluster object or notify a resource DLL of changes to the cluster. Control codes are categorized as external or internal.
control code functions
A set of Server Cluster API functions that take control codes as parameters. Each cluster object has one control code function and many control codes, allowing a single function to initiate several different operations.
core network name resource
The Network Name resource for a server cluster.
custom resource type
A resource type defined by a third-party developer using the Server Cluster API. Creating a custom resource type involves writing a resource DLL and a Cluster Administrator extension.


D

Database Manager
Software component in the Cluster service that controls access to the cluster database.
data value
A single value associated with a property value. A cluster object property consists of one or more property values, each consisting of one or more data values. For example, if a property consists of multiple DWORD arrays, each array is considered a property value, and each array element is considered a data value.
dependency
A resource on which another resource depends. If resource A depends on resource B, then B is a dependency of A.
dependency relationship
Relationship between two resources where one resource depends on another resource to operate. Resources in a dependency relationship must be in the same group. Dependent resources are taken offline before, and brought online after, their dependencies.
dependent
A resource that depends on one or more resources in order to operate. If resource A depends on resource B, then resource A is dependent.
disk mirroring
Fault tolerant technique that writes data simultaneously to two disks using the same disk controller. The disks operate in tandem, constantly storing and updating the same files. Mirroring alone does not ensure data protection. If both disks fail at the same time, you still lose data.
disk striping
Spreading data over multiple disk drives. Data is interleaved by byte or sector blocks across the drives.
Domain Name System (DNS)
Service that maps node names to IP addresses.
DWORD-aligned
The alignment or spacing of data in a buffer. Data is DWORD-aligned if the byte size of each data value is an even multiple of a DWORD (4 bytes).


E

Event Log Manager
Software component in the Cluster service that is responsible for initialization and supports event notification.
expandable string
A string containing unexpanded references to environment variables, such as "\\%SystemRoot%\data".
expanded string
A string containing expanded references to environment variables
external control code
A control code that applications can use to initiate an operation on a cluster object. External control codes are passed as the dwControlCode parameter to control code functions.

See also internal control code.


F

failback
Process of moving a group back to its preferred node when the node becomes active after a failure.
failed
Describes a node or resource that has ceased operating and is unavailable to the cluster. Node or resource failure can trigger failover.
failover
Process of moving a group to another node in response to a node or resource failure.
Failover Manager
Software component in the Cluster service that works with the Resource Manager to manage resources and groups and initiate failover operations.
failover policy
Parameters that affect failover operations of a group. These parameters include the FailoverThreshold and FailoverPeriod properties.
failover time
Amount of time it takes a group to complete the failover process.
fault tolerant
Non-stop, 100% availability of resources. Clients never experience an interruption or loss of service.

See also high availability.

File Share resource
A file share managed as a cluster resource. The Cluster service defines the File Share resource type for managing File Share resources.


G

Generic Application resource
An application being managed as a cluster resource. The Cluster service defines the Generic Application resource type for managing Generic Application resources.
Generic Service resource
A Microsoft® Windows NT®/Windows® 2000 service being managed as a cluster resource. The Cluster service defines the Generic Service resource type for managing Generic Service resources.
Global Update Manager
Software component in the Cluster service that provides update services to the nodes in a cluster.
group
A collection of resources managed as a single cluster object. Typically a group contains all of the resources needed to run a specific application or service. Failover and failback always act on groups.


H

heartbeat
Message that is sent regularly between cluster network drivers on each node. Heartbeat messages are used to detect communication failure between cluster nodes.
high availability
Describes a resource that remains operational and usable by clients most of the time with a very low percentage of failures that interrupt service. Server clusters are designed to keep applications and other cluster resources highly available.

See also fault tolerant.

highly available
See high availability.


I

inactive
A node that is running but not participating in cluster operations.
interconnect
A network that connects nodes in a cluster.
internal control code
A control code used by the Cluster service to notify a resource DLL of changes to the cluster environment. Applications cannot use internal control codes; they must use external control codes.
IP Address resource
An IP address being managed as a cluster resource by the IP Address resource type. An IP Address resource can be used to create a virtual server.


L

Log Manager
Software component in the Cluster service that writes changes to the recovery log stored on the quorum resource.


M

major version
An integer used to identify a particular release of the Cluster service. This number is combined with the minor version to produce a version number.
MSCS
One of the former names for the Server Cluster API.

Other former names or pseudonyms include Cluster Server, Clustering Service, Wolfpack.

minor version
The build number of a particular release of the Cluster service. This number is combined with the major version to produce a version number.
Membership Manager
Software component in the Cluster service that maintains information about the cluster's current membership.
mixed mode
Describes a server cluster in which different nodes are running different versions of the Cluster service.


N

network
A cluster object that carries internal communication between nodes and/or provides client access to cluster resources.
network interface
See network interface card.
network interface card (NIC)
A hardware plug-in board that connects a node to a local area network. If the node is a member of a server cluster, the network interface is a cluster object

Also called adapter card.

Network Load Balancing cluster
One of two types of clusters provided by Windows Clustering that distributes and load balances network connections among servers, providing high availability and scalability for stateless TCP/IP applications and services.
Network Name resource
An network name being managed as a cluster resource by the Network Name resource type. A Network Name resource must be used with an IP Address resource, a combination referred to as a virtual server.
network partition
Situation that occurs when all networks designated to carry internal cluster communication fail and nodes cannot receive heartbeat signals from each other. Also known as split brain syndrome.
NIC
See network interface card.
node
A Microsoft® Windows NT® Server/Windows® 2000 system that is an active or inactive member of a server cluster.
Node Manager
Software component in the Cluster service that maintains all node and network configuration and state information. Also controls operation of the cluster network driver.
node version
Two version numbers that describe the lowest and highest versions of the Cluster service with which a node is compatible. A node's version is compared with the cluster version before it is allowed to join the cluster. The NodeHighestVersion and NodeLowestVersion properties specify the node version.


O

offline
A state describing a resource or group as unavailable to the cluster.
online
A state describing a resource or group as available to the cluster.


P

parameter block
A buffer that contains the data for one or more properties, or a pointer to the data. Entries in a property table contain an offset to a parameter block.
partitioned
A state in which one or more of the nodes in a server cluster cannot communicate with the other nodes.
paused
State that applies to a node that is a fully active member in the server cluster but cannot host groups. The paused state is provided for an administrator to perform maintenance.
pending
State that refers to a resource being brought online or taken offline.
persistent arbitration
The process by which a node gains control of the quorum resource and defends its control. The SCSI reserve and release functions can be used to implement this type of arbitration support.
Physical Disk resource
A cluster-capable disk being managed as a cluster resource by the Physical Disk resource type.
possible owner
A node on which a resource is capable of running. Each resource is associated with a list of possible owners. Resources will fail over only to nodes that are listed as possible owners.
preferred owner
A node on which a group prefers to run. Each group is associated with a list of preferred owners sorted in order of preference. During failover, the group is moved to the most-preferred available node on the list.
Print Spooler resource
A print spooler being managed as a cluster resource by the Print Spooler resource type.
private property
An attribute possessed by an individual instance of a cluster object. Other instances may or may not possess the same property.
property
An attribute associated with a cluster object that describes an identity or behavior for the object. A property can consist of multiple property values, each of which can consist of multiple data values. For example, if a property consists of multiple DWORD arrays, each array is considered a property value, and each array element is considered a data value.
property access
A characteristic of a property that determines the user's ability to change the property. A property's access can be read/write or read-only.
property list
A collection of information used to describe multiple properties in control code operations. Each entry in a property list consists of a value list containing a property name and one or more property values. Each property value, in turn, consists of one or more data values.
property scope
A characteristic of a property that determines which objects the property applies to. A property can be common or private in scope.
property status
A characteristic of a private property that determines whether the property must have a value. Private properties can have a status of required (must have a valid value) or optional (does not need a value).
property table
An array of RESUTIL_PROPERTY_ITEM structures used to store multiple properties.
property value
One of the values associated with a multivalue property. A cluster object property consists of one or more property values, each consisting of one or more data values. For example, if a property consists of multiple DWORD arrays, each array is considered a property value, and each array element is considered a data value.


Q

quorum-capable resource
A storage class resource that is an instance of a resource type implemented to support quorum resources. By default, only Physical Disk resources are quorum-capable, but developers can create resource types that support other kinds of storage class resources as quorum-capable resources.
quorum log
See recovery log.
quorum resource
The quorum-capable resource selected to maintain essential cluster data. The quorum resource stores a synchronized version of the cluster database as well as critical recovery information in a recovery log. The quorum resource guarantees that all nodes have access to the most recent database changes.


R

recovery log
A file that maintains a history of all of the transactions affecting the cluster database on all nodes. The recovery log is stored on the cluster's quorum resource and is also referred to as the quorum log.
resource
A physical or logical entity that is capable of being owned by a node, brought online and taken offline, moved between nodes, and managed as a cluster object. A resource can be owned by only a single node at any point in time. A resource is an instance of a resource type.
Resource API
Subset of Server Cluster API functions that allow a resource DLL to communicate with a Resource Monitor. Some of the functions are implemented by a resource DLL and others are implemented by the Resource Monitor.
resource class
Numeric value that is used to identify server cluster resources of similar capability, such as resources that can act as storage devices.
resource DLL
Dynamic-link library containing an implementation of the Resource API for a specific type of resource. The resource DLL is loaded into the address space of its Resource Monitor.
Resource Manager
Software component in the Cluster service that works with the Failover Manager to manage resources and groups and initiate failover operations.
Resource Monitor
Component of the Cluster service that manages communication between a node's Cluster service and one or more of its resources.
resource type
A cluster object used to categorize and manage resources sharing similar characteristics. A resource type is implemented in a resource DLL that manages all the resources of that type in the cluster.
rolling upgrade
The process of systematically upgrading each server cluster node while the other nodes continue to provide service. Administrators perform rolling upgrades by failing over all groups on a node, taking the node offline, upgrading the node, bringing it back online, failing back the groups to the node, and continuing to the next node.


S

SCSI
See Small Computer System Interface.
scalability
A measure of how well a computer system can grow to meet increasing demands.
server application
The server side of the client-server model. The server waits for requests from its clients. When it receives a request, the server processes it and returns the requested information to the client.
server cluster
The type of cluster that the Cluster service implements. Server clusters are characterized by high availability. The server cluster is one of two types of clusters provided by Microsoft® Windows Clustering.
Server Cluster API
Collection of functions that are implemented by the Cluster service and used by cluster-aware applications, cluster management applications, and resource DLLs. The Cluster API includes functions for managing cluster objects and the cluster database.
server cluster object
See cluster object.
service
Data or operation made available to network clients through a virtual server; not necessarily a Microsoft® Windows NT®/Windows® 2000 service.
shared disk
A disk shared between multiple owners simultaneously. Server clusters do not use shared disks. A cluster disk is owned by only one node at any point in time.
shared nothing model
Clustering architecture where systems share neither memory nor devices. Each processor has its own memory and a copy of the operating system. Connections between processors are optimized because messages are passed across a high-speed, dedicated bus. Server clusters implements this model.
shared resource
Cluster organization in which some resources are accessible to all systems in the cluster.
single point of failure
A single hardware or software component that prevents a cluster from functioning if the component fails. Administrators try to avoid single points of failure through redundancy and backup systems.
Small Computer System Interface (SCSI)
A protocol for connecting devices from several classes of peripherals to a host system without requiring modifications to hardware and software.
storage class resource
A data storage device that is accessible to all cluster nodes and that is able to operate as a cluster resource.
stripe set
See disk striping.
system
See node.


T

time service
A server cluster resource that maintains consistent time across all nodes.
unknown property
A user-defined property unsupported by any DLL. Use Cluster Utility Functions to work with unknown properties.


V

value list
A collection of data values that is used as the data portion of a property value in a property list. Each entry except the final one in a value list is made up of a CLUSPROP_VALUE structure and data. The final entry contains only the CLUSPROP_SYNTAX_ENDMARK value.
version number
A value that describes a version of the Cluster service as a combination of the major version and the minor version . Version numbers are used to determine whether a node can join a cluster. Examples of version numbers include the NodeHighestVersion and NodeLowestVersion properties.
virtual server
A group containing a Network Name resource, an IP Address resource, and additional resources necessary to run one or more applications or services. Clients can use the network name to access the resources in the group, analagous to using a computer name to access the services on a physical server. However, because a virtual server is a group, it can be failed over to another node without affecting the underlying name or address.


W

Windows Clustering
A feature of the Microsoft® Windows NT®/Windows® 2000 operating system that supports two different types of clusters: the server cluster and the network load balancing cluster.
Windows Internet Name Service (WINS)
An enhanced NetBIOS Name Server (NBNS) designed by Microsoft to register NetBIOS computer names and to resolve them to IP addresses for both local and remote hosts.
Windows Management Instrumentation (WMI)
A unified architecture for describing, accessing, and instrumenting objects. Part of this architecture is a large repository of CIM classes that WMI can use to carry out management tasks on specific objects.
WMI
See Windows Management Instrumentation.
WMI class
A template for a type of managed object. WMI classes are based on the Common Information Model (CIM), as implemented in Windows Management Instrumentation (WMI).
Wolfpack
One of the former pseudonyms for the Server Cluster API.

Other former names or pseudonyms include Cluster Server, Clustering Service, and MSCS.


Network Load Balancing Provider

Purpose

Network Load Balancing clusters balance TCP/IP connection loads across multiple ports and servers according to a configurable set of rules. The Network Load Balancing Provider allows developers to create customized, remote, scriptable administration tools for Network Load Balancing clusters.

Developer Audience

Programming with the provider means interacting with Windows Management Instrumentation (WMI). Developers are strongly advised to review the Platform SDK documentation on WMI, especially the information and examples pertaining to client-side or remote administration programming.

This documentation assumes that readers are familiar with WMI and the Network Load Balancing user interface, and that they have access to the Platform SDK documentation for WMI as well as the online help documentation for Network Load Balancing.

Run-Time Requirements

The Network Load Balancing Provider requires the Microsoft® Windows® 2000 Advanced Server or Datacenter Server operating system.

See Also

Microsoft Windows 2000 Help, Server Cluster APIs, WMI SDK

About the Network Load Balancing Provider

An overview of how Network Load Balancing works.

Using the Network Load Balancing Provider

Describes how to accomplish typical Network Load Balancing administrative tasks.

Network Load Balancing Provider Reference

Describes the Network Load Balancing Provider classes, their properties, and methods.

Feedback

Make error reports and feature requests directly to Microsoft.


Finding What You Need in Network Load Balancing

Information is presented in this document as follows.

Section | Content
About the Network Load Balancing Provider | An overview of how Network Load Balancing works and how the API can interact with the software
Using the Network Load Balancing Provider | An extensive sample demonstrating the various API method calls
Network Load Balancing Provider Reference | A description of the WMI classes, properties, and methods of the Network Load Balancing API
Network Load Balancing Glossary | Definitions of terms used in the Network Load Balancing documentation

For additional information on Network Load Balancing, see the Microsoft® Windows® 2000 Help documentation.


About the Network Load Balancing Provider

Network Load Balancing clusters dynamically distribute the flow of incoming TCP and UDP traffic among the cluster nodes according to a set of traffic-handling rules. The Network Load Balancing Provider allows applications to interact with Network Load Balancing clusters through the unified management framework of Windows Management Instrumentation (WMI).

The following sections provide more information on Network Load Balancing clusters and the Provider.

Section | Content
Network Load Balancing Clusters | Presents a brief overview of how the Network Load Balancing technology works.
How the Provider Works | Describes WMI provider architecture.
Configuring Clusters with the Provider | The Network Load Balancing Provider's role in cluster configuration.


Network Load Balancing Clusters

This section presents a brief overview of Network Load Balancing concepts. For details on Network Load Balancing configuration and administration, see the Windows 2000 online Help documentation.

Network Load Balancing enables all cluster nodes on a single subnet to concurrently detect incoming network traffic for one or more IP addresses.

The Network Load Balancing Driver

On each cluster node, a Network Load Balancing driver acts as a filter between the network driver and the higher layers of the TCP/IP stack to allow a portion of the incoming network traffic to be received by the node. How the traffic is filtered depends on the current set of traffic handling rules.

Host Priority

Every node (also called host) in the cluster must be assigned a host priority, a unique integer that identifies the node and determines the order in which traffic is handled by default. The node with the lowest priority handles all traffic not otherwise handled by the current set of rules.

Convergence

The cluster nodes exchange periodic messages and, in the event of a node failure, participate in a process called convergence.

Port Rules

Port rules determine how incoming connections are distributed among nodes. A port rule consists of the following parameters:

  • A range of port numbers to which the port rule applies.
  • The protocols (TCP, UDP, or both) to which the port rule applies.
  • The filtering mode for the port rule. The filtering mode determines how traffic is handled by the port rule and can be set to one of the following values.
Filtering mode | Description
Single-host filtering mode | One node (the node with the highest handling priority) handles all traffic. This mode load balances multiple, single-host applications.
Multiple-host filtering mode | Traffic is distributed across all cluster nodes according to the load percentage set for each node. This mode load balances a single, cluster-wide application.
Disabled | No traffic is accepted by the ports in the port range. When all of a node's ports are disabled, the node is said to be draining.

A port rule applies the filtering mode to all traffic of the specified protocol flowing into all ports in the specified range.


How the Provider Works

A provider is an architectural element of Windows Management Instrumentation (WMI). As a working definition, WMI defines a unified architecture for describing, accessing, and instrumenting objects. Part of this architecture is a large database of WMI classes used to carry out remote management tasks on specific objects.

A provider extends the WMI schema of classes to allow WMI to work with new types of objects. The Network Load Balancing Provider defines classes for querying and configuring Network Load Balancing clusters, nodes, and port rules.

The Network Load Balancing Provider has a set of unique behaviors not found in other providers. The following sections describe these behaviors as well as the intended usage model for the provider:

  • Connecting to WMI
  • Local and Remote Operations
  • Remote Control
  • Enumerating Nodes

For a complete description and definition of WMI, please see the Windows Management Instrumentation documentation in the Platform SDK.


Connecting to WMI

To use the Network Load Balancing Provider, your application establishes a connection to WMI and requests access to a namespace, often in the form of an object path such as "\\<computer name>\root\Microsoft_NLB". WMI creates a client-server connection between the computer system on which your application is running (the provider client) and the node that will load the provider and carry out provider operations (the provider node). The namespace you use determines how the provider node is selected. For more information, refer to the following sections:

  • Direct Connections
  • Routed Connections
  • Remote Administration


Direct Connections

You can connect directly to a specific node in the cluster by specifying an object path that resolves to the node's dedicated IP address. Direct connections offer several advantages:

  • The connection will succeed unless WMI cannot establish a network connection to the node based on the namespace. Network Load Balancing does not have to be running on the node.
  • You can configure the cluster IP address of the node without affecting your connection.
  • You can target configuration operations more effectively.

Node-specific object paths have the form:

\\<name>\root\MicrosoftNLB

where <name> can be any name or IP address that resolves to the dedicated IP address of a node.


Routed Connections

In a routed connection, you specify an object path that resolves to the cluster IP address and the WMI connection is routed to one of the cluster nodes based on the Network Load Balancing port rules. There are disadvantages associated with routed connections:

  • If cluster activity has been stopped on all nodes, the connection will fail.
  • You have no control over which node will be selected as the provider node.
  • If you change the cluster IP address of the provider node, you will lose your connection.

The recommended way to establish a connection to WMI is to use a direct connection.

Cluster object paths have the form:

\\<name>\root\MicrosoftNLB

where <name> can be any URL, name, or IP address that resolves to the cluster IP address.


Remote Administration

One of the benefits of WMI is its ability to facilitate remote administration. With the Network Load Balancing Provider, it is important to distinguish between the meaning of "remote" in "remote administration" versus the meaning of "remote" in "remote operations."

  • The word "remote" in remote administration refers to the WMI connection model. WMI implements a connection as a remote client/server connection regardless of whether the provider client and the provider node are different computer systems or the same computer system.
  • The word "remote" in remote operations refers to the relationship between the provider node and the effects of operations initiated by the provider. For more information see Local and Remote Operations).

Note that the physical relationship between the provider client and the provider node is irrelevant. You can run your application on a cluster node and establish a direct connection to that node, but this has no impact on whether operations are considered local or remote, and you are still performing remote administration.


Local and Remote Operations

The Network Load Balancing cluster software with which the provider interacts categorizes operations as local or remote based on the location of the effect of the operation relative to the origin of the operation:

  • If an operation originates from a node, and it affects the same node, the operation is local. A node always responds to local operations, regardless of the remote control setting.
  • If an operation originates from one node and it affects a another node, the operation is remote. Only nodes on which remote control is enabled respond to remote control operations.

The Network Load Balancing provider conforms to this architecture as follows:

  • If an operation originates from the provider node, and it affects the same node, the operation is local. Local operations include enumerating, instantiating, and using the classes representing the provider node and its settings and port rules.
  • If an operation originates from the provider node, and it affects a different node, the operation is remote. Remote operations include enumerating, instantiating, and using the classes representing the cluster or any node, setting, or port rule external to the provider node.

Although the Network Load Balancing provider allows remote operations, making use of remote operations in your application is not recommended for the following reasons:

  • Remote operations depend on remote control being enabled, which is a configuration with significant security issues (see the Network Load Balancing online help documentation). By relying on remote control being enabled, remote operations require the user or the application to put network security at risk.
  • Remote operations can produce inconsistent and unreliable results if some nodes have remote control enabled and others do not (see Enumerating Nodes). To guarantee that operations are applied uniformly across all nodes, use local operations.
  • Remote operations are unnecessary. You can configure an entire cluster safely and reliably through a series of local operations.

To maximize the effectiveness and security of your application, always perform local operations with the Network Load Balancing provider. For more information, see the Standard Usage Model for the Network Load Balancing provider.


Remote Control

In a Network Load Balancing cluster, each node has a remote control setting that determines whether or not it responds to remote operations.

  • If remote control is on, or enabled, the node responds to queries, changes settings, and otherwise participates in remote operations
  • If remote control is off, or disabled, the node will only participate in local operations.

The remote control setting has very significant security implications. For the details of these implications, see the Network Load Balancing online help.

The Network Load Balancing provider exposes the remote control setting through the RemoteControlEnabled property of the MicrosoftNLB_NodeSetting class. The intent of this property is to allow developers to design custom interfaces that give users the abillity to turn remote control on and off.

There is no reason for developers to use the RemoteControlEnabled property for any other purpose. You can perform all configuration and administration tasks through the provider using local operations.

In a Network Load Balancing cluster, the remote control setting on any node represents a security decision on the part of the user. Changing the setting even briefly without the user's informed consent contravenes the user's security policies and may compromise the network.


Enumerating Nodes

When you use the standard WMI enumeration procedures to enumerate nodes with the Network Load Balancing provider, the results vary as follows:

  • You always get a MicrosoftNLB_Node instance representing the provider node. This node is always listed first in the enumeration.
  • You will get additional MicrosoftNLB_Node instances for each node that is currently running Network Load Balancing and that has RemoteControlEnabled set to TRUE.

The following table illustrates enumeration results in a Network Load Balancing cluster consisting of nodes A, B, C, and D. The results shown for a node are obtained by connecting directly to the node (see Making Direct Connections) and enumerating all available nodes:

Provider node | Network Load Balancing is running | Cluster operations are enabled | Remote control is on | Enumeration results (in order of appearance)
A | yes | yes | yes | A, C
B | yes | yes | no | B, A, C
C | yes | no | yes | C, A
D | no | no | yes | error

  • Node D does not show up in any enumeration because Network Load Balancing is not running on that node.
  • Node C shows up in all enumerations even though cluster operations have been stopped on that node.
  • Node B appears only in enumerations performed from node B.
  • WMI allows a connection to Node D, but any provider operation will return an error because Network Load Balancing is not running on node D.

Because of the behavior described above, enumeration is not a reliable indicator of cluster membership. This is by design. Do not use enumeration as the basis of a cluster membership algorithm.


Configuring Clusters with the Provider

The Network Load Balancing Provider allows you to create customized administration tools for configuring Network Load Balancing clusters. The following sections describe the Provider's role in various aspects of cluster configuration.

Topic | Information
Standard Usage Model | Describes the recommended procedures for using the Network Load Balancing provider to configure clusters.
Remote Setup of a Network Load Balancing Cluster | Describes the process of performing a remote installation of Network Load Balancing.
Configuring User Interface Settings | Maps the settings shown on the Network Load Balancing Properties dialog to the Provider classes, properties, and methods that affect those settings.


Standard Usage Model

The most reliable and secure way to use the Network Load Balancing provider is to never make use of remote operations. This can be done by observing the following procedure:

To Configure a Cluster

  1. Independently obtain and maintain a list of cluster members which includes their dedicated IP addresses.
  2. Using the membership list, establish a direct connection with a cluster node.
    1. Obtain a MicrosoftNLB_Node class representing the node. If necessary, use class methods to initiate draining, suspend cluster activity, or otherwise halt the flow of traffic to the node.
    2. Obtain a MicrosoftNLB_NodeSetting class representing the node's configuration settings.
    3. Obtain MicrosoftNLB_PortRule classes representing the port rules associated with the node.
    4. Configure the node. See Configuring User Interface Settings. The SetToDefault method can be useful here.
    5. When all settings are correct, use the LoadAllSettings method to commit the changes to the cluster.
  3. Repeat step 2 until all cluster nodes have been configured.

This procedure works regardless of the remote control setting. All operations are local and restricted to one node at a time.


Remote Setup of a Network Load Balancing Cluster

Currently, there is no way to remotely bind the Network Load Balancing driver to the network interface card (NIC). The binding must be done manually through the Network and Dial-Up Connections dialog box and thus requires a working installation of the operating system. Once the Network Load Balancing driver is bound to a NIC, you can perform all other configuration steps remotely, but you will need to use two additional providers:

  • Use the Domain Name System (DNS) provider to register the cluster name and IP address with DNS.
  • Use the Win32 provider to register the cluster name and IP address with TCP/IP.

For information on these providers, see the Platform SDK documentation for WMI.

For checklists and procedures describing how to install Network Load Balancing, see the Windows online Help documentation.


Configuring User Interface Settings

The following sections describe each of the settings displayed on the Network Load Balancing Properties dialog box and the Provider classes or methods used to access the same settings:

  • Configuring Cluster Parameters
  • Configuring Host Parameters
  • Configuring Port Rules

Note If the Network Load Balancing provider and the Network Load Balancing user interface are used concurrently in the same cluster to make configuration changes, the results are unpredictable. For example, if the remote password is modified through the user interface, the provider may return a WLBS_BAD_PASSW error when attempting to get or enumerate instances of MicrosoftNLB_Node or MicrosoftNLB_Cluster. Using the LoadAllSettings method of the MicrosoftNLB_ClusterSetting class or the LoadAllSettings method of the MicrosoftNLB_NodeSetting class will update the provider and remove the error. For the best results, avoid concurrent use of the provider and the user interface.


Configuring Cluster Parameters

The settings shown on the "Cluster Parameters" tab of the Network Load Balancing Properties dialog are accessed through the MicrosoftNLB_ClusterSetting class, using the properties and methods shown in the following table.

Dialog setting | Property or method
Cluster name (full internet name) | ClusterName
Primary IP address | ClusterIPAddress
Subnet mask | ClusterNetworkMask
Network address | ClusterMACAddress
Multicast support enabled checkbox | MulticastSupportEnabled
Remote control password | SetPassword
Remote control enabled checkbox | RemoteControlEnabled


Configuring Host Parameters

The settings shown on the "Host Parameters" tab of the Network Load Balancing Properties dialog are accessed through the MicrosoftNLB_NodeSetting class, by using the properties and methods shown in the following table.

Setting | Property or method
Priority | HostPriority
Initial state active | ClusterModeOnStart
Dedicated IP Address | DedicatedIPAddress
Subnet mask | DedicatedNetworkMask


Configuring Port Rules

On the "Port Rules" tab of the Network Load Balancing Properties dialog, the filtering mode of a port rule is a configurable property. The Network Load Balancing Provider does not define a corresponding property. Instead, each filtering mode is represented by a specific class derived from MicrosoftNLB_PortRule. To access the settings of a port rule, you must create an instance of the class that represents the filtering mode of the port rule, as shown in the following table.

Filtering mode | Class to use
Multiple-host filtering mode | MicrosoftNLB_PortRuleLoadBalanced
Single-host filtering mode | MicrosoftNLB_PortRuleFailover
Disabled | MicrosoftNLB_PortRuleDisabled

The remaining settings shown on the "Port Rules" tab of the Network Load Balancing Properties dialog are accessed using the classes and methods shown in the following table.

Setting | Class | Property or method
Port range | All MicrosoftNLB_PortRule classes | StartPort and EndPort
Protocols | All MicrosoftNLB_PortRule classes | Protocol
Affinity | MicrosoftNLB_PortRuleLoadBalanced | Affinity
Load weight | MicrosoftNLB_PortRuleLoadBalanced | LoadWeight
Equal load checkbox | MicrosoftNLB_PortRuleLoadBalanced | EqualLoad
Handling priority | MicrosoftNLB_PortRuleFailover | Priority


Using the Network Load Balancing Provider

The Network Load Balancing Provider defines WMI classes that allow your application to control Network Load Balancing clusters, nodes, and port rules.

For information on how to use the Network Load Balancing provider, see the following sections:

  • Making Direct Connections
  • Obtaining Class Instances

For example code demonstrating how to use the provider, see the scripting example.

For general information about how to use providers, please refer to the Platform SDK documentation on Windows Management Instrumentation (WMI).


Making Direct Connections

The following procedure describes how to use the Scripting API for WMI to establish a direct connection:

  1. Obtain an SWbemLocator object.
  2. Obtain an SWbemServices object using SWbemLocator.ConnectServer, specifying the target host's dedicated IP address as the Computername parameter.
  3. Use the methods of SWbemServices to obtain instances of Network Load Balancing provider classes. For more information see Obtaining Class Instances.

The following code snippet demonstrates this procedure. For a more detailed code example, see NLBScriptLib.vbs.

Set oLoc = CreateObject("WbemScripting.SWbemLocator")
strDIP = "172.16.102.43"
strNamespace = "root\MicrosoftNLB"
strUser = "Administrator"
strPassword = ""
Set oSvc = oLoc.ConnectServer(strDIP, _
                              strNamespace, _
                              strUser, _
                              strPassword)
oLoc.Security_.ImpersonationLevel = 3


Obtaining Class Instances

If you establish a direct connection with a cluster node (see Making Direct Connections), you can obtain instances of Network Load Balancing provider classes as follows:

  • Use the SWbemServices.InstancesOf method to get a collection of MicrosoftNLB_Node objects. The collection will always return the node you are connected to first, or you can use the MicrosoftNLB_Node object's Name property to identify a particular node. Note that the nodes you will be able to enumerate depend on several factors. For more information see Enumerating Objects.
  • Use the SWbemServices.InstancesOf method to get a collection of MicrosoftNLB_NodeSetting objects. The collection will always return the MicrosoftNLB_NodeSetting corresponding to the node you are connected to first, or you can use the MicrosoftNLB_NodeSetting object's Name property to identify a particular node setting. Note that the node settings you will be able to enumerate depend on several factors. For more information see Enumerating Objects.
  • Use the MicrosoftNLB_NodeSetting.GetPortRule method to get instances of MicrosoftNLB_PortRule objects.

The following code snippet demonstrates how to obtain instances of Network Load Balancing provider classes. For a more detailed code example, see NLBScriptLib.vbs.

'Set configuration data.
strClusterIP = "172.50.66.14"
strHostID = "1"
strDIP = "172.50.35.12"
strKey = strClusterIP & ":" & strHostID
strNamespace = "root\MicrosoftNLB"
strUser = "Administrator"
strPassword = ""
strPortNumber = "65535"

'Make a direct connection.
Set oLoc = CreateObject("WbemScripting.SWbemLocator")
Set oSvc = oLoc.ConnectServer(strDIP, _
                              strNamespace, _
                              strUser, _
                              strPassword)
oLoc.Security_.ImpersonationLevel = 3

'Get a node instance.
Set oNodes = oSvc.InstancesOf ("MicrosoftNLB_Node")
For Each oNode in oNodes
    ' The first one is the one we want
    Exit For
Next

'Get a node setting instance.
Set oNodeSettings = oSvc.InstancesOf ("MicrosoftNLB_NodeSetting")
For Each oNodeSetting in oNodeSettings
    ' The first one is the one we want
    Exit For
Next

'Get a port rule instance.
oNodeSetting.GetPortRule CLng(strPortNumber), oPortRule

WScript.Echo oPortRule.Name

Set oPortRule = Nothing
Set oNodeSetting = Nothing
Set oNodeSettings = Nothing
Set oNode = Nothing
Set oNodes = Nothing
Set oSvc = Nothing
Set oLoc = Nothing


Scripting Example

The following scripting example uses XML, Windows Script Host, and Microsoft® Visual Basic® Scripting Edition (VBScript) to create an extensible command-line interface for Network Load Balancing. The code is presented in three sections:

Section | Description
Nlb.xml | Contains configuration data in an XML document.
NlbScriptLib.vbs | Contains common functions and constants (VBScript) used by all of the jobs in Nlb.wsf.
Nlb.wsf | A Windows Script Host (WSH) script that defines a number of jobs that can be called from the command line.


Nlb.xml

Nlb.xml is an XML document containing configuration information. NlbScriptLib.vbs parses this document to plug in values for the cluster IP address, the dedicated IP address, etc. To extend the document to include more setting and configuration information, simply add more tags.

Note that Nlb.xml is a basic XML document. To store configuration information for an entire cluster, a DTD or an XML schema would enforce a uniform object model.

<?xml version="1.0"?>
<!-- NLB Cluster Configuration Data (single node only) -->
<!-- TODO:  Change these values to reflect your cluster! -->
<nodeinfo>
  <clusterIP>172.50.66.14</clusterIP>
  <dedicatedIP>172.50.35.12</dedicatedIP>
  <hostID>1</hostID>
  <portnumber>65535</portnumber>
</nodeinfo>


NlbScriptLib.vbs

NLBScriptLib.vbs serves as a common library of functions for the jobs in Nlb.wsf. It is mainly used to provide a standard mechanism for connecting to the Network Load Balancing provider.

'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' NlbScriptLib.vbs
'
' Contains functions and constants used by Nlb.wsf
'
'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

Public Const DEBUG_MODE = False

' The NLB provider namespace
Public Const NLB_NAMESPACE = "root\MicrosoftNLB"

' Global objects
Public g_objLocator     'SWbemLocator object
Public g_objService     'SWbemService object
Public g_objArgs        'Arguments object
Public g_objNode        'MicrosoftNLB_Node object

'Global strings
Public g_strCIP         'Cluster IP
Public g_strDIP         'Dedicated IP
Public g_strHostID      'Host priority
Public g_strPort        'Port number
Public g_strNameKey     'Used to specify the Name property

Public Function ConnectNLB()
'
' Sets all global objects and establishes a connection to a
' Network Load Balancing host via its dedicated IP address (DIP).
'
' Every job in NLB.WSF calls ConnectNLB.
'
' ConnectNLB expects the following command-line arguments:
' 1) The user ID of the caller.
' 2) The password of the caller.
'
    Dim strUsername, strPassword
    Dim xmlDoc, ElementList, objNode, objNodes

    'Parse the XML document
    Set XMLDoc = CreateObject("Microsoft.xmlDOM")
    xmlDoc.Async = False
    xmlDoc.Load("nodeinfo.xml")
    Set ElementList = xmlDoc.getElementsByTagName("clusterIP")
    g_strCIP = ElementList.item(0).text
    Set ElementList = xmlDoc.getElementsByTagName("dedicatedIP")
    g_strDIP = ElementList.item(0).text
    Set ElementList = xmlDoc.getElementsByTagName("hostID")
    g_strHostID = ElementList.item(0).text
    Set ElementList = xmlDoc.getElementsByTagName("portnumber")
    g_strPort = ElementList.item(0).text
    Set ElementList = Nothing
    Set XMLDoc = Nothing

    'Parse command-line arguments
    Set g_objArgs = WScript.Arguments
    If g_objArgs.Count < 2 Then
        ShowSyntax
        WScript.Quit
    End If

    'Connect to NLB
    Set g_objLocator = CreateObject("WbemScripting.SWbemLocator")
    Set g_objService = g_objLocator.ConnectServer(strDIP, _
                                                  NLB_Namespace, _
                                                  strUserName, _
                                                  strPassword)
    g_objLocator.Security_.ImpersonationLevel = 3

    'Get a MicrosoftNLB_Node object
    Set objNodes = g_objService.InstancesOf ("MicrosoftNLB_Node")
    For Each objNode in objNodes
        Exit For
    Next
    Set g_objNode = objNode
    g_strNameKey = g_strCIP & ":" & g_strHostID

End Function

Public Function QuitWithMessage(strMessage)
    WScript.Echo strMessage
    DisconnectNLB
    WScript.Quit
End Function

Public Function EnumProperties(obj)
    Dim oProps, oProp
    Set oProps = obj.Properties_
    On Error Resume Next
    For Each oProp in oProps
        WScript.Echo oProp.Name & " : " & CStr(oProp.Value)
        If Err.Number = 94 Then
        'Error 94 = Invalid Use of Null
            Err.Clear
            WScript.Echo oProp.Name & " : (null)"
        End If
    Next
    Set oProp = Nothing
    Set oProps = Nothing
End Function

Public Function DisconnectNLB
    Set g_objNodes = Nothing
    Set g_objArgs = Nothing
    Set g_objService = Nothing
    Set g_objLocator = Nothing
End Function

Public Function ShowSyntax()
    WScript.Echo vbCrLf
    WScript.Echo String(70,"=")
    WScript.Echo "NLB.WSF SYNTAX GUIDE:" & vbCrLf
    WScript.Echo "Run NLB.WSF on the command line using the following basic syntax:"
    WScript.Echo "    cscript //Job:<JobID> nlb.wsf <arglist>" & vbCrLf
    WScript.Echo "For <JobID>, specify the name of the job you want to run."
    WScript.Echo "Job names are defined in NLB.WSF." & vbCrLf
    WScript.Echo "For <arglist>, specify:"
    WScript.Echo "    1. Your network username."
    WScript.Echo "    2. Your network password."
    WScript.Echo "Example: Running the Test job"
    WScript.Echo "    cscript //Job:" & Chr(34) & "Test" & Chr(34) & " " & "nlb.wsf " & Chr(34) & "Administrator" & Chr(34) & " " & Chr(34) & Chr(34) & vbCrLf
    WScript.Echo String(70,"=")
End Function


Nlb.wsf

Nlb.wsf is an XML-compliant Windows Script Host (WSH) script that can perform a number of different jobs. Configuration data is supplied by Nlb.xml, and NlbScriptLib.vbs provides a common library of functions. The script is designed to run on the command line and requires two command-line arguments in addition to a job identifier. The command syntax is:

    cscript //job:<job id> nlb.wsf <arglist>

For <job id> use the name of the job you want to run.

For <arglist>, specify the following command-line arguments:

  1. Your network username.
  2. Your network password.

For more information about WSH command-line syntax, see the Platform SDK documentation on Windows Script Host.

<?xml version="1.0"?>
<!------------------------------------------------------------------
Nlb.wsf

Example script used to demostrate the NLB provider. Must be used in
conjunction with NlbScriptLib.vbs and NodeInfo.xml. To extend the
functionality of this script simply add more jobs.
------------------------------------------------------------------->
<package>
  <job id="Test">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        WScript.Echo g_objNode.Name
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Disable">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Disable(CLng(g_strPort))
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Drain">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Drain(CLng(g_strPort))
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="DrainStop">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.DrainStop
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Enable">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Enable(CLng(g_strPort))
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Resume">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Resume
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Start">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Start
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Stop">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Stop
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="Suspend">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        ConnectNLB
        g_objNode.Suspend
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="ShowNodeSettings">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        Dim objNodeSettings, objNodeSetting
        ConnectNLB
        Set objNodeSettings = g_objService.InstancesOf ("MicrosoftNLB_NodeSetting")
        For Each objNodeSetting in objNodeSettings
            EnumProperties objNodeSetting
        Next
        Set objNodeSetting = Nothing
        Set objNodeSettings = Nothing
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="SetDefaults">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        Dim objNodeSettings, objNodeSetting, objPortRules, objPortRule
        ConnectNLB
        Set objNodeSettings = g_objService.InstancesOf ("MicrosoftNLB_NodeSetting")
        On Error Resume Next
        For Each objNodeSetting in objNodeSettings
            Exit For
        Next
        objNodeSetting.SetDefaults
        objNodeSetting.LoadAllSettings
        Set objNodeSetting = Nothing
        Set objNodeSettings = Nothing
        DisconnectNLB
      ]]>
    </script>
  </job>
  <job id="ShowPortRule">
    <script language="VBScript" src="NLBScriptLib.vbs" />
    <script language="VBScript">
      <![CDATA[
        Dim objNodeSettings, objNodeSetting, objPortRule
        ConnectNLB
        Set objNodeSettings = g_objService.InstancesOf ("MicrosoftNLB_NodeSetting")
        For Each objNodeSetting in objNodeSettings
            Exit For
        Next
        objNodeSetting.GetPortRule CLng(g_strPort), objPortRule
        EnumProperties objPortRule
        Set objPortRule = Nothing
        Set objNodeSetting = Nothing
        Set objNodeSettings = Nothing
        DisconnectNLB
      ]]>
    </script>
  </job>
</package>


Network Load Balancing Provider Reference

The Network Load Balancing Provider is defined in wlbsprov.mof. By convention, this documentation describes only the classes, methods, and associations specific to Network Load Balancing. Top-level WMI classes (those with the CIM_ prefix) that are defined in the MOF file are not specific to Network Load Balancing and are described in the Platform SDK documentation for Windows Management Instrumentation (WMI).

Section | Contents
Network Load Balancing WMI Classes | WMI classes for Network Load Balancing, along with their methods and properties
Standard Return Values | Describes Network Load Balancing–specific return values associated with certain class methods and thrown errors.


Network Load Balancing WMI Classes

Network Load Balancing has the following WMI classes.

WIM class | Description
MicrosoftNLB_Cluster | Represents an instance of a Network Load Balancing cluster.
MicrosoftNLB_ClusterClusterSetting | Associates an instance of the MicrosoftNLB_Cluster class to an instance of the MicrosoftNLB_ClusterSetting class.
MicrosoftNLB_ClusterSetting | Represents data that identifies the Network Load Balancing cluster.
MicrosoftNLB_ExtendedStatus | The provider uses this class to report error codes specific to Network Load Balancing.
MicrosoftNLB_Node | Represents an instance of a node within a Network Load Balancing cluster.
MicrosoftNLB_NodeNodeSetting | Associates an instance of the MicrosoftNLB_Node class to an instance of the MicrosoftNLB_NodeSetting class.
MicrosoftNLB_NodeSetting | Represents the configuration data specific to a node.
MicrosoftNLB_NodeSettingPortRule | Associates an instance of the MicrosoftNLB_NodeSetting class to instances of classes derived from MicrosoftNLB_PortRule.
MicrosoftNLB_ParticipatingNode | Associates an instance of the MicrosoftNLB_Cluster class with participating MicrosoftNLB_Node class instances.
MicrosoftNLB_PortRule | An abstract base class from which classes that represent port rules are derived.
MicrosoftNLB_PortRuleDisabled | Represents a disabled port rule.
MicrosoftNLB_PortRuleFailover | Represents a Network Load Balancing port rule set to single-host filtering mode.
MicrosoftNLB_PortRuleLoadbalanced | Represents a Network Load Balancing port rule set to multiple-host filtering mode.


MicrosoftNLB_Cluster

The MicrosoftNLB_Cluster WMI class represents an instance of a Network Load Balancing cluster. Only nodes that have remote control enabled contribute to the ClusterState property as reported in this class and respond to the methods invoked from this class.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_Cluster : CIM_Cluster
{
string Caption
uint16 ClusterState
string CreationClassName
string Description
datetime InstallDate
string Interconnect
string InterconnectAddress
uint32 MaxNumberOfNodes
string Name
string NameFormat
string PrimaryOwnerContact
string PrimaryOwnerName
string Roles
string Status
uint16 Types
};

Properties

The MicrosoftNLB_Cluster class has the following properties:

Caption
Not used. Inherited from CIM_Cluster.
ClusterState
A uint16 that summarizes the states of all cluster nodes that have remote control enabled. Nodes that do not have remote control enabled do not report their status.

The value indicates the states of the reporting nodes as follows.
Value | Meaning
1-32 | Indicates the number of converged nodes in the cluster that have RemoteControlEnabled set to True.
1005 | WLBS_STOPPED
1006 | WLBS_CONVERGING
1009 | WLBS_DRAINING
1013 | WLBS_SUSPENDED

For a description of the values 1005 through 1013, see the Standard Return Values.

Inherited from CIM_Cluster.

CreationClassName
Qualifiers: CIM_Key, MaxLen (256)

String that indicates the name of the class or subclass used in the creation of a MicrosoftNLB_Cluster instance. When used with the other key properties of this class, this property allows all instances of this class and its subclasses to be uniquely identified.

Inherited from CIM_Cluster.

Description
Not used. Inherited from CIM_Cluster.
InstallDate
Not used. Inherited from CIM_Cluster.
Interconnect
Not used. Inherited from CIM_Cluster.
InterconnectAddress
Qualifiers: Override("InterconnectAddress"), Read

String that displays the IP address of the cluster.

Inherited from CIM_Cluster.

MaxNumberOfNodes
A uint16 that indicates the maximum number of nodes that can participate in the cluster. For Network Load Balancing this should be 32.

Inherited from CIM_Cluster.

Name
Qualifiers: Override("Name"), Read, MaxLen (256)

String that is always set to the cluster IP address..

Inherited from CIM_Cluster.

NameFormat
Not used. Inherited from CIM_Cluster.
PrimaryOwnerContact
Not used. Inherited from CIM_Cluster.
PrimaryOwnerName
Qualifiers: MaxLen (64), MappingStrings {"MIF.DMTF|General Information|001.4" }

String that represents the name of the primary system owner.

Inherited from CIM_Cluster.

Roles
Not used. Inherited from CIM_Cluster.
Status
Do not use this property. The Network Load Balancing provider uses the ClusterState property to indicate the status of the cluster.

Inherited from CIM_Cluster.

Types
Not used. Inherited from CIM_Cluster.

Methods

The MicrosoftNLB_Cluster class has the following methods. Note that these methods affect only nodes for which the MicrosoftNLB_ClusterSetting RemoteControlEnabled property has been set to TRUE.

Method | Description
Disable | Qualifiers: Implemented Disables a range of ports on all nodes that have remote control enabled.
Drain | Qualifiers: Implemented Drains a range of ports on all nodes that have remote control enabled.
DrainStop | Qualifiers: Implemented Drains all ports on all nodes that have remote control enabled, then stops cluster operation on all nodes.
Enable | Qualifiers: Implemented On all nodes that have remote control enabled, enables ports that have been disabled.
Resume | Qualifiers: Implemented Resumes all suspended nodes that have remote control enabled.
Start | Qualifiers: Implemented Starts cluster operations on all nodes.
Stop | Qualifiers: Implemented Stops cluster operations on all nodes that have remote control enabled.
Suspend | Qualifiers: Implemented Suspends cluster operation on all nodes that have remote control enabled.

Remarks

The MicrosoftNLB_Cluster class cannot be enumerated if no nodes in the cluster have remote control enabled.

The MicrosoftNLB_Cluster class is derived from the CIM_Cluster class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_Cluster : CIM_Cluster
{
  [ Read, Override ("Name"), MaxLen (256) ]
  string Name;

  [ Override("InterconnectAddress"), Read ]
  string InterconnectAddress;

  [ Override ("ClusterState"), Read,
    Values   { "WLBS_SUSPENDED", "WLBS_STOPPED", "WLBS_DRAINING",
               "WLBS_CONVERGING"}: ToInstance,
    ValueMap { "1013", "1005", "1009", "1006"}: ToInstance ]
  uint16 ClusterState;
};


Disable Method of the MicrosoftNLB_Cluster Class

The Disable method terminates existing connections and prevents new connections to a range of ports on all nodes that have remote control enabled.

[MOF]
uint32 Disable(
  uint32 Port,
  uint32 NumNodes
);

Parameters

Port
[in] To affect a range of ports, set Port to a port number ( 0 to 65,535 ). All ports in the port rule containing the specified port number will be affected. To affect all ports, set Port to 0xFFFFFFFF.
NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

To block new connections while allowing existing connections to terminate normally, use the Drain method.

To re-enable disabled ports, use the Enable method.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


Drain Method of the MicrosoftNLB_Cluster Class

The Drain method causes one or more port rules to start draining on all nodes that have remote control enabled.

[MOF]
uint32 Drain(
  uint32 Port,
  uint32 NumNodes
);

Parameters

Port
[in] To affect a range of ports, set Port to a port number ( 0 to 65,535 ). All ports in the port rule containing the specified port number will be affected. To affect all ports, set Port to 0xFFFFFFFF.
NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


DrainStop Method of the MicrosoftNLB_Cluster Class

The DrainStop method drains all ports and stops cluster operations on all nodes that have remote control enabled.

[MOF]
uint32 DrainStop(
  uint32 NumNodes
);

Parameters

NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


Enable Method of the MicrosoftNLB_Cluster Class

The Enable method enables ports that have been disabled on all nodes that have remote control enabled.

[MOF]
uint32 Enable(
  uint32 Port,
  uint32 NumNodes
);

Parameters

Port
[in] To affect a range of ports, set Port to a port number ( 0 to 65,535 ). All ports in the port rule containing the specified port number will be affected. To affect all ports, set Port to 0xFFFFFFFF.
NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


Resume Method of the MicrosoftNLB_Cluster Class

The Resume method resumes cluster operations on all nodes that have remote control is enabled.

[MOF]
uint32 Resume(
  uint32 NumNodes
);

Parameters

NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


Start Method of the MicrosoftNLB_Cluster Class

The Start method starts cluster operations on all nodes that have remote control enabled

[MOF]
uint32 Start(
  uint32 NumNodes
);

Parameters

NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


Stop Method of the MicrosoftNLB_Cluster Class

The Stop method stops cluster operations on all nodes that have remote control enabled.

[MOF]
uint32 Stop(
  uint32 NumNodes
);

Parameters

NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


Suspend Method of the MicrosoftNLB_Cluster Class

The Suspend method suspends cluster operations on all nodes that have remote control enabled.

[MOF]
uint32 Suspend(
  uint32 NumNodes
);

Parameters

NumNodes
[out] Returns the number of nodes affected by the operation.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

To enable remote control for a node, set the MicrosoftNLB_ClusterSetting RemoteControlEnabled property to TRUE.

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


MicrosoftNLB_ClusterClusterSetting

The MicrosoftNLB_ClusterClusterSetting CIM association class associates an instance of the MicrosoftNLB_Cluster class to an instance of the MicrosoftNLB_ClusterSetting class.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_ClusterClusterSetting : CIM_ElementSetting
{
MicrosoftNLB_Cluster REF Element
MicrosoftNLB_ClusterSetting REF Setting
};

Properties

The MicrosoftNLB_ClusterClusterSetting class has the following properties:

Element
Qualifiers: Key, Override("Element"), Min (1)

Reference to a MicrosoftNLB_Cluster instance that represents a cluster.

Inherited from CIM_ElementSetting.

Setting
Qualifiers: Key, Override("Setting")

Reference to a MicrosoftNLB_ClusterSetting instance that represents the cluster settings for a node.

Inherited from CIM_ElementSetting.

Remarks

The MicrosoftNLB_ClusterClusterSetting class is derived from the CIM_ElementSetting class.

MOF Code

[ Association, Dynamic: ToInstance,
  Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_ClusterClusterSetting : CIM_ElementSetting
{
  [ Key, Override("Element"), Min (1) ]
  MicrosoftNLB_Cluster REF Element;

  [ Key, Override("Setting") ]
   MicrosoftNLB_ClusterSetting REF Setting;
};

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_ClusterSetting


MicrosoftNLB_ClusterSetting

The MicrosoftNLB_ClusterSetting WMI class represents data that identifies the Network Load Balancing cluster to which a node belongs.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_ClusterSetting : CIM_Setting
{
string AdapterGuid
string Caption
string ClusterIPAddress
Boolean ClusterIPToMulticastIP
string ClusterMACAddress
string ClusterName
string ClusterNetworkMask
string Description
uint32 IGMPJoinInterval
Boolean IGMPSupport
string MulticastIPAddress
Boolean MulticastSupportEnabled
string Name
Boolean RemoteControlEnabled
string SettingID
};

Properties

The MicrosoftNLB_ClusterSetting class has the following properties:

AdapterGuid
A string that specifies the GUID of the adapter to which Network Load Balancing is bound.
Caption
Not used. Inherited from CIM_Setting.
ClusterIPAddress
String that specifies the cluster's primary IP address in standard dotted decimal notation (xxx.xxx.xxx.xxx).
ClusterIPToMulticastIP
Boolean. If set to TRUE, Network Load Balancing automatically generates the multicast IP address from the cluster IP address. If FALSE, the multicast IP address must be specified in the MulticastIPAddress property. Defaults to TRUE.
ClusterMACAddress
Qualifiers: Read

String that specifies the MAC address of the cluster.

ClusterName
String that specifies a full Internet name for the Network Load Balancing cluster (for example, cluster.domain.com). This name is used for the cluster as a whole and should be the same for all nodes in the cluster.
ClusterNetworkMask
String that specifies the subnet mask.
Description
Not used.
IGMPJoinInterval
uint32. Specifies the interval in seconds between IGMP join messages sent by Network Load Balancing to switches on the network. IGMP join messages instruct the switches to forward multicast frames to specific ports. However, the switches periodically discard this information according to a configurable time-out interval. Be sure to set the IGMPJoinInterval property to a value less than the switch time-out interval. By default, IGMPJoinInterval is set to 60 seconds (1 minute) and the default switch time-out value is 5 minutes.
IGMPSupport
Boolean. The IGMPSupport property determines how multicast traffic is handled as follows.
Value | Description
FALSE | Default. Network Load Balancing does not send IGMP join messages. Switches send all traffic (including multicast packets) to all switch ports.
TRUE | Network Load Balancing sends IGMP join messages to switches at intervals specified by the IGMPJoinInterval property. IGMP join messages cause the switches to send multicast traffic to specific ports rather than to all ports.

MulticastIPAddress
String that specifies the cluster's multicast IP address if ClusterIPToMulticastIP is FALSE. A multicast IP group address should not interfere with other traffic or hinder any multicast applications that may be running on nodes that are part of the subnet on which the Network Load Balancing cluster resides.
MulticastSupportEnabled
Boolean that specifies whether or not a multicast MAC address should be used for cluster operations. If this option is enabled, Network Load Balancing converts the cluster MAC address belonging to the cluster adapter into a multicast address. It also ensures that the cluster's primary IP address resolves to this multicast address as part of the ARP protocol. At the same time, the adapter can now use its original, built-in MAC address, which, in unicast mode, was disabled.
Name
Qualifiers: Key, Read

String that specifies the name of the node to which these settings apply. This is the name stored in the MicrosoftNLB_Node Name property.

RemoteControlEnabled
Boolean that determines whether this node will be listed in enumerations and whether the node will respond to the methods of the MicrosoftNLB_Cluster and MicrosoftNLB_Node classes. The default is FALSE.

If set to FALSE:

The node will not be listed in enumerations of cluster nodes.

The node will not respond to or be affected by MicrosoftNLB_Cluster methods.

To access a node's settings or to perform actions like enabling or disabling a port rule, you must connect to each node individually using WMI. For an example, see Making Direct Connections.

This setting is the default on Windows 2000 for security reasons.

If set to TRUE:

The node will be listed in enumerations.

The node will be affected by MicrosoftNLB_Cluster methods.

For the security implications of this setting, please see the Windows 2000 Help documentation.

SettingID
Not used. Inherited from CIM_Setting.

Methods

The MicrosoftNLB_ClusterSetting class has the following methods.

Method | Description
LoadAllSettings | Qualifier: Implemented Propagates all current settings (cluster, node, and port rule) to the Network Load Balancing driver.
SetPassword | Qualifier: Implemented Sets the remote control password for the cluster. For more information on the remote control password, see the online help documentation for Network Load Balancing.
SetDefaults | Qualifier: Implemented If there is only one adapter bound to Network Load Balancing on this node, the SetDefault method resets all of the properties of the MicrosoftNLB_ClusterSetting class to their default values. If there are multiple adapters bound to Network Load Balancing on this node, the SetDefault property returns WMI_E_NOT_SUPPORTED.

\

Remarks

Regardless of the remote control settings on other nodes, enumerating the MicrosoftNLB_ClusterSetting class always returns one instance only. This instance represents the cluster settings for the provider node.

After changing any MicrosoftNLB_ClusterSetting properties, you must call LoadAllSettings to bring the new values into effect. For more information, see LoadAllSettings.

The MicrosoftNLB_ClusterSetting class is derived from the CIM_Setting class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409)]
class MicrosoftNLB_ClusterSetting : CIM_Setting
{
  [ Key, Read ]
  string Name;

  string ClusterName;

  [ ModelCorrespondence {"CIM_Cluster.InterconnectAddress"} ]
  string ClusterIPAddress;

  string ClusterNetworkMask;

  [ Read ]
  string ClusterMACAddress;

  Boolean MulticastSupportEnabled;

  Boolean RemoteControlEnabled;
};

See Also

MicrosoftNLB_NodeSetting


LoadAllSettings Method of the MicrosoftNLB_ClusterSetting Class

The LoadAllSettings method forces the Network Load Balancing driver to reload, which allows it to update its private copy of the cluster configuration data.

[MOF]
uint32 LoadAllSettings();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

Because the Network Load Balancing driver runs "beneath" the operating system, its only opportunity to read and save cluster configuration data is during its initialization. The LoadAllSettings method forces the driver to reload, which updates its private data store and "commits" the changes to the cluster.

Note that in Windows NT 4.0, the reload functionality is not supported, and the method will return a reboot request. In other words, you must reboot Windows NT 4.0 nodes in order to commit any configuration change.

See Also

MicrosoftNLB_ClusterSetting


SetPassword Method of the MicrosoftNLB_ClusterSetting Class

The SetPassword method changes the remote control password for the cluster.

[MOF]
void SetPassword(
  string Password
);

Parameters

Password
[in] Specifies the remote control password.

Return Values

This method has no return values.

Remarks

Use caution when changing the remote control password and be sure to commit the change by using the LoadAllSettings method.

See Also

LoadAllSettings Method of the MicrosoftNLB_ClusterSetting Class, MicrosoftNLB_ClusterSetting


SetDefaults Method of the MicrosoftNLB_ClusterSetting Class

The SetDefaults method resets all of the properties of the MicrosoftNLB_ClusterSetting class to their default values.

[MOF]
void SetDefaults();

Parameters

This method has no parameters.

Return Values

This method has no return values.

Remarks

Use the LoadAllSettings method to commit the setting changes to the cluster.

See Also

MicrosoftNLB_ClusterSetting


MicrosoftNLB_ExtendedStatus

The MicrosoftNLB_ExtendedStatus WMI class is used by the Network Load Balancing provider to report error codes specific to Network Load Balancing.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_ExtendedStatus : __ExtendedStatus
{
string Description
string Operation
string ParameterInfo
string ProviderName
uint32 StatusCode
};

Properties

The MicrosoftNLB_Cluster class has the following properties.

Description
Any user-defined string that describes an error or operational status.

Inherited from __ExtendedStatus.

Operation
String that describes the operation that was taking place at the time of the failure or anomaly.

Inherited from __ExtendedStatus.

ParameterInfo
String that identifies one or more parameters that was involved in the error or status change. For example, if an application attempted to retrieve a class that does not exist, ParameterInfo would be set to the offending class name.

Inherited from __ExtendedStatus.

ProviderName
String that identifies the provider that caused or reported the error or status change. If a provider was not involved, this string is set to "Windows Management".

Inherited from __ExtendedStatus.

StatusCode
Qualifiers: Override("StatusCode")

A uint32 that contains Network Load Balancing and Winsock error codes. The following values map constants defined for Network Load Balancing but do not include Winsock error codes:
Value | Constant
1101 | WLBS_BAD_PASSW
1102 | WLBS_IO_ERROR
1003 | WLBS_BAD_PARAMS
1004 | WLBS_NOT_FOUND
1103 | WLBS_TIMEOUT
1150 | WLBS_PORT_OVERLAP
1151 | WLBS_BAD_PORT_PARAMS
1152 | WLBS_MAX_PORT_RULES
1154 | WLBS_REG_ERROR

For a description of the values 1101 through 1154, see the Standard Return Values.

Remarks

The MicrosoftNLB_ExtendedStatus class is derived from the __ExtendedStatus class WMI system class.

MOF Code

[ Dynamic : ToInstance, Provider("Microsoft|NLB_Provider|V1.0"),
  LOCALE(0x409) ]
class MicrosoftNLB_ExtendedStatus : __ExtendedStatus
{
  [ Override("StatusCode"),
    Values { "WLBS_BAD_PARAMS", "WLBS_NOT_FOUND", "WLBS_BAD_PASSW",
             "WLBS_IO_ERROR", "WLBS_TIMEOUT", "WLBS_PORT_OVERLAP",
             "WLBS_BAD_PORT_PARAMS", "WLBS_MAX_PORT_RULES",
             "WLBS_REG_ERROR" }: ToInstance,
    ValueMap { "1003", "1004", "1101", "1102", "1103", "1150", "1151",
               "1152", "1154" }: ToInstance ]
  uint32 StatusCode;
};


MicrosoftNLB_Node

The MicrosoftNLB_Node WMI class represents an instance of a node within a Network Load Balancing cluster.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_Node : CIM_UnitaryComputerSystem
{
string Caption
string CreationClassName
string DedicatedIPAddress
string Description
uint32 HostPriority
string InitialLoadInfo
datetime InstallDate
string LastLoadInfo
string Name
string NameFormat
uint16 PowerManagementCapabilities
Boolean PowerManagementSupported
uint16 PowerState
string PrimaryOwnerContact
string PrimaryOwnerName
uint16 ResetCapability
string Roles
string Status
uint32 StatusCode
};

Properties

The MicrosoftNLB_Node class has the following properties:

Caption
Qualifiers: MaxLen (64)

String that provides a short one-line description of the node.

Inherited from CIM_UnitaryComputerSystem.

CreationClassName
Qualifiers: CIM_Key, MaxLen (256)

String that indicates the name of the class or subclass used in the creation of a MicrosoftNLB_Node instance. When used with the other key properties of this class, this property allows all instances of this class and its subclasses to be uniquely identified.

Inherited from CIM_UnitaryComputerSystem.

DedicatedIPAddress
Qualifiers: Read

String that specifies this node's unique IP address used for network traffic not associated with the cluster (for example, Telnet access to a specific node within the cluster).

Description
String that provides a description of the node.

Inherited from CIM_UnitaryComputerSystem.

HostPriority
Qualifiers: Read

A uint32 that specifies the host priority of the node. Each node within the cluster must specify a unique host priority, ranging from 1 (indicates the highest priority) to n (lowest priority), where n is the number of nodes in the cluster. The node with the highest priority receives all network traffic not handled by port rules.

InitialLoadInfo
String that specifies either the key of the initial load device or name of the service to start when the node boots. Load parameters may also be specified. For example: "%system%\svcname.exe -f -b -t"
InstallDate
Qualifiers: MappingStrings {"MIF.DMTF|ComponentID|001.5"}

A datetime that indicates when the node was installed. The lack of a value does not indicate that the node is not installed.

Inherited from CIM_UnitaryComputerSystem.

LastLoadInfo
Qualifiers: MappingStrings {"MIB.IETF|HOST-RESOURCES-MIB.hrSystemInitialLoadDevice", MIB.IETF|HOST-RESOURCES-MIB.hrSystemInitialLoadParameters"}

String that stores the value of the InitialLoadInfo property that was used for the most recent boot of the node.

Inherited from CIM_UnitaryComputerSystem.

Name
Qualifiers: Read, Override("Name")

String that identifies the node by a combination of the cluster IP address and the node's host priority. The name is formatted as (cluster IP address)(colon)(host priority). For example: "172.150.35.12:1".

Note When configuring new clusters, all of the cluster IP addresses may initially be set to zero (0.0.0.0). In this case the name format changes to "0.0.0.x:id" where x is a unique index and id is the host priority of the node.

Inherited from CIM_UnitaryComputerSystem.

NameFormat
String that specifies the process by which the Name property is generated. For a description of the possible values, see the WMI SDK documentation.

Inherited from CIM_UnitaryComputerSystem.

PowerManagementCapabilities
A uint16 that indicates the specific power management capabilities of the node as an array of any of the following values that apply.
Value | Setting | Comment
0 | Unknown | The power management capabilities of the node cannot be determined.
1 | Not Supported | If the PowerManagementSupported property is FALSE, this should be the only value in the array.
2 | Disabled. | The power management capabilities of the node are turned off.
3 | Enabled | The power management features are currently enabled, but the exact feature set is unknown, or the information is unavailable.
4 | Power Saving Modes Entered Automatically | The node can change its power state based on usage or other criteria.
5 | Power State Settable | The SetPowerState method is supported.
6 | Power Cycling Supported | The SetPowerState method can be invoked with the PowerState input variable set to 5 (Power Cycle).
7 | Timed Power On Supported | As 6 (Power Cycling Supported), but also allows the Time parameter to specify a power-on time.

For more information, see SetPowerState

Inherited from CIM_UnitaryComputerSystem.

PowerManagementSupported
Boolean that indicates whether the node supports power management.

Inherited from CIM_UnitaryComputerSystem.

PowerState
A uint16 that indicates the current power state of the node as one of the following values.
Value | Setting | Description
0 | Unknown | The node's power state cannot be determined.
1 | Full Power | The node is operating at full power.
2 | Power Save - Low Power Mode | The node is in a power save state and is available, but its performance may be degraded.
3 | Power Save - Standby | The node is in a power save state and is unavailable but can be powered up quickly.
4 | Power Save - Unknown | The node is in an unrecognized power save state.
5 | Power Cycle | The node is changing power states.
6 | Power Off | The node is powered off and unavailable.
7 | Power Save - Warning | the node is in a low power state and is generating a warning (for example, a low battery warning from a laptop).

Inherited from CIM_UnitaryComputerSystem.

PrimaryOwnerContact
Qualifiers: MaxLen (256), MappingStrings {"MIF.DMTF|General Information|001.3"}

String that provides information on how the primary system owner can be reached (for example, phone number or e-mail address).

Inherited from CIM_UnitaryComputerSystem.

PrimaryOwnerName
Qualifiers: MaxLen (64)

String that specifies the name of the primary system owner.

Inherited from CIM_UnitaryComputerSystem.

ResetCapability
A uint16 that describes whether the node supports remote reset as one of the following values.
Value | Meaning
1 | Other
2 | Unknown
3 | Disabled
4 | Enabled
5 | Not Implemented

Inherited from CIM_UnitaryComputerSystem.

Roles
A string array that specifies the roles this node plays in the IT-environment.

Inherited from CIM_UnitaryComputerSystem.

Status
Qualifiers: MaxLen (10)

String that indicates the current status of the node as one of the following values.
Value | Description
"OK" | The node is operational.
"Error" | No status information is available due to an unknown error.
"Unknown" | The node returned unrecognized state information.

Inherited from CIM_UnitaryComputerSystem.

StatusCode
Qualifiers: Read

A uint32 that indicates the current status of the node as one of the following values.
Value | Constant
1005 | WLBS_STOPPED
1006 | WLBS_CONVERGING
1007 | WLBS_CONVERGED
1008 | WLBS_DEFAULT
1009 | WLBS_DRAINING
1013 | WLBS_SUSPENDED

For a description of the values 1105 through 1013, see the Standard Return Values.

Methods

The MicrosoftNLB_Node class has the following methods.

Method | Description
Disable | Qualifiers: Implemented Disables a range of ports on the node.
Drain | Qualifiers: Implemented Drains a range of ports on the node.
DrainStop | Qualifiers: Implemented Drains all ports, then stops cluster operations on the node.
Enable | Qualifiers: Implemented Enables ports that have been disabled on the node.
Resume | Qualifiers: Implemented Resumes all suspended ports on the node.
SetPowerState | Not used. Inherited from CIM_UnitaryComputerSystem.
Start | Qualifiers: Implemented Starts cluster operations on the node.
Stop | Qualifiers: Implemented Stops cluster operations on the node.
Suspend | Qualifiers: Implemented Suspends cluster operations on the node.

Remarks

The MicrosoftNLB_Node class is derived from the CIM_UnitaryComputerSystem class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_Node : CIM_UnitaryComputerSystem
{
  [ Read, Override ("Name") ]
  string Name;

  [ Read ]
  uint32 HostPriority;

  [ Read ]
  string DedicatedIPAddress;

  [ Read,
    Values { "WLBS_SUSPENDED", "WLBS_STOPPED", "WLBS_DRAINING",
             "WLBS_CONVERGING", "WLBS_CONVERGED",
             "WLBS_DEFAULT" }: ToInstance,
    ValueMap { "1013", "1005", "1009", "1006", "1007",
               "1008" }: ToInstance ]
  uint32 StatusCode;
};


Disable Method of the MicrosoftNLB_Node Class

The Disable method disables a range of ports on the node.

[MOF]
uint32 Disable(
  uint32 Port
);

Parameters

Port
[in] To affect a range of ports, set Port to a port number ( 0 to 65,535 ). All ports in the port rule containing the specified port number will be affected. To affect all ports, set Port to 0xFFFFFFFF.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

When enumerating instances of the MicrosoftNLB_Node class, you will always receive an instance representing the provider node, regardless of the remote control setting on the provider node. If there are any nodes in the cluster with remote control enabled, you will get instances representing those nodes as well. However, the provider node will always be listed first in an enumeration. For more information, see enumerating nodes.

To block new connections while allowing existing connections to terminate normally, use the Drain method of the MicrosoftNLB_Node class.

To re-enable disabled ports, use the Enable method of the MicrosoftNLB_Node class.

See Also

Drain Method of the MicrosoftNLB_Node Class, Enable Method of the MicrosoftNLB_Node Class, MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


Drain Method of the MicrosoftNLB_Node Class

The Drain method drains a range of ports on the node.

[MOF]
uint32 Drain(
  uint32 Port
);

Parameters

Port
[in] To affect a range of ports, set Port to a port number ( 0 to 65,535 ). All ports in the port rule containing the specified port number will be affected. To affect all ports, set Port to 0xFFFFFFFF.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


DrainStop Method of the MicrosoftNLB_Node Class

The DrainStop drains all ports and stops cluster operations on the node.

[MOF]
uint32 DrainStop();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


Enable Method of the MicrosoftNLB_Node Class

The Enable method enables ports that have been disabled on the node.

[MOF]
uint32 Enable(
  uint32 Port
);

Parameters

Port
[in] To affect a range of ports, set Port to a port number ( 0 to 65,535 ). All ports in the port rule containing the specified port number will be affected. To affect all ports, set Port to 0xFFFFFFFF.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


Resume Method of the MicrosoftNLB_Node Class

The Resume method resumes cluster operations on the node.

[MOF]
uint32 Resume();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


SetPowerState Method of the MicrosoftNLB_Node Class

The SetPowerState method is inherited from CIM_UnitaryComputerSystem and is currently not used by the Network Load Balancing provider.

See Also

MicrosoftNLB_Node


Start Method of the MicrosoftNLB_Node Class

The Start method starts cluster operations on the node.

[MOF]
uint32 Start();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


Stop Method of the MicrosoftNLB_Node Class

The Stop method stops cluster operations the node.

[MOF]
uint32 Stop();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


Suspend Method of the MicrosoftNLB_Node Class

The Suspend method suspends cluster operations on the node.

[MOF]
uint32 Suspend();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_ClusterSetting, MicrosoftNLB_Node


MicrosoftNLB_NodeNodeSetting

The MicrosoftNLB_NodeNodeSetting CIM association class associates an instance of the MicrosoftNLB_Node class to an instance of the MicrosoftNLB_NodeSetting class.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_NodeNodeSetting : CIM_ElementSetting
{
MicrosoftNLB_Node REF Element
MicrosoftNLB_NodeSetting REF Setting
};

Properties

The MicrosoftNLB_NodeNodeSetting class has the following properties:

Element
Qualifiers: Key, Override("Antecedent"), Min (1)

Reference to a MicrosoftNLB_Node instance that represents a cluster node.

Inherited from CIM_ElementSetting.

Setting
Qualifiers: Key, Override("Dependent")

Reference to a MicrosoftNLB_NodeSetting instance that represents the settings for a node.

Inherited from CIM_ElementSetting.

Remarks

The MicrosoftNLB_NodeNodeSetting class is derived from the CIM_ElementSetting class.

MOF Code

[ Association, Dynamic: ToInstance,
  Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_NodeNodeSetting : CIM_ElementSetting
{
  [ Key, Override("Element"), Min (1) ]
  MicrosoftNLB_Node REF Element;

  [ Key, Override("Setting") ]
  MicrosoftNLB_NodeSetting REF Setting;
};

See Also

MicrosoftNLB_Node, MicrosoftNLB_NodeSetting


MicrosoftNLB_NodeSetting

The MicrosoftNLB_NodeSetting WMI class represents the configuration data specific to a node.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_NodeSetting : CIM_Setting
{
string AdapterGuid
string AdapterDisplayName
uint32 AliveMessagePeriod
uint32 AliveMessageTolerance
string Caption
Boolean ClusterModeOnStart
string DedicatedIPAddress
string DedicatedNetworkMask
string Description
uint32 DescriptorsPerAlloc
uint32 HostPriority
Boolean MaskSourceMAC
uint32 MaxDescriptorsPerAlloc
string Name
uint32 NumActions
uint32 NumAliveMessages
uint32 NumberOfRules
uint32 NumPackets
uint32 RemoteControlUDPPort
string SettingID
};

Properties

The MicrosoftNLB_NodeSetting class has the following properties:

AdapterGuid
A string that specifies the GUID of the adapter to which Network Load Balancing is bound.
AdapterDisplayName
A string that specifies the display name of the adapter to which Network Load Balancing is bound.
AliveMessagePeriod
A uint32 that specifies the message exchange period in milliseconds. You should pick this number based on your failover requirements. A longer message exchange period will reduce the networking overhead needed to maintain fault tolerance, but it will increase the failover delay.
AliveMessageTolerance
A uint32 that specifies how many exchanged messages from a node can be missed before the cluster initiates convergence. You should adjust this number based on your availability requirements. Increasing the number of message exchanges before convergence will reduce the number of unnecessary convergence initiations due to transient network congestion, but it will also increase the failover delay.
Caption
Not used. Inherited from CIM_Setting.
ClusterModeOnStart
A Boolean value that specifies whether the node should join the cluster on boot.
DedicatedIPAddress
Qualifiers: ModelCorrespondence {"MicrosoftNLB_Node .DedicatedIPAddress"}

String that specifies this node's unique IP address used for network traffic not associated with the cluster (for example, Telnet access to a specific node within the cluster).

DedicatedNetworkMask
String that specifiesthe subnet mask.
Description
Not used. Inherited from CIM_Setting.
DescriptorsPerAlloc
A uint32 that specifies the number of connection tracking descriptors per allocation.
HostPriority
Qualifiers: ModelCorrespondence {"MicrosoftNLB_Node .HostPriority"}

A uint32 that specifies a node's unique priority for handling default network traffic for TCP and UDP ports that are not otherwise specified in the port rules tab of the Network Load Balancing Properties dialog box. It is used in case a node within the cluster goes offline, and it determines which node within the cluster will take over handling this traffic if required. The allowed values for a node's host priority range from 1 to the maximum number of nodes. Lower values indicate higher priorities (where 1 is the highest priority). Each node within the cluster must specify a unique host priority.

MaskSourceMAC
If TRUE, mangle source MAC address to prevent switch learning. Use a value of FALSE if the cluster is on a hub; this value optimizes switch performance by re-enabling learning.
MaxDescriptorsPerAlloc
A uint32 that specifies the maximum number of connection tracking descriptors per allocation.
Name
Qualifiers: Key, Read

String that specifies the name of the node that owns this set of cluster configuration data. This is the name stored in the MicrosoftNLB_Node Name property.

NumActions
A uint32 that specifies the number of actions per allocation.
NumAliveMessages
A uint32 that specifies the number of heartbeats per allocation.
NumberOfRules
Qualifiers: Read

A uint32 that specifies the number of defined port rules.

NumPackets
A uint32 that specifies the number of packets per allocation.
RemoteControlUDPPort
A uint32 that specifies the UDP port that is used to receive remote control commands. By default, these are ports 1717 and 2504 at the cluster IP address.
SettingID
Not used. Inherited from CIM_Setting.

Methods

The MicrosoftNLB_NodeSetting class has the following methods.

Method | Description
GetPortRule | Qualifiers: Implemented. This method retrieves the port rule associated with a port number.
LoadAllSettings | Qualifiers: Implemented. Propagates all current settings (cluster, node, and port rule) to the Network Load Balancing driver
SetDefaults | Qualifier: Implemented Resets all of the properties of the MicrosoftNLB_NodeSetting class to their default values.

Remarks

After changing any MicrosoftNLB_ClusterSetting properties, you must call LoadAllSettings to bring the new values into effect. For more information, see LoadAllSettings.

The MicrosoftNLB_NodeSetting class is derived from the CIM_Setting class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_NodeSetting : CIM_Setting
{
  [ Key, Read ]
  string Name;

  [ ModelCorrespondence {"MicrosoftNLB_Node.DedicatedIPAddress"} ]
  string DedicatedIPAddress;

  string DedicatedNetworkMask;

  [ Read ]
  uint32 NumberOfRules;

  [ ModelCorrespondence {"MicrosoftNLB_Node.HostPriority"} ]
  uint32 HostPriority;

  uint32 AliveMessagePeriod;

  uint32 AliveMessageTolerance;

  Boolean ClusterModeOnStart;

  uint32 RemoteControlUDPPort;

  Boolean MaskSourceMAC;

  uint32 DescriptorsPerAlloc;

  uint32 MaxDescriptorsPerAlloc;

  uint32 NumActions;

  uint32 NumPackets;

  uint32 NumAliveMessages;

};

See Also

MicrosoftNLB_ClusterSetting


GetPortRule Method of the MicrosoftNLB_NodeSetting Class

The GetPortRule method retrieves the port rule associated with a port number.

[MOF]
void GetPortRule(
  UINT32 Port,
  MicrosoftNLB_PortRule PortRule
);

Parameters

Port
[in] Specifies a port number within the range of ports covered by the port rule.
PortRule
[out] A MicrosoftNLB_PortRule object.

Return Values

This method returns a uint32 set to one of the standard return values.

See Also

MicrosoftNLB_NodeSetting


LoadAllSettings Method of the MicrosoftNLB_NodeSetting Class

The LoadAllSettings method forces the Network Load Balancing driver to reload, which allows it to update its private copy of the cluster configuration data.

[MOF]
uint32 LoadAllSettings();

Parameters

This method has no parameters.

Return Values

This method returns a uint32 set to one of the standard return values.

Remarks

Because the Network Load Balancing driver runs "beneath" the operating system, its only opportunity to read and save cluster configuration data is during its initialization. The LoadAllSettings method forces the driver to reload, which updates its private data store and "commits" the changes to the cluster.

Note that in Windows NT 4.0, the reload functionality is not supported and the method will return a reboot request. In other words, you must reboot Windows NT 4.0 nodes in order to commit any configuration change.

See Also

MicrosoftNLB_NodeSetting


SetDefaults Method of the MicrosoftNLB_NodeSetting Class

The SetDefaults method resets all of the properties of the MicrosoftNLB_NodeSetting class to their default values.

[MOF]
void SetDefaults();

Parameters

This method has no parameters.

Return Values

This method has no return values.

Remarks

Use the LoadAllSettings method to commit the setting changes to the cluster.

See Also

MicrosoftNLB_NodeSetting


MicrosoftNLB_NodeSettingPortRule

The MicrosoftNLB_NodeSettingPortRule CIM association class Associates an instance of the MicrosoftNLB_NodeSetting class to instances of classes derived from MicrosoftNLB_PortRule.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_NodeSettingPortRule : CIM_Component
{
MicrosoftNLB_NodeSetting REF GroupComponent
MicrosoftNLB_PortRule REF PartComponent
};

Properties

The MicrosoftNLB_NodeSettingPortRule class has the following properties:

GroupComponent
Qualifiers: Key, Override("GroupComponent"), Min (1)

Reference to a MicrosoftNLB_NodeSetting instance that represents the settings for a node.

Inherited from CIM_Component.

PartComponent
Qualifiers: Key, Override("PartComponent")

Reference to a MicrosoftNLB_PortRule instance that represents a port rule.

Inherited from CIM_Component.

Remarks

The MicrosoftNLB_NodeSettingPortRule class is derived from the CIM_Component class.

MOF Code

[ Association, Dynamic: ToInstance,
  provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_NodeSettingPortRule : CIM_Component
{
  [ Key, Override("GroupComponent"), Min (1) ]
  MicrosoftNLB_NodeSetting REF GroupComponent;

  [ Key, Override("PartComponent") ]
  MicrosoftNLB_PortRule REF PartComponent;
};


MicrosoftNLB_ParticipatingNode

The MicrosoftNLB_ParticipatingNode CIM association class associates an instance of the MicrosoftNLB_Cluster class with participating MicrosoftNLB_Node class instances.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_ParticipatingNode : CIM_ParticipatingCS
{
MicrosoftNLB_Node REF Antecedent
MicrosoftNLB_Cluster REF Dependent
uint16 RoleOfNode
uint16 StateOfNode
};

Properties

The MicrosoftNLB_ParticipatingNode class has the following properties:

Antecedent
Qualifiers: Key, Override("Antecedent"), Min (1)

Reference to a MicrosoftNLB_Node instance that represents an independent computer system currently participating in the cluster.

Inherited from CIM_ParticipatingCS.

Dependent
Qualifiers: Key, Override("Dependent")

Reference to a MicrosoftNLB_Cluster instance that represents the cluster.

Inherited from CIM_ParticipatingCS.

RoleOfNode
Not used. Inherited from CIM_ParticipatingCS.
StateOfNode
Not used. Inherited from CIM_ParticipatingCS.

Remarks

Enumerating instances of the MicrosoftNLB_ParticipatingNode class will have the same results as enumerating instances of MicrosoftNLB_Node. For more information see enumerating nodes.

An attempt to obtain a MicrosoftNLB_Cluster instance using the Dependent property will fail if no nodes have remote control enabled.

The MicrosoftNLB_ParticipatingNode class is derived from the CIM_ParticipatingCS class.

MOF Code

[ Association, Dynamic: ToInstance,
  Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_ParticipatingNode : CIM_ParticipatingCS
{
  [ Key, Override ("Antecedent") Min (1) ]
  MicrosoftNLB_Node REF Antecedent;

  [ Key, Override ("Dependent") ]
  MicrosoftNLB_Cluster REF Dependent;
};

See Also

MicrosoftNLB_Cluster, MicrosoftNLB_Node


MicrosoftNLB_PortRule

The MicrosoftNLB_PortRule WMI class is an abstract base class from which classes that represent port rules are derived.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_PortRule : CIM_Setting
{
string AdapterGuid
string Caption
string Description
uint32 EndPort
string Name
uint32 Protocol
string SettingID
uint32 StartPort
};

Properties

The MicrosoftNLB_PortRule class has the following properties:

AdapterGuid
A string that specifies the GUID of the adapter to which Network Load Balancing is bound.
Caption
Not used. Inherited from CIM_Setting.
Description
String that describes the MicrosoftNLB_PortRule object.

Inherited from CIM_Setting.

EndPort
A uint32 that describes the ending port number to which this rule applies. The default is 65535.
Name
Qualifiers: Key, Override("Name")

String that specifies the name of the node to which this port rule applies. This is the name stored in the MicrosoftNLB_Node Name property.

Inherited from CIM_Setting.

Protocol
A uint32 that describes the network protocol to which this rule applies. The possible values are the following.
Value | Protocol
1 | TCP
2 | UDP
3 | Both (the default)

SettingID
Not used. Inherited from CIM_Setting.
StartPort
Qualifiers: Key

A uint32 that specifies the starting port number to which this rule applies. The default is 0 (zero).

Methods

The MicrosoftNLB_PortRule class has the following method.

Method | Description
SetDefaults | Qualifiers: Static, Implemented Resets the node's port rule configuration to the default.

Remarks

The MicrosoftNLB_PortRule class is derived from the CIM_Setting class.

MOF Code

[ Abstract, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_PortRule : CIM_Setting
{
  [ Key, Override("Name") ]
  string Name;

  [ Key ]
  uint32 StartPort = 0;

  uint32 EndPort = 65535;

  [ Values {"TCP", "UDP", "Both"},
    ValueMap {"1", "2", "3"} ]
  uint32 Protocol = 3;

  [ Static, Implemented
    Values   { "WLBS_OK" } : ToInstance,
    ValueMap { "1000" } : ToInstance ]
  void SetDefaults([IN] MicrosoftNLB_Node ref Node);
};


SetDefaults Method of the MicrosoftNLB_PortRule Class

The SetDefaults method resets the node's port rule configuration to the default.

[MOF]
void SetDefaults(
  MicrosoftNLB_Node REF Node
);

Parameters

Node
[in] A MicrosoftNLB_Node object.

Return Values

See Standard Return Values.

Remarks

Use the LoadAllSettings method to commit the setting changes to the cluster.

See Also

MicrosoftNLB_PortRule


MicrosoftNLB_PortRuleDisabled

The MicrosoftNLB_PortRuleDisabled WMI class represents a port rule on a single node whose filtering mode is set to "Disable."

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_PortRuleDisabled : MicrosoftNLB_PortRule
{
string Caption
string Description
uint32 EndPort
string Name
uint32 Protocol
string SettingID
uint32 StartPort
};

Properties

The MicrosoftNLB_PortRuleDisabled class has the following properties.

Caption
Not used. Inherited from MicrosoftNLB_PortRule.
Description
Not used. Inherited from MicrosoftNLB_PortRule.
EndPort
A uint32 that specifies the ending port number to which this port rule applies

Inherited from MicrosoftNLB_PortRule.

Name
Qualifiers: Key, Override("Name")

String that specifies the name of the node to which this port rule applies. This is the name stored in the MicrosoftNLB_Node Name property.

Inherited from MicrosoftNLB_PortRule.

Protocol
A uint32 that specifies the network protocol to which this rule applies. The possible values are the following.
Value | Protocol
1 | TCP
2 | UDP
3 | Both

Inherited from MicrosoftNLB_PortRule.

SettingID
Not used. Inherited from MicrosoftNLB_PortRule.
StartPort
Qualifiers: Key

A uint32 that specifies the starting port number to which this rule applies.

Inherited from MicrosoftNLB_PortRule.

Remarks

An instance of the MicrosoftNLB_PortRuleDisabled class corresponds to a port rule on a single cluster node (specified by the Name property). The instance can be obtained from the GetPortRule method of the MicrosoftNLB_NodeSetting class. After changing any MicrosoftNLB_PortRuleDisabled properties, you must call the LoadAllSettings method of the MicrosoftNLB_NodeSetting class to bring the new values into effect.

The MicrosoftNLB_PortRuleDisabled class is derived from the MicrosoftNLB_PortRule class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0") LOCALE(0x409) ]
class MicrosoftNLB_PortRuleDisabled : MicrosoftNLB_PortRule
{
};

See Also

MicrosoftNLB_PortRule, MicrosoftNLB_PortRuleFailover, MicrosoftNLB_PortRuleLoadbalanced


MicrosoftNLB_PortRuleFailover

The MicrosoftNLB_PortRuleFailover WMI class represents a Network Load Balancing port rule set to single-host filtering mode.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_PortRuleFailover : MicrosoftNLB_PortRule
{
string Caption
string Description
uint32 EndPort
string Name
uint32 Priority
uint32 Protocol
string SettingID
uint32 StartPort
};

Properties

The MicrosoftNLB_PortRuleFailover class has the following properties.

Caption
Not used. Inherited from MicrosoftNLB_PortRule.
Description
Not used. Inherited from MicrosoftNLB_PortRule.
EndPort
A uint32 that specifies the ending port number to which this rule applies.

Inherited from MicrosoftNLB_PortRule.

Name
Qualifiers: Key

String that specifies the name of the node to which this port rule applies. This is the name stored in the MicrosoftNLB_Node Name property.

Inherited from MicrosoftNLB_PortRule.

Priority
A uint32 that specifies the local node's host priority for handling the networking traffic for this port rule. The node with the highest handling priority (lowest numerical value) for this rule among the current members of the cluster will handle all of the traffic for this rule. The allowed values range from 1, the highest priority (and the default), to the maximum number of nodes allowed. This value must be unique for all nodes in the cluster.
Protocol
A uint32 that specifies the network protocol to which this rule applies. The possible values are the following.
Value | Protocol
0 | TCP
1 | UDP
2 | Both

Inherited from MicrosoftNLB_PortRule.

SettingID
Not used. Inherited from MicrosoftNLB_PortRule.
StartPort
Qualifiers: Key

A uint32 that specifies the starting port number to which this rule applies.

Inherited from MicrosoftNLB_PortRule.

Remarks

An instance of the MicrosoftNLB_PortRuleFailover class corresponds to a port rule on a single cluster node (specified by the Name property). The instance can be obtained from the GetPortRule method of the MicrosoftNLB_NodeSetting class. After changing any MicrosoftNLB_PortRuleFailover properties, you must call the LoadAllSettings method of the MicrosoftNLB_NodeSetting class to bring the new values into effect.

The MicrosoftNLB_PortRuleFailover class is derived from the MicrosoftNLB_PortRule class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_PortRuleFailover : MicrosoftNLB_PortRule
{
  [ LOCALE(0x409) ]
  uint32 Priority = 1;
};

See Also

MicrosoftNLB_PortRule, MicrosoftNLB_PortRuleLoadBalanced, MicrosoftNLB_PortRuleDisabled


MicrosoftNLB_PortRuleLoadbalanced

The MicrosoftNLB_PortRuleLoadbalanced WMI class represents a Network Load Balancing port rule set to multiple-host filtering mode.

The following syntax is simplified from MOF code and includes all inherited properties. For a compilable version (without inherited properties), see the MOF Code section.

class MicrosoftNLB_PortRuleLoadbalanced : MicrosoftNLB_PortRule
{
uint32 Affinity
string Caption
string Description
uint32 EndPort
Boolean EqualLoad
uint32 LoadWeight
string Name
uint32 Protocol
string SettingID
uint32 StartPort
};

Properties

The MicrosoftNLB_PortRuleLoadbalanced class has the following properties.

Affinity
A uint32 that specifies client affinity as one of the following values.
Value | Affinity
0 | None
1 | Single (the default)
2 | Class C

For more information on affinity, see the Windows 2000 Help documentation.

Caption
Not used. Inherited from MicrosoftNLB_PortRule.
Description
Not used. Inherited from MicrosoftNLB_PortRule
EndPort
A uint32 that specifies the ending port number to which this rule applies.

Inherited from MicrosoftNLB_PortRule

EqualLoad
A Boolean value that specifies whether the node accepts an equal portion of the load-balanced traffic in multiple-host filtering mode for this port rule. If this property is set to TRUE (the default), the node accepts an equal portion of the load-balanced traffic.
LoadWeight
A uint32 that specifies the percentage of load-balanced network traffic that this node should handle for the associated port rule. Allowed values range from 0 (zero) to 100; defaults to 50. To prevent a node from handling any network traffic, set the load weight to 0 (zero).
Name
Qualifiers: Key

String that specifies the name of the node to which this port rule applies. This is the name stored in the MicrosoftNLB_Node Name property.

Inherited from MicrosoftNLB_PortRule

Protocol
A uint32 that specifies the network protocol to which this rule applies. The possible values are the following.
Value | Protocol
1 | TCP
2 | UDP
3 | Both

Inherited from MicrosoftNLB_PortRule

SettingID
Not used. Inherited from MicrosoftNLB_PortRule
StartPort
Qualifiers: Key

A uint32 that specifies the starting port number to which this rule applies.

Inherited from MicrosoftNLB_PortRule

Remarks

An instance of the MicrosoftNLB_PortRuleLoadbalanced class corresponds to a port rule on a single cluster node (specified by the Name property).

The instance can be obtained from the GetPortRule method of the MicrosoftNLB_NodeSetting class. After changing any MicrosoftNLB_PortRuleLoadbalanced properties, you must call the LoadAllSettings method of the MicrosoftNLB_NodeSetting class to bring the new values into effect.

The MicrosoftNLB_PortRuleLoadbalanced class is derived from the MicrosoftNLB_PortRule class.

MOF Code

[ Dynamic, Provider("Microsoft|NLB_Provider|V1.0"), LOCALE(0x409) ]
class MicrosoftNLB_PortRuleLoadbalanced : MicrosoftNLB_PortRule
{
  Boolean EqualLoad = True;

  uint32 LoadWeight = 50;

  [ Values {"None", "Single", "ClassC"} : Amended,
    ValueMap{"0", "1", "2"} ]
  uint32 Affinity = 1;
};

See Also

MicrosoftNLB_PortRule, MicrosoftNLB_PortRuleFailover, MicrosoftNLB_PortRuleDisabled


Standard Return Values

The Network Load Balancing Provider communicates status and error information as follows:

  • All WMI operations that produce an error create an __ExtendedStatus object. Depending on the source of the error, the StatusCode property of the __ExtendedStatus object may contain one of the values listed below.
  • The MicrosoftNLB_Cluster and MicrosoftNLB_Node methods also generate the following values which are returned through the ReturnValue property of IWbemClassObject.
Value | Error code | Description
1000 | WLBS_OK | The operation completed successfully.
1001 | WLBS_ALREADY | The specified target is already in the state that the requested operation would produce.
1002 | WLBS_DRAIN_STOP | One or more nodes reported a drain stop operation.
1003 | WLBS_BAD_PARAMS | Bad configuration parameters in a node's registry prevented the node from starting cluster operations.
1004 | WLBS_NOT_FOUND | The specified port number was not found in any port rule..
1005 | WLBS_STOPPED | Cluster operations have stopped on at least one node.
1006 | WLBS_CONVERGING | The cluster is converging.
1007 | WLBS_CONVERGED | The cluster has converged successfully.
1008 | WLBS_DEFAULT | The specified node has converged as the default host.
1009 | WLBS_DRAINING | One or more nodes are draining.
1013 | WLBS_SUSPENDED | Cluster operations have been suspended on one or more nodes.
1050 | WLBS_REBOOT | The node must be rebooted for the specified configuration changes to take effect.
1100 | WLBS_INIT_ERROR | An internal error prevented initialization of the cluster control module.
1101 | WLBS_BAD_PASSW | The specified password was not accepted by the cluster.
1102 | WLBS_IO_ERROR | A local I/O error prevents communication with the Network Load Balancing driver.
1103 | WLBS_TIMEOUT | The requested operation timed out without receiving a response from the specified node.
1150 | WLBS_PORT_OVERLAP | At least one of the port numbers in the specified port rule is currently listed in at least one other port rule.
1151 | WLBS_BAD_PORT_PARAMS | The settings for one or more port rules contain one or more invalid values.
1152 | WLBS_MAX_PORT_RULES | The cluster contains the maximum number of port rules.
1153 | WLBS_TRUNCATED | The return value has been truncated.
1154 | WLBS_REG_ERROR | An internal registry access error occurred.


Network Load Balancing Glossary

A – E

availability
A measure of a computer system's ability to maintain services despite hardware or software failures. A highly available system delivers services to clients a high percentage of the time.
CIM
See Common Information Model.
CIM class
See WMI class.
CIP
See cluster IP address.
cluster
A group of independent computer systems, referred to as nodes, working together as a unified computing resource.
cluster IP address
The IP address serviced by a Network Load Balancing cluster. All network traffic directed to the cluster IP address is either handled by the current port rule settings or by the default host. The cluster IP address is sometimes referred to as the CIP.
Common Information Model (CIM)
A programming paradigm that describes how to represent real-world managed objects. Used for WMI class specification.
convergence
The process of redistributing the existing connection load to operational cluster nodes according to the current load balancing rules.
default host
The node with the lowest host priority is the default host, The default host handles all of the network traffic for TCP and UDP ports that are not otherwise covered by port rules.
direct connection
A WMI connection in which the namespace resolves to the dedicated IP address of a cluster node, which becomes the provider node.
drain
A state in which a node is no longer accepting incoming traffic is draining. No new connections are allowed, but existing connections are allowed to complete their jobs and terminate naturally. While draining, a node can participate in convergence and remains part of the cluster.


F - M

Platform SDK: Windows Clustering

F – M

filtering mode
Part of a port rule specification that determines how inbound network traffic is distributed among ports.
host
Another name for a node. As used in the Network Load Balancing documentation, a host is a computer running Windows NT®/Windows® 2000 that runs an Internet server program or service. A cluster consists of multiple hosts connected over a local area network, which is in turn connected to the Internet.
host priority
A unique integer that identifies a particular node in the cluster. The node with the lowest priority handles all traffic not otherwise handled by the current set of port rules.
load
The amount of work being done by a node. In Network Load Balancing, load is measured as a raw number of connections.
load balancing
A technique for scaling the performance of a server-based application (such as a Web server) by distributing its client requests across multiple nodes within the cluster.
local connection
A situation where the provider client and the provider node happen to be the same computer system. This situattion has nothing to do with whether an operation is considered a local operation or a remote operation.

See also remote connection and remote administration.

local operation
Any operation initiated by the Network Load Balancing provider that affects the provider node. The word 'local' in this context means "local relative to the provider." A node will always respond to a local operation, regardless of its RemoteControlEnabled setting.
multiple-host filtering mode
A port rule setting in which multiple nodes handle a portion of the traffic flowing into the port range defined by the port rule.


N - Z

Platform SDK: Windows Clustering

N – Z

namespace
As used by WMI, a namespace is a group of classes and instances. This group controls the scope and visibility of the classes and instances it contains. Namespaces are like logical databases.
network interface card (NIC)
A hardware plug-in board that connects a node to a local area network. Network Load Balancing currently supports FDDI, Ethernet and fast Ethernet adapter cards.

Also called adapter card.

Network Load Balancing cluster
One of two types of clusters provided by Windows Clustering that distributes and load balances network connections among servers, providing scalability for stateless TCP/IP applications and services.
NIC
See network interface card.
node
As used in the Network Load Balancing documentation, a node (also called a host) is a computer running Windows NT®/Windows® 2000 that runs an Internet server program or service. A cluster consists of multiple nodes connected over a local area network, which is in turn connected to the Internet.
port range
All of the port numbers within a range specified by a minimum and maximum port number. Every port rule includes a port range defining the port numbers affected by the rule.
port rule
A setting that determines how Network Load Balancing filters incoming traffic for a range of ports. Administrators configure a port rule by specifying a filtering mode, protocols, and a port range. A port rule applies the filtering mode to all traffic of the specified protocols flowing into all ports in the specified range. The Network Load Balancing API includes functions to enable and disable port rules.
protocol
The kind of network traffic to which a port rule applies. Protocol can be set to TCP, UDP, or both.
provider
A component that allows Windows Management Instrumentation (WMI) to communicate with new kinds of managed objects by extending the WMI class repository. The Network Load Balancing Provider defines classes for querying and configuring Network Load Balancing clusters, nodes, and port rules.
provider client
The computer system from which an application connects to a provider through WMI.
provider node
The cluster node on which the Network Load Balancing provider is running.
remote administration
Describes how WMI views the connection between the provider client and the provider node. The connection is always treated as remote even if the provider client and the provider node are the same computer system. Remote administration has nothing to do with whether an operation is considered a local operation or a remote operation.
remote connection
A situation where the provider client and the provider node happen to be different computer systems. Remote connections has nothing to do with whether an operation is considered a local operation or a remote operation.

See also local connection and remote administration.

remote operation
Any operation initiated by the Network Load Balancing provider that affects a node other than the provider. The word '"remote" in this context means "remote relative to the provider." A node will respond to a remote operation only if its RemoteControlEnabled setting is TRUE.
routed connection
A WMI connection in which the namespace resolves to the cluster IP address and is routed to a provider node according to the Network Load Balancing port rules currently in effect.
scalability
A measure of how well a computer system can grow to meet increasing demands.
server cluster
The type of cluster that the Cluster service implements. Server clusters are characterized by high availability. The server cluster is one of two types of clusters provided by Microsoft® Windows Clustering.
single-host filtering mode
A port rule setting in which all traffic flowing into the port range defined by the port rule is handled by a single node.
Windows Clustering
A feature of the Microsoft® Windows NT®/Windows® 2000 operating system that supports two different types of clusters: the server cluster and the network load balancing cluster.
Windows Management Instrumentation (WMI)
A unified architecture for describing, accessing, and instrumenting objects. Part of this architecture is a large repository of CIM classes that WMI can use to carry out management tasks on specific objects.
WMI
See Windows Management Instrumentation.
WMI class
A template for a type of managed object. WMI classes are based on the Common Information Model (CIM), as implemented in Windows Management Instrumentation (WMI).


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.