Legal Information

Microsoft Cluster Server

Information in this document is subject to change without notice. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1996 - 1997 Microsoft Corporation. All rights reserved.

Microsoft, Microsoft Press, MS, MS-DOS, Visual Basic, Visual C++, Windows, Win32, Win32s, Windows NT, and Developer Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. OS/2 is a registered trademark licensed to Microsoft Corporation. Other product and company names mentioned herein may be the trademarks of their respective owners.

Portions of the glossary reprinted with permission from Tandem Computers, Inc.


Cluster Server Concepts and Architecture

Clustering technologies have been built and used for many years to provide users with systems that are highly available, scalable, and easy to administer. Clustering enables several connected systems to appear to network users as a single, highly available system. If one of the systems in the cluster fails, another system continues to provide service, picking up where the failed system left off.

Clusters are also highly scalable, meaning that CPU, I/O, storage, and application resources can be added incrementally to expand capacity efficiently. Using clustering technology, system administrators can add smaller, standard systems as needed to meet overall processing power requirements.

Microsoft® Cluster Server is a software clustering technology that enables applications to run efficiently on Microsoft® Windows NT® Server network operating system platforms. Cluster Server directs client requests to the specific system in the cluster that is hosting the group of resources needed to service the request. If that system is unavailable, its resources are transferred to an alternate system and the request is redirected. Applications that are written to take full advantage Cluster Server features can cause this transfer to be transparent to the client.

Cluster Server focuses on high availability rather than on fault tolerance. A fault-tolerant system offers non stop availability, but at a significant cost. Fault tolerance is usually implemented by keeping a backup of the primary system. The backup system remains idle and unused until a failure occurs and must be kept completely consistent with the primary system. With Cluster Server, all systems remain active, performing normal, routine functions. Consistency across the systems is ensured. Cluster Server allows a small amount of down time to enable users to achieve high levels of availability and a better utilization of computing resources.


Clustering Models

Two principal software models are used in clustering today: shared disk and shared nothing. In the shared disk model, software running on any node in the cluster may access any disk connected to any system in the cluster. If two systems need to see the same data, the data must be read twice from the disk. The disk is mounted by both systems and access is synchronized through distributed locking.

The shared disk model is effective in reducing the required number of expensive peripheral devices and enables individual computers to access data stored in a shared-disk database management system. However, access to the shared device can limit system scalability. Shared-disk databases, for example, cannot grow beyond a certain size because of the overhead needed to coordinate access to the shared disks from many processors.

In the shared nothing model, systems share neither memory nor devices. Cluster Server uses the shared nothing model. Each system has its own memory, operating system, and subset of the cluster's resources. Only one system may own and access a particular resource at a time, although, on failure, another system may take ownership of the resource. Requests from clients are automatically routed to the system that owns the resource. Connections between systems are optimized because messages are passed across a high-speed, dedicated bus. Each system within the cluster owns a subset of the cluster's resources.


Cluster Server Concepts and Terminology

As defined by Microsoft® Cluster Server, a cluster is a loosely coupled collection of two or more independent Microsoft® Windows NT® Server systems. Network clients and administrators view this collection as a single system.

The computer systems that make up the collection are known as nodes. To ensure availability, the nodes communicate across redundant network paths. Cluster resources, the entities that Cluster Server manages, are hosted by the cluster nodes. Cluster Server can manage as a resource any entity that can be taken offline, brought online, and moved to another node if a failure occurs.

A cluster projects its own unique identity distinct from the identities of its nodes. This identity is used by network clients to access the applications and services running on the cluster nodes and by administrators to manage the cluster. Maintaining a unique identity allows Cluster Server to transparently move applications and related resources between nodes, to replace a malfunctioning node, and to add a new node. Network clients continue to see a single computer system.

A cluster is similar to a general distributed system, except that it provides these additional capabilities:

  1. Every node has full connectivity and communication with the other nodes in the cluster through the following:
    • One or more shared SCSI buses for storage. Each shared SCSI bus attaches one or more disks that hold data used to manage the cluster. Cluster Server provides a dual-access storage model whereby multiple systems in the cluster can access the same storage.
    • A private network, or interconnect, that carries only internal cluster communication. Private networks are recommended, but not required.
    • One or more public networks. Public networks serve as backup for a private network and can be used both for internal cluster communication and to host client applications. Network adapters, known to the cluster as network interfaces, attach nodes to networks.
  2. Every node in the cluster is aware when another system joins or leaves the cluster.
  3. 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.

Networks, network interfaces, nodes, and resources are four of six components that applications and network administrators work with when they program for or use Cluster Server. There are also cluster groups and resource types. Each of the Cluster Server components is associated with:

  • A set of operations that is made available through the Cluster API, the Resource API, the Cluster Utility functions, or the Cluster Administrator Extension API.
  • Data that is stored in the cluster database and accessed through specific functions in the Cluster API.

The following table briefly describes the Cluster Server components:

Cluster Server object | Description
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 Cluster Server, and can be started, stopped, and moved to another node.
Resource type | A category of resources, such as physical disks.
Group | A collection of resources that run together on a node and are failed over as a single unit.


Cluster Server Architecture

The Cluster Server architecture is made up of the following software components:

  • Cluster Service
  • Cluster Network Driver
  • Cluster Administrator
  • One or more Resource Monitors
  • One or more resource DLLs

The Cluster Service is the 'brains' of a cluster. There is one instance of Cluster Service running on every node in a cluster. The Cluster Service manages resources and coordinates with other instances of the Cluster Service in the cluster. The Cluster API is used by applications and resources to interact with the Cluster Service. The Cluster API allows applications and resources to manage cluster components and to access the cluster database.

The Cluster Network Driver provides highly available communication between cluster nodes and helps to maintain cluster membership. The Cluster Network Driver maintains configuration information provided by the Cluster Service and communicates with the other nodes in the cluster. When a communication failure is detected, the Cluster Network Driver notifies the Cluster Service.

Resource Monitors act as an interface between the Cluster Service and cluster resources. Each resource is exposed by a dynamic link library (DLL) that is loaded into the Resource Monitor process. Resource Monitors isolate the Cluster Service from failures in a resource DLL. Multiple Resource Monitors can be used to isolate resources from one another.

Resource DLLs are used to manage cluster resources of a particular type. Each resource DLL is written to manage one or more resource types. When the Cluster Service issues a request to a resource, that request is passed to the Resource Monitor. The Resource Monitor in turn calls an entry point function in the resource DLL responsible for the resource. The entry point functions are part of the Resource API. When a resource DLL is loaded, it passes a table to the Resource Monitor containing pointers to each of these functions.

Cluster Server provides resource DLLs for the resource types that it supports, such as the IP Address and Physical Disk resources. However, a cluster is not limited to these resource types. Third-party developers can create their own resource DLLs to replace or augment Cluster Server's resource DLLs. For a conceptual overview of resources, see About Cluster Resources.

Every node in a cluster can own one or more groups consisting of dependent or related resources. Administrators use a graphical application known as Cluster Administrator to establish and configure these resource groups and other cluster objects and to initiate failover, handle maintenance, and monitor cluster activity. Any Microsoft® Windows NT® system, regardless of whether it is a cluster node, can install Cluster Administrator.

Cluster Administrator allows administrators to view, add, and change resources belonging to any of the resource types defined by Cluster Server. Third-party developers providing their own resource types can write an extension that enables Cluster Administrator to manage their custom types.

The following diagram shows how these Cluster Server components relate to applications of various types and to each other within a single Windows NT Server network operating system.

The diagram shows three types of applications:

  • Cluster management
  • Cluster-aware
  • Cluster-unaware

Cluster management applications are used to administer clusters, to perform such tasks as adding resources, changing the membership of groups, and moving a group from one node to another. One example of a cluster management application is Cluster Administrator; another is a command line tool also provided with Cluster Server called CLUSTER.EXE. Administrators can use these applications to configure their cluster and establish resource dependencies and failover policies, but not to add a node to a cluster. A node can only be added to a new or existing cluster when the node installs Cluster Server. Cluster management applications use the Cluster API to communicate with the Cluster Service.

Both cluster-aware and cluster-unaware applications run on a cluster node and can be managed as cluster resources. However, only cluster-aware applications can take advantage of features offered by Cluster Server through the Cluster API. For example, cluster-aware applications can:

  • Report status upon request to the Resource Monitor.
  • Respond to requests to be brought online or taken offline gracefully.

A cluster-aware application is typically managed by the Cluster Service as a custom resource type, a resource type created by a third-party developer responsible for the application. To create a custom resource type, a developer provides two DLLs: a resource DLL and a Cluster Administrator extension DLL. The Cluster Administrator extension DLL implements methods included in the Cluster Administrator extension API.

A cluster-unaware application is typically managed as a Generic Application resource, one of the resource types defined by Cluster Server. Generic Application resources can be administered with Cluster Administrator and can be failed over to an alternate node when a failure occurs. Cluster-unaware applications do not communicate directly with the Cluster Service through the Cluster API.


Cluster Service

The Cluster Service is a Microsoft® Windows NT® service used to control cluster activities. The Cluster Service performs such tasks as coordinating event notification, facilitating communication between other software components, handling failover operations, and managing configuration.

The Cluster Service is made up of several closely-related pieces called managers. The following table describes the function of each Cluster Service manager:

Manager | Description
Checkpoint Manager | Responsible for saving data from the cluster database or from other portions of the system registry to files maintained on the quorum resource.
Database Manager | Controls access to the cluster database.
Event Log Manager | Replicates the Windows NT event log records across the nodes of a cluster. The Windows NT Event Viewer attached to any one of the nodes can be used to view cluster events.
Failover Manager | Handles the transferring of groups of resources from one node to another in response to a request from the Resource Manager. Works with the Resource Manager to manage resource dependencies and start and stop resources.
Global Update Manager | Provides update services to the cluster nodes, enabling the Database Manager to ensure that related changes to the cluster database take place consistently across the cluster. All changes to the cluster configuration and to its state are applied using the Global Update Manager.
Log Manager | Writes changes to the recovery log stored on the quorum resource when any of the cluster nodes are down. Takes checkpoints at appropriate moments, thereby helping to ensure that the local cluster databases are kept consistent across the cluster. Handles a partition in time, a situation that occurs when cluster nodes are not online at the same time.
Membership Manager | Works with the Node Manager and the Cluster Network Driver to maintain cluster membership and to provide membership information to other components in the Cluster Service. Keeps track of the nodes that are currently active members of the cluster and nodes that are configured as members but not active.
Node Manager | Maintains all node and network configuration and state information. Controls operation of the Cluster Network Driver.
Resource Manager | Initiates the transfer of cluster groups to alternate nodes by sending a failover request to the Failover Manager. Determines how ownership of the groups should be redistributed.


Cluster Network Driver

The Cluster Network Driver, CLUSNET.SYS, is a software component that is responsible for:

  • Providing highly available communication by monitoring the status of all network paths between nodes and routing messages over the path determined to be the best.
  • Detecting the failure of a node by maintaining communication between nodes through the use of periodic messages called heartbeats.

Heartbeats are sent to every node in the cluster and are also exchanged over all network paths between nodes. They are used to monitor the health of a network link and to detect node failure. If a node fails to respond to a heartbeat message or voluntarily leaves the cluster, the Cluster Network Driver notifies the Membership Manager and Node Manager. These Cluster Service components initiate an operation known as regrouping to take the inactive node offline and cancel its membership in the cluster. When the Failover Managers on the surviving nodes learn that a node has failed, they cooperate to redistribute any groups that were hosted by that node.


Cluster Networks

Cluster Server relies on the availability of a network path to ensure that the nodes of a cluster can communicate. If one network fails, another network must be able to take its place. Therefore, maintaining accurate information about network topology is critical.

Cluster Server maintains configuration information about network topology not only to store data about all of the networks that are available to the cluster, but also to keep track of the particular network or networks that are currently being used and to properly configure IP Address resources.

Cluster Server views networks as serving one of the following roles:

  1. Carrying internal cluster communication.
  2. Providing client systems with access to cluster application services.
  3. Carrying internal cluster communication and connecting client systems to cluster application services.
  4. Carrying traffic unrelated to cluster operation.

Internal cluster communication implies cluster control messages. IP Address resources are created on networks that provide clients with access to cluster services.

Cluster Server authenticates all internal communication, but those sites that are particularly concerned about security may wish to restrict internal communication to physically secure networks.

The following diagram provides an example of these four roles. The key below the diagram lists the values that are stored in a network's Role property. The private network, or Interconnect, is used only for internal communication between the cluster nodes. The Internet, due to its widespread usage, is only used to connect client systems to the cluster. The 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, Cluster Server attaches to every available network, storing property information for each in the cluster database. However, an administrator can prevent the Cluster Service from attaching to a network by assigning the value ClusterNetworkRoleNone to its Role property. Only the first three roles identify a network as one that should be utilized by the Cluster Service.

Networks used by the Cluster Service expose their behavior through Cluster API functions. One of the functions, ClusterNetworkControl, is used to initiate a variety of operations. The operations are defined by a set of control codes. Several of the operations involve accessing network data stored in the cluster database.


Cluster Nodes

A cluster node is a Microsoft® Windows NT® Server system that has a working installation of Microsoft® Cluster Server. A node can be an active or inactive member of a cluster, depending on whether or not it is currently online and in communication with the other cluster nodes. An active node can act as host to one or more cluster groups.

When an administrator installs Cluster Server, a choice must be made as to whether the system should form its own cluster or join an existing cluster. After installation is complete, the node will always attempt to join an existing cluster whenever it is restarted. To join the existing cluster, Cluster Server validates the node's name, password, and cluster database. Active membership is restored if the name and password are valid and consistency exists between this cluster database and the cluster databases residing on the other nodes in the cluster.

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. The quorum resource is the resource, typically a disk, that stores the cluster's recovery logs. The recovery logs are used by the Cluster Service to keep the cluster databases residing on each cluster node consistent. If access is granted, the node verifies whether or not its cluster database has the same information as the recovery logs. After the cluster database and recovery logs are synchronized, a new cluster is able to form.


Resource Monitor

The Resource Monitor is a Cluster Server component that acts as a intermediary between the Cluster Service and a resource DLL. When the Cluster Service makes a request of a resource, the Resource Monitor transfers that request to the appropriate resource DLL. When a resource DLL must report status or notify the Cluster Service of an event, the Resource Monitor ensures that the information is delivered successfully. Resource Monitors do not make decisions or set policy.

The Resource Monitor runs in a process separate from that of the Cluster Service for two reasons:

  • To protect the Cluster Service from resource failures.
  • To allow the Resource Monitor to take action if the Cluster Service fails. The Resource Monitor detects Cluster Service failure and responds by taking all of the resources and groups on the affected node offline.

Every cluster node runs one or more Resource Monitors. By default, the Cluster Service starts only one Resource Monitor to interact with all of the resources hosted by the node. However, this default can be overridden either by an administrator using Cluster Administrator or another management application or by the developer of a custom resource type. It is recommended that potentially problematic resource DLLs be assigned their own Resource Monitor, thereby preventing faulty behavior from affecting other resources and other Resource Monitors.

Each Resource Monitor on a node has threads for polling the status of the resources for which it is responsible. Currently, the Resource Monitor creates one polling thread for every 16 resources.


Cluster 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 by only one node at a time.
  • It can be moved between nodes.

Resources are managed in the cluster environment through communication between the Cluster Service through a Resource Monitor to a resource DLL, a mainly passive translation layer that implements entry point functions defined by the Resource API. In response to a Cluster Service request, the Resource Monitor calls the appropriate entry point function to check and control the resource's state.

A resource DLL is loaded into the Resource Monitor's process, runs in the system account, and must be considered privileged code. All of the resource DLLs provided with Cluster Server run in a single process. Resource DLLs can use any convenient interprocess communication mechanism to interact with their resources.

Cluster resources maintain pieces of information known as properties. There are common resource properties that describe all resources regardless of their type and private resource properties that describe resources of a particular type. The local restart policy, defining the desired actions in the event that the resource cannot continue on the current node, is an example of a common property. The signature of a Physical Disk resource is an example of a private property because it is irrelevant for other types of resources. Common properties are stored in the cluster database; private properties can be stored in the cluster database, in an alternate location, or generated on demand.

Cluster resources also maintain a list of nodes that can act as valid hosts. For example, a Physical Disk resource may be hosted only on nodes that are physically connected to the resource. Applications can retrieve this list by calling ClusterResourceEnum and passing CLUSTER_RESOURCE_ENUM_NODES as the dwType parameter.

To interact with a cluster resource, applications and the Cluster Service call the Cluster API function ClusterResourceControl and specify as a parameter a control code. A control code is a 32-bit value that describes a particular operation. Some of the operations associated with resource control codes are supported by the resource DLL; others are supported by the associated Resource Monitor.


Resource Types

Cluster resources are organized by type. Resource types are associated with a set of control codes. The control codes describe operations that all resource types can perform, such as returning or updating property values. To invoke a particular operation, applications call the Cluster API function ClusterResourceTypeControl and pass the control code that represents the specific operation.

Resource types are also associated with a set of properties, or attributes. There are common properties, or attributes that apply to all resource types, and private properties, or attributes that apply only to resources of a particular type. Only some resource types define private properties.

Cluster Server defines several types of resources and provides resource DLLs to manage those 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, a developer can have more control over how Cluster Server manages his or her application or service.

The following types of resources are defined by Cluster Server:

  • Distributed Transaction Coordinator (DTC)
  • Generic Application
  • Generic Service
  • Physical Disk
  • Print Spooler
  • File Share
  • IP Address
  • Internet Information Server (IIS) Virtual Root
  • Message Queue
  • Network Name
  • Time Service

The Distributed Transaction Coordinator (DTC) resource type supports the Distributed Transaction Coordinator, Microsoft's transaction manager. Every DTC resource has a required dependency on both a Network Name resource and a storage class device.

There can only be one DTC resource residing on each node. There are no private properties associated with the DTC resource type.

The Generic Application resource type is used to provide basic management of cluster-unaware applications. The Generic Application resource type can also be used to manage cluster-aware applications that are not associated with custom resource types. Generic Application resources have very crude failure detection and are taken offline by terminating the process. To query for failure, the resource DLL merely determines whether the process still exists. Generic Application resources maintain several private properties such as the command line for running the application and a reference directory.

The Generic Service resource type manages Microsoft® Windows NT® 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 Service Controller. If the service is running, it is presumed to be online. To provide greater functionality, a custom resource type should be defined. Generic Service resources maintain three private properties: a set of startup parameters, the name of the service, and a value that affects the name of the node on which the service is running.

The Physical Disk resource type describes a shared disk connected to two or more nodes in a cluster. In a typical cluster, the Physical Disk is included as a dependency for resources of various other types. Physical Disk resources are the only type of resource defined by Cluster Server that can operate as a cluster's quorum resource. Physical Disks maintain two private properties: the disk signature and a drive designator. These properties are used to identify the resource. Only one property is required; a Physical Disk resource must set either the disk signature or the drive designator.

The Print Spooler resource type describes a network printer that applications access using a network IP address rather than an individual name. Every group can have only a single Print Spooler resource. Print Spooler resources maintain two private properties: a default spool directory and a time-out value.

The File Share resource type is used to manage a file share that applications can access using a network path. File Share resources maintain several private properties, some that are required and some that are optional. The required properties include a share name and the path to the resource.

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. To configure an IP Address resource, administrators provide values for its private properties. An IP Address resource's private properties consist of the address, subnet mask, and network name.

The IIS Virtual Root resource type manages Microsoft® Internet Information Server (IIS) virtual roots that support the WWW, FTP, and GOPHER services. IIS Virtual Root resources are closely tied to other Cluster Server resources, namely IP Address resources, Network Name resources, and Physical Disk resources. The private properties of the IIS Virtual Root resource type include the physical location of the resource, security information, an alias for client access, and the name of the related Web service.

The Message Queue resource supports the Microsoft® Message Queue Server (MSMQ). This resource depends on a Network Name resource and a Distributed Transaction Coordinator (DTC) resource. Only one Message Queue resource can be running on a node at any point in time. Message Queue resources do not maintain any private properties.

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 it to be accessed by network clients as a virtual server. Network Name resources maintain one private property: the name of the resource.

The Time Service resource type ensures that time remains synchronized across all nodes within a cluster. The Time Service is a special resource type unlike the other types. One node is selected automatically to host the Time Service resource and to provide the correct time to the other nodes in the cluster. The selected node is posted in the cluster database. If an alternate node must be used, the Time Service is stopped and restarted so that time is kept consistent across all members of the cluster. The Time Service does not maintain any private properties.


Cluster Groups

Cluster resources are associated with a group, a collection of cluster resources that define the unit of failover. Any cluster operation performed on a group is performed on all resources contained within the group. That is, when one resource in the 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.

To fully exploit the processing power of a cluster, administrators should establish at least as many groups as there are nodes in the cluster. The group concept allows resources to be combined into larger logical units. Although groups are typically formed from related or dependent resources, groups can also be established with resources that are unrelated and nondependent to balance the load or for administrative convenience. A dependent resource is one that relies on another resource to operate. Dependent resources are taken offline before the resources upon which they depend are taken offline and brought online after these resources are brought online.

Typically a group is made up of an application and all of its related peripherals, such as an application and its associated peripherals and data. When a group includes a Network Name resource and an IP Address resource, the group can be referred to as a virtual server. The term virtual server relates to the way that network clients view their access to the services associated with the resources in the group. These clients appear to be connecting to a physical server when in reality they are connecting to a group of related resources running on any of the nodes in the cluster, a virtual server.

Every group maintains several common properties in the cluster database that describe the group and dictate how and when the failover and failback processes should occur. In addition, every group maintains a list of the nodes that can act and should act as its host. The list of preferred nodes for a group is computed from the lists maintained by the resources that are members of the group. This list is made up of two pieces of information:

  • Node(s) on which the group or resource prefers to run.
  • Node(s) that the group or resource prefers to move to during a failover.

To interact with a group, an application specifies one of the group control codes as a parameter to the Cluster API function ClusterGroupControl. The control codes describe group operations such as getting and setting common properties or retrieving characteristics. For more information about operations that are available through ClusterGroupControl, see Control Codes for Groups.


Quorum Resource

The quorum resource plays a crucial role in the operation of the cluster. In every cluster, a single resource is designated as the quorum resource. A quorum resource can be any resource with the following attributes:

  • Must offer a means of persistent arbitration. Persistent arbitration means that the quorum resource must allow a single node to gain physical control of it and defend its control. For example, SCSI disks can use their Reserve and Release commands for persistent arbitration.
  • Must provide physical storage that can be accessed by any node in the cluster. The quorum resource stores data that is critical to recovery when there is a communication failure between a cluster's nodes.

The quorum resource is used to guarantee that only one set of active, communicating nodes operate as the cluster, acting as a tie-breaker in the unlikely event that cluster nodes are running, but cannot communicate. To maintain a cluster's membership, the Cluster Service relies on the frequent, timely exchange of messages with its peers on other nodes. Although unlikely, it is possible for a failure to occur of all possible networks connecting the cluster nodes. Such a failure could cause the cluster to divide into two or more sets of active nodes that can communicate within the set but not between sets. Each set would assume that nodes in the other sets have failed and attempt to take control of their resources. To prevent this scenario, the node that gains access to the quorum resource is the node that is granted the ability to form the cluster.

The quorum resource maintains access to the most current version of the cluster database and to essential recovery data. When a cluster node fails, changes to the cluster database are written to the quorum resource. To realize the importance of this function, consider the situation where Node2 in a two-node cluster fails. If Node1 goes down before Node2 is brought back online, Node2 must gain control of the quorum resource to be made aware of Node1's changes. Node2 must update its private copy of the cluster database with the changes from the recovery log maintained by the quorum resource. When the quorum resource is out of disk space, all changes to the cluster database are prevented.

Whenever a node attempts to form a cluster, it first tries to gain control of the quorum resource. As other nodes join the cluster, control of the quorum resource can be traded among them, as long as they remain in communication. If communication with the node that controls the quorum resource fails, then the surviving nodes must arbitrate for control. The node that gains control of the quorum resource and the nodes with which the controlling node can communicate will continue to operate as the cluster. Nodes that were previously active and now cannot communicate release all of their resources and halt operation immediately.

The only type of resource defined by Cluster Server that can act as a quorum resource is currently the Physical Disk. However, third-party developers can create their own resource types to be quorum resources as long as they are able to perform arbitration and act as storage devices. It is recommended that clusters use a stripe set of disks.


Introduction to Cluster Server Programming

As a programmer using the Cluster Server SDK, you may perform one or more of the following tasks:

  • Create a new cluster-aware application.
  • Add cluster-awareness to an existing application.
  • Create a custom resource type by building a resource DLL to allow Cluster Server to manage your application or service as a cluster resource.
  • Create a cluster management application.
  • Create a Cluster Administrator extension DLL to allow Cluster Administrator to handle your custom resource type.
  • Create a setup program to install, configure, and register a resource DLL and/or a Cluster Administrator extension DLL.

A cluster-aware application is any application that runs on a cluster node and is managed and administered as a cluster resource. A cluster-aware application is aware of its environment and is designed to take advantage of the features that clustering offers. When a cluster-aware application detects that it is running on a cluster node, it provides special functionality or performs additional tasks made available through the Cluster API.

Most applications can be made cluster-aware. Only applications that do not use TCP/IP as a network protocol, maintain data in a configurable location, or support transaction processing cannot be made cluster-aware. Typical cluster-aware applications include database applications, transaction processing applications, file and print server applications, and other groupware applications.

Although it is possible to use the resource DLLs provided by Cluster Server to manage your cluster-aware application, it is recommended that you create your own. By creating a resource type that fits your specific needs, you can have more control and flexibility in how Cluster Server handles your application. Creating a custom resource type enables the Resource Monitor to manage your application in ways that are specific to the application.

To create a custom resource type, you build a resource DLL using the Resource API and, as an option, a DLL to allow Cluster Administrator to include property sheets for your application. The resource DLL contains implementations of entry point functions defined in the Resource API for handling the communication between the application and the Resource Monitor. The Cluster Administrator extension DLL uses the interface methods of the Cluster Administrator Extension API to allow the application to be administered with Cluster Administrator. Providing a Cluster Administrator extension DLL simplifies the job of the network administrator; it enables him or her to work with your application, its dependent resources, and any other standard resources using an integrated, consistent user interface.

You can also create a cluster management application with the Cluster Server SDK. A cluster management application is an application written specifically to manage one or more clusters. Cluster management applications can typically run locally on one of the cluster nodes or remotely on a non-clustered system. Cluster Administrator is an example of a cluster management application as is the command-line tool, CLUSTER.EXE. If you need to create your own cluster management application that runs as a stand-alone application or in conjunction with Cluster Administrator, you can do so using the Cluster API.

Although Cluster Server programming applies primarily to cluster-aware and cluster management applications, Cluster Server supports a third type of application, the cluster-unaware application. A cluster-unaware application resembles a cluster-aware application in that both run on a cluster node and are managed and administered as cluster resources. The difference between applications that are cluster-aware and those that are not is in their knowledge of their environment. A cluster-unaware application has no inherent knowledge of its existence in a cluster; its functionality is the same regardless of whether or not it is running in a cluster. Cluster-unaware applications are typically managed as Generic Application or Generic Service resources, but it is possible to also manage them as custom resource types.


Installing the Microsoft Cluster Server SDK

The Microsoft® Cluster Server SDK supports Microsoft Developer Studio™ for Visual C++ version 4.2 and Microsoft Visual Studio™ for Visual C++ version 5.0. The steps for installation are slightly different depending on the development environment you elect to use.

To install the Microsoft Cluster Server SDK
  1. Install Microsoft Windows NT® Server network operating system version 4.0 with Service Pack 3.
  2. Install Microsoft Cluster Server, selecting either Form a New Cluster if your development machine is the first member of the cluster, or Join an Existing Cluster if another machine has already established the cluster. When asked, specify a disk on the shared SCSI bus to use as the quorum resource.

    Although it is possible to create cluster-aware applications and DLLs on a non-clustered system, keep in mind that you will be need a two-machine cluster for testing. Two nodes are needed to successfully test failover. Therefore, it makes sense to do your development on a machine that is a member of an active cluster.

    For more information about the installation process, see the Microsoft Cluster Server Administrator's Guide.

  3. Verify that you have either Microsoft Visual C++® version 4.2 or version 5.0 with the Unicode MFC libraries and the MIDL compiler version 3.00.44 or greater. The MIDL compiler is available with the Microsoft Platform SDK.
  4. If you have Visual C++ version 4.2, download the Visual C++ 4.2b Technology Update from the Downloads and Patches area of the Visual C++ home page on the web located at http://www.microsoft.com/visualc.
  5. If you have Visual C++ version 4.2, install the Active Template Library (ATL) version 2.0 or greater. With Visual C++ version 5, ATL 2.1 is included.
  6. If you will be programming in Microsoft Visual Basic®, verify that you have Microsoft Visual Basic version 4.0 or greater on your machine.
  7. Install the Cluster Server SDK by running the SETUPSDK.EXE program from the SDK directory of the installation CD. The SETUPSDK program will ask for the location of the root directory of your Microsoft Visual C++ development environment and place its files in the appropriate subdirectory.

    The Cluster Server SDK contains header files, libraries, interface definition languages files, and sample code. It also contains a custom Resource Type AppWizard, accessible through the development environment of Microsoft Visual C++, that creates skeleton versions of resource and Cluster Administrator extension DLLs.

When you have finished installing, you will notice that:

  • Files that support the Cluster Service have been placed in the cluster subdirectory of your system directory.
  • Files that you will use for Cluster Server programming have been placed in directories under the root directory of your Visual C++ development environment.
  • Cluster Administrator is now available from the Start menu.

The following table describes the SDK files that are added to directories in your Visual C++ version 4.2 development environment:

Directory | Cluster Server SDK File
BIN | Cluster Administrator extension registration program (REGCLADM.EXE).
HELP | Documentation files (MCMSDK files).
INCLUDE | CLUSAPI.H, RESAPI.H, CLUADMEX.H, CLUADMEX.IDL, and MSCLUS.IDL.
LIB | CLUADMEX, CLUSAPI, and RESUTILS libraries and the MSCLUS type library.
SAMPLES | SmbSmp is a resource DLL, written in C. SmbSmpEx is a Cluster Administrator extension DLL for a File Share resource, written in C++.
TEMPLATE | Resource Type AppWizard (RESTYPAW.DLL).

The following table describes the SDK files that are added to directories in your Visual C++ version 5.0 development environment:

Directory | Cluster Server SDK File
BIN | Cluster Administrator extension registration program (REGCLADM.EXE).
HELP | Documentation files (MCMSDK files).
INCLUDE | CLUSAPI.H, RESAPI.H, CLUADMEX.H, CLUADMEX.IDL, and MSCLUS.IDL.
LIB | CLUADMEX, CLUSAPI, and RESUTILS libraries and the MSCLUS type library.
SAMPLES | SmbSmp is a resource DLL, written in C. SmbSmpEx is a Cluster Administrator extension DLL for a File Share resource, written in C++.
SharedIDE | Resource Type AppWizard (RESTYPAW.DLL).

SmbSmp and SmbSmpEx demonstrate how to write a basic resource DLL and a Cluster Administrator extension DLL, respectively. The sample directories contain the source code and all other supporting files needed to build these DLLs. Because these samples manage the same resource type, they are stored in a single workspace and use a single makefile.

Another sample, DebugEx, is installed in the cluster directory of your system directory, typically C:\WINNT\CLUSTER. DebugEx is a Cluster Administrator extension that you can use to debug your resource DLL. To set up DebugEx, specify the debugger that you wish to use. If the resource is configured to run in its own Resource Monitor, the Cluster Service will attach the specified debugger to the Resource Monitor for that resource after it has started but before any entry points in the resource DLL have been called. The common resource property, DebugPrefix, holds the path to the debugger that will be attached to the Resource Monitor for the resource.


Suggested Background Reading

To supplement your understanding of how Microsoft® Cluster Server works with applications before you begin programming, read In Search of Clusters by Gregory F. Pfister, ISBN: 0-13-437625-0. In Search of Clusters offers an excellent introduction to clustering technology including a description of the common programming models.

For an overview of Cluster Server concepts and components, read Cluster Server Concepts and Architecture. This topic discusses the clustering model employed by Cluster Server and the software components responsible for implementing the model.

If you will be creating a new resource type, read the Microsoft Cluster Server Administrator's Guide and become well-versed in using Cluster Administrator. The Administrator's Guide describes how administrators expect to interact with new types of resources, thereby helping you to create DLLs that conform to those expectations. Because most administrators will be using Cluster Administrator for this interaction, resource type developers typically write an extension to this application to handle their new resource types. Understanding Cluster Administrator's design is critical to producing a high quality extension.

If you plan to use the Cluster Automation Server, you should be familiar with Component Object Model (COM) and Automation. See the "COM and ActiveX Object Services" section of the Microsoft Platform SDK for information on these topics.

The reference sections of the Cluster Server SDK provide syntax and return codes, as well as directions on how and when to use particular functions, methods, structures, properties, and control codes.


Background Reading: Creating a Resource DLL

To create a resource DLL for a new resource type
  1. See Using the Resource Type AppWizard to learn how to create a skeletal version of a resource DLL.
  2. See Common Resource Properties to determine how to use the information that is relevant to all cluster resources.
  3. If your resource type is based on an existing resource type, the discussion of the private properties for the Cluster Server resource types in Private Resource Properties should prove helpful.
  4. Start to supplement the source produced by the Resource Type AppWizard by reading Customizing a Resource DLL. This topic provides hints as to where additional functionality is typically needed.
  5. Use the Resource API documentation to learn how to further supplement your resource DLL. The descriptions in the Resource API will help you determine if you need to implement optional entry point functions and how and when to make calls to the Resource Monitor. For example, a resource DLL that handles quorum resources has unique requirements. In addition to implementing the standard functions and calling the standard callbacks, quorum resources must implement the Arbitrate and Release entry point functions and make calls to the QuorumResourceLost callback.
  6. Study the Control Codes for Resources to determine which of the many control codes your ResourceControl entry point function should support and to determine how to implement that support.
  7. Become familiar with the utility functions that are available for manipulating property lists by referring to Property List Utility Functions.
  8. Refer to the relevant portions of the Cluster API for making calls to the Cluster Service:

    Cluster Management Functions discusses functions for accessing the cluster as a whole.

    Node Management Functions discusses functions for accessing cluster nodes.

    Group Management Functions discusses functions for accessing cluster groups.

    Resource Management Functions discusses functions for accessing resources.

    Cluster Database Management Functions discusses functions for accessing the cluster database.

  9. When you are ready to test, refer to Registering a Resource DLL to help with registration and Debugging a Resource DLL to help with debugging.


Background Reading: Creating a Cluster Administrator Extension DLL

Creating a Cluster Administrator extension DLL involves implementing some of the methods from the Cluster Administrator Extension API and make calls to others. Whereas the Resource API is made up of standard functions, the Cluster Administrator Extension API is a COM-based API consisting of interfaces. Therefore, before concentrating on tasks specific to Cluster Administrator extensions, it is wise to become familiar with the COM programming model. For information on COM, see the "COM and ActiveX Object Services" section in the Microsoft Platform SDK.

Also, if you use the Resource Type AppWizard to begin development, you will notice that the code it produces uses the Microsoft Foundation Classes (MFC) and C++ language. If you are not an experienced MFC user, it is recommended that you take some time to read the documentation included with Microsoft Visual C++® development system.

To create a Cluster Administrator extension DLL
  1. See Using the Resource Type AppWizard to learn how to create a skeletal version of a Cluster Administrator extension DLL.
  2. See Common Resource Properties to determine how to use the information that is relevant to all cluster resources.
  3. If the resource type to be administered by your extension is based on an existing resource type, the discussion of the private properties for the Cluster Server resource types in Private Resource Properties should prove helpful.
  4. Use the Cluster Administrator Extension API to learn how to further supplement your Cluster Administrator extension DLL. The descriptions in the API reference will help you determine which of the interfaces you will need to implement and why and how you should implement them. It also describes when and how to make calls to Cluster Administrator.
  5. Use the Cluster Structures reference to learn how to store various properties and other information that you might want to expose in your Cluster Administrator extension property sheet.
  6. Refer to the relevant portions of the Cluster API for making calls to the Cluster Service:

    Cluster Management Functions discusses functions for accessing the cluster as a whole.

    Node Management Functions discusses functions for accessing cluster nodes.

    Group Management Functions discusses functions for accessing cluster groups.

    Resource Management Functions discusses functions for accessing resources.

    Cluster Database Management Functions discusses functions for accessing the cluster database.

  7. When you are ready to test, refer to Registering a Cluster Administrator Extension DLL to help with registration and Debugging a Cluster Administrator Extension DLL to help with debugging.


Background Reading: Creating a Cluster-Aware Application

A cluster-aware application includes calls to the Cluster Service using the Cluster API. The Cluster API allows an application to retrieve information about cluster objects, to initiate operations, and to update information in the cluster database.

To create a cluster-aware application
  1. Gain a thorough understanding of Cluster Control Codes. The cluster control codes allow you to call one of four Cluster API functions to perform a multitude of different operations. Whereas most of the Cluster API functions are designed to perform a single task, ClusterResourceControl, ClusterResourceTypeControl, ClusterGroupControl, and ClusterNodeControl are designed to perform any task that is represented by a control code.
  2. Use the Cluster Structures reference to learn how to parse the structures that hold properties and other information.
  3. Refer to the relevant portions of the Cluster API for making calls to the Cluster Service:

    Cluster Management Functions discusses functions for accessing the cluster as a whole.

    Node Management Functions discusses functions for accessing cluster nodes.

    Group Management Functions discusses functions for accessing cluster groups.

    Resource Management Functions discusses functions for accessing resources.

    Cluster Database Management Functions discusses functions for accessing the cluster database.

  4. Read Using the Cluster Database to understand the purpose and structure of the cluster database and to discover how to access it.


Background Reading: Creating a Cluster Management Application

You can create a cluster management application using C, C++, Microsoft Visual Basic or a scripting language. What you choose to read before beginning to code depends on your choice of language. If you are using C or C++, you will be working with the Cluster API to manipulate data. If you are using Visual Basic or a scripting language, you will be working with the Cluster Automation Server.

To create a cluster management application with C or C++
  1. Become familiar with the common properties of resources, resource types, nodes, and groups through the relevant sections in the SDK:
    • Common Resource Properties describe properties that apply to all resources.
    • Common Resource Type Properties describe properties that apply to all resource types.
    • Common Group Properties describe properties that apply to all groups.
    • Common Node Properties describe properties that apply to all nodes.
  2. Become familiar with the private properties of resources associated with the Cluster Server resource types by reading Private Resource Properties.
  3. Use the Cluster Structures reference to learn how structures are used to store properties and other cluster-related information.
  4. Refer to the relevant portions of the Cluster API for making calls to the Cluster Service:

    Cluster Management Functions discusses functions for accessing the cluster as a whole.

    Node Management Functions discusses functions for accessing cluster nodes.

    Group Management Functions discusses functions for accessing cluster groups.

    Resource Management Functions discusses functions for accessing resources.

    Cluster Database Management Functions discusses functions for accessing the cluster database.

To create a cluster management application with Visual Basic or a scripting language
  1. Learn about the Component Object Model (COM) and Automation if you are unfamiliar with these technologies. See the "COM and ActiveX Object Services" section of the Microsoft Platform SDK for information on these technologies, or read Inside COM by Dale Rogerson, which is available through Microsoft Press.
  2. Refer to the relevant portions of the Cluster Automation Server reference to learn about the programmable objects that are available and their properties and methods.


Preparing to Use Visual Basic

The Microsoft® Cluster Automation Server allows you to create instances of programmable objects that you can access with an application or tool that supports Automation, such as Microsoft Visual Basic®. Programmable objects expose properties that can be retrieved and updated and methods that can be invoked.through Visual Basic. The programmable objects provided by Cluster Server expose properties and methods that are specific to cluster management.

To prepare your environment for using the Cluster Automation Server with Visual Basic
  1. Install Microsoft Visual Basic version 4.0 or 5.0.
  2. Install the Microsoft Cluster Server SDK.
  3. Register MSCLUS.DLL, the dynamic link library that contains the Cluster Automation Server. Typically this registration is taken care of when you install the SDK. However, if you need to manually register MSCLUS.DLL, use the system registry program REGSVR32.

To test your environment, launch Visual Basic and choose References from the Projects menu. If MSCLUS.DLL has been registered properly, it will appear in the list of components as "MS Cluster 1.0 Type Library." Click the check box next to this item in the list to enable the Visual Basic Object Browser to include the programmable cluster objects. You will now be able to allocate instances of these objects, call their methods, and retrieve as well as set their properties.


Using the Cluster Database

The cluster database is part of the Microsoft® Windows NT® registry that is resident on each cluster node. It contains information about all physical and logical elements in a cluster.

The following table lists the keys under which cluster data is stored:

Cluster Database Key | Type of Stored Data
Cluster\Parameters\Groups | Information about cluster groups.
Cluster\Parameters\Nodes | Information about cluster nodes.
Cluster\Parameters\Quorum | Information about the quorum resource.
Cluster\Parameters\Resources | Information about cluster resources.
Cluster\Parameters\ResourceTypes | Information about resource types.

The following data shows an excerpt from the information stored in the cluster database for Cluster Server's Physical Disk resource type:

Physical Disk
    AdminExtensions : REG_MULTI_SZ : {4EC90FB0-D0BB-11CF-B5EF-00A0C90AB505}
    DllName : REG_SZ : clusres.dll
    IsAlivePollInterval : REG_DWORD : 0xea60
    LooksAlivePollInterval : REG_DWORD : 0x1388
    Name : REG_SZ : Physical Disk

Much of the information that is stored in the cluster database is property information. For the Physical Disk resource type, AdminExtensions, DllName, IsAlivePollInterval, LooksAlivePollInterval, and Name are all common properties. The entries are in order by property name, followed by type and value.

Individual resources often store both common and private property information in the cluster database. Whereas common properties apply to all resources regardless of their type, private properties apply only to resources of a specific type. For example, an IP Address resource requires an address, network name, and subnet mask while a Physical Disk resource requires a signature.

Resources and groups store their key name as a GUID. This is the unique identifier for the resource or group. Groups store the following pieces of information in the cluster database:

  • List of GUID values that identify resources that are members of the group.
  • Name of the group such as Cluster Group or Disk Group.
  • Numeric constant that indicates the group's operational status.

Cluster-aware applications should use the cluster database exclusively for saving state and property information; they should not use the system registry. Using the cluster database makes it easier to manage and administer the cluster and allows a resource's configuration for a specific node to be modified even when the node is offline.

However, it is possible for a cluster-unaware application to use the system registry to store important information. In the event that the application is moved, it would be essential to maintain access to this information. The Cluster API includes a feature known as registry checkpointing to insure the availability of information stored on a tree in the system registry. The application establishes a registry checkpoint by calling ClusterResourceControl with the CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code. Whenever anything changes on the checkpointed registry tree and the application is online, the Cluster Service stores a copy of the tree in the quorum resource's log file. If the application moves to another node, the Cluster Service restores the registry tree from the log file to the system registry on the new node.

To access information in the cluster database, applications should use the control code functions in the Cluster API whenever possible. The control code functions are:

  • ClusterResourceControl to access resource information.
  • ClusterResourceTypeControl to access resource type information.
  • ClusterGroupControl to access group information.
  • ClusterNodeControl to access node information.

These functions provide access to state and property information through a variety of control codes. There is a different set of control codes that are valid for each function. For example, to access a resource's modifiable common properties, call ClusterResourceControl with the control code CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES. For a comprehensive list of the operations available with the control code functions, see one of the following topics:

For resources, see Control Codes for Resources.

For resource types, see Control Codes for Resource Types.

For groups, see Control Codes for Groups.

For nodes, see Control Codes for Nodes.

When an application requires information that is not exposed through a control code, usually one of the cluster database management functions included in the Cluster API can be called to retrieve the information. The database management functions are similar to the Microsoft Win32® registry functions, but there is one important difference. With the database management functions, changes made on one node are atomically distributed as they occur to all affected nodes in the cluster. Therefore, all members of a cluster have consistent access to the information. Because the Win32 registry functions lack this important replication feature, applications should never use them to access the cluster database.


Creating a Custom Resource Type

It is possible to create a new resource type that you can associate with either a cluster-aware or cluster-unaware application. The advantages to creating your own new resource type are:

  • You can have the Resource Monitor manage your application in ways that are specific to your application.
  • You can make administration through Cluster Administrator less complicated.

When you create a new resource type, you should expect the network administrator to combine your new type with a Network Name resource and its dependent resources to create a virtual server that clients can access. Make sure that the network administrator places all of the necessary dependencies in the same group either by checking for this condition in your Cluster Administrator extension or by failing to load the resource DLL if a dependency is missing.

If there are required dependencies for your new resource type, support the CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code in your resource DLL's ResourceControl entry point and CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES in your ResourceTypeControl entry point. Also, check in Online that all required dependencies are available before allowing a resource to be brought online.

For example, suppose your new resource type manages a cluster-aware application that relies on data files. The network administrator might form a virtual server with this application, a Network Name resource, an IP Address resource, and a Physical Disk resource holding the application's data files.

It is recommended that you use the Resource Type AppWizard to create your new resource type. Because the Resource Type AppWizard creates skeletal implementations of all required entry point functions and interface methods, you will save time and effort and be assured that you are starting with working code.

When you use the Resource Type AppWizard, it will ask for parameters. Parameters are information that is specific to your resource type, also known as private properties. When a network administrator runs Cluster Administrator to create a resource of the new type, your Cluster Administrator extension will prompt him or her to enter values for these properties. These values are stored in the cluster database.

To create a new resource type
  1. Create a resource type project using the Resource Type AppWizard. See Using the Resource Type AppWizard for a step-by-step description of how to create your project.
  2. Prepare your build environment. For more information, see Preparing a Build Environment.
  3. Add code to customize the source files for your resource and Cluster Administrator extension DLLs. See Customizing a Resource DLL.
  4. Build the resource and Cluster Administrator extension DLLs. See Building a Custom Resource Type.
  5. Register your new resource type. For information about resource type registration, see Registering a Resource DLL.
  6. Register your Cluster Administrator extension DLL and the DebugEx Cluster Administrator extension DLL.
  7. Debug your resource DLL. For information about resource DLL debugging, see Debugging a Resource DLL.
  8. Debug your Cluster Administrator extension DLL. For more information, see Debugging a Cluster Administrator Extension DLL.


Using the Resource Type AppWizard

The Microsoft® Visual C++® development environment includes the Resource Type AppWizard, a wizard that guides you through the creation of a new resource type. The Resource Type AppWizard prompts for two types of information:

  • Information that is common to all resources, or common properties.
  • Information that applies only to resources belonging to your new type, or private properties.

Private properties are not shared with resources belonging to other types; they are specific to a single type. Examples of private resource properties include ShareName and Path properties for File Share resources and the Signature property for Physical Disk resources.

The following procedure takes you through the steps necessary for creating a project to support a new resource type with the Resource Type AppWizard.

To use the Resource Type AppWizard to create a new resource type
  1. Start your Visual C++ development environment.
  2. Select New from the File menu and then Project Workspace from the list box.
  3. Select Cluster Resource Type Application from the list of project types, enter the name of the project, and press the Create button. You will see the following dialog box:

  4. Provide a name in the Resource type name edit control.
  5. If you are creating a resource type to manage a service, check the Resource depends on a service checkbox and enter the name of the service.
  6. Press the Next button. You will see this dialog box:

    The Resource Parameters dialog box allows you to add parameters that are specific to your resource type, like a share name for a disk resource or a subnet mask for an IP address resource. Parameters are passed to your resource DLL to control the software associated with your new resource type. Some parameters are considered private properties of the resource and are accessible through Cluster Administrator and other management applications using the control code functions of the Cluster API.

    For more information about the common and private properties of resources, see Cluster Properties. For general information about control codes, see Cluster Control Codes.

  7. For each parameter that you want to enter, press the Add button and specify the name and type of the parameter and whether or not it is required. If you specify a numeric type such as DWORD, you can enter a default value, a minimum value, and a maximum value as shown in the following dialog box

  8. After adding each parameter, press the OK button of the Add Parameter dialog box. You will notice that the parameter and all related information is inserted into the Resource Parameters dialog box. The order in which the parameters appear dictates their order on the Parameters page in your Cluster Administrator extension. The following dialog box shows how the Resource Parameters screen appears after two parameters have been added:

  9. When you have added all of the parameters for the resource type, press the Finish button. A screen entitled New Project Information is displayed, providing data about the projects that you are about to create to support your new resource type. The data includes the names of the projects, resource type, project files, and classes, and specifies the directory in which the projects will be installed.

    The following New Project Information screen shows the type of data that is generated:

  10. If you are satisfied with the New Project Information, press the OK button to create the projects.
  11. Wait for the projects to be created and the workspace to be unloaded and reloaded. Your resource DLL and Cluster Administrator extension DLL projects are now ready for you to use.


Preparing a Build Environment

To prepare your environment for building and debugging resource DLLs or Cluster Administrator extension DLLs, you must correctly set the PATH, INCLUDE, and LIB environment variables and check for the existence of required libraries. Complete the following checklist to prepare your build environment:

  • Verify that you have set your PATH, INCLUDE, and LIB environment variables to include the appropriate directories in the correct order. The Microsoft® Developer Studio™ bin, include, and lib directories must appear first in the lists of directories for the corresponding PATH, INCLUDE, and LIB environment variables.
  • Set the PATH environment variable to a path that includes as its first directory the Developer Studio binary directory. This is typically c:\msdev\bin.
  • Set the INCLUDE environment variable to a path that includes these directories in the following order:
    1. Developer Studio directory containing header files, typically c:\msdev\include.
    2. Directory containing the CLUSAPI.H header file.
    3. Directory containing the Active Template Library (ATL) source files and header files, typically c:\msdev\atl.
  • Set the LIB environment variable to a path that includes as its first directory the Developer Studio library directory. This is typically c:\msdev\lib.
  • Check that you have installed the Unicode version of MFC; this library is required for building the Cluster Administrator extension DLL.
  • Check that you have the DebugEx Cluster Administrator extension DLL available in your cluster directory.

Note It is common to set your environment variables during the installation process for Microsoft Developer Studio. However, they can also be set by running VCVARS32.BAT from the BIN directory under the root of your development environment. Running VCVARS32.BAT is only necessary if you want to build from the command line rather than from within Developer Studio.


Building a Custom Resource Type

After you have created a project for your new resource type, attempt to build it. Use the Win32® Debug option if you would like debug versions of your DLLs and the Win32 Release option if you prefer release versions. You can build your DLLs from within Microsoft® Developer Studio™ or from the command line with the following commands:

nmake /a /f project.mak CFG="ResourceType - Win32 Version"
nmake /a /f project.mak CFG="ResourceTypeEx - Win32 Version"

Substitute the name of your project's makefile for project.mak. Substitute the name of your new resource type for ResourceType and then append an "Ex" to the resource type for ResourceTypeEx. For example, if you name your new resource TestDB, set ResourceType to TestDB and ResourceTypeEx to TestDBEx. Specify Debug or Release for the version.

If either of your build attempts fail, recheck that your environment variables are assigned correctly. See Preparing a Build Environment for a detailed description of how to set these variables.


Customizing a Resource DLL

The resource DLL that is created by the Resource Type AppWizard contains implementations of all of the necessary entry point functions, but these implementations are very basic, providing only a basic failover and failback capability. There are three main reasons for customizing and enhancing the resource DLL source files that are generated by the AppWizard:

  • To create code that will allow your resources to take full advantage of the cluster environment. For example, when your resource is being taken offline it might be advantageous to close files that are open and delete files that are temporary.
  • To implement parameters or properties that provide information specific to your resources.
  • To support the Active/Active failover and failback capability, which enables two separate instances of your resource to run on different nodes using different data. The data resides on a disk on the shared SCSI bus.

The source files in your resource DLL project include comments that begin with TODO: to indicate where to insert additional functionality or ADDPARAM: to indicate where to insert additional parameters or properties. The following modifications are common:

  1. Add library files specific to your resource type. Add lines for your resource-specific libraries after the following:
    #pragma comment(lib, "clusapi.lib")
  2. Add header files specific to your resource type. 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>


Registering a Resource DLL

The registration process for your new resource DLL involves copying your project files to a file share chosen for the resource type on the cluster nodes. After the files have been copied, perform the actual registration with the following command:

CLUSTER -create resourcetype "Resource type name" path

Have your setup program call the Cluster API function CreateClusterResourceType.


Debugging a Resource DLL

When you debug a resource DLL, you are debugging both the resource type and the resources that belong to the resource type.

To debug a resource type
  • Set the resource type's DebugControlFunctions property to TRUE.
  • Set the resource type's DebugPrefix property to the path to your debugger.

When your ResourceTypeControl entry point function is called, the Cluster Service checks the settings for these properties. If DebugControlFunction 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.

To debug a resource DLL
  1. Register the DebugEx Cluster Administrator DLL.
  2. Start Cluster Administrator.
  3. 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 insure that other resources remain unaffected by those problems.
  4. View the properties of the new resource by choosing Properties from the File menu after selecting the new resource.
  5. Click the Debug tab.
  6. In the Debug Command Prefix edit control, type the full path to your debugger. For example, if you are using MSDEV, type "c:\msdev\bin\msdev.exe."
  7. Press the OK button.
  8. Stop the Cluster Service by typing "net stop clussvc."
  9. Start the Cluster Service locally by typing the following command from the cluster directory:
    start clussvc -debug

    This command will cause a command box to be displayed with the output from the Cluster Service. As soon as the Cluster Service starts, it will start the Resource Monitor with your resource in it and attach your debugger to it. At that point you will see MSDEV being invoked. You can now set breakpoints in the DLL, such as SmbSampleOnlineThread.


Registering a Cluster Administrator Extension DLL

To register your Cluster Administrator extension DLL, call REGCLADM.EXE followed by the complete path to the DLL as follows:

regcladm path

Next, register DebugEx so that this extension is available to aid in debugging your resource DLL. To register DebugEx, enter:

regcladm debugex.dll

If DebugEx has already been registered, the Debug tab will appear as one of the tabs on the property sheet of Cluster Administrator.

There are two parts to the registration of a Cluster Administrator extension.

The first part is registering the extension with the cluster. The DllRegisterCluAdminExtension entry point accomplishes this registration. DllRegisterCluAdminExtension causes the AdminExtensions property to be stored in the cluster database and modified if necessary. The CLSID for the extension is placed in the AdminExtensions value if it is not already present.

The second part is registering the extension with COM. The DllRegisterServer entry point accomplishes this registration. This causes a key for the ProgId (for example, CLUADMEX.Standard) to be created below HKEY_CLASSES_ROOT and a key for the CLSID to be created below HKEY_CLASSES_ROOT\CLSID.

REGCLADM calls both DllRegisterCluAdminExtension and DllRegisterServer. Setup programs that install these extensions will also need to call these two entry points. If your setup program is run on a cluster node, call both entry points. If your setup program is run on a client (for example, a non-cluster node, such as where Cluster Administrator is installed), just call DllRegisterServer.


Debugging a Cluster Administrator Extension DLL

To debug a Cluster Administrator extension DLL
  1. Run the MSDEV 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. Select Settings from the Build menu.
  4. Select the entry that represents the Win32 Debug version of your Cluster Administrator extension DLL project in the Settings For list box.
  5. Select 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 and press the OK button.
  7. Set a breakpoint in the project, such as at the OnInitDialog method for the parameter page in the resprop.cpp source file.
  8. Start Cluster Administrator in the debugger by pressing f5.
  9. View the properties of a resource of the type supported by your Cluster Administrator extension DLL.
  10. Select the Parameters tab to switch to the parameters page. This should cause the debugger to halt at the breakpoint set above in step 7.

The debugger should also halt when you create a new resource of the type supported by your extension DLL.

Note 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 will cause the appearance of error popup dialogsr.


Cluster Server Programming

Cluster Server programming targets two main types of development:

  • Developing applications to manage clusters and cluster objects.
  • Developing custom resource types to allow applications and services to operate as cluster resources.

Depending on the type of development that you intend to pursue, you will use one or more of the application programming interfaces (APIs) included with the Cluster Server SDK. The Cluster Server SDK has a variety of different APIs, some that are sets of functions and others that are Component Object Model (COM) interfaces. Although Cluster Server supports development in C, C++, Microsoft® Visual Basic®, and several scripting languages, not all of the APIs are meant to be used with all of the languages. The following table offers a summary description of each API.

API | Description | Languages
Cluster API | Allows a resource DLL or application to communicate with the Cluster Service and cluster database. | C, C++
Resource API | Allows the Cluster Service to communicate with a resource through the Resource Monitor. | C, C++
Cluster Administrator Extension API | Allows property pages and context menus for a custom resource type to be integrated into Cluster Administrator. | C, C++
Cluster Automation Server API | Allows an application to administer a cluster. | Visual Basic, scripting languages

The Cluster API is a function-based interface used by cluster-aware applications written in C or C++. The Cluster Service implements all of the functions of the Cluster API. Applications and resource DLLs make calls to these functions to access information about cluster objects.

The Resource API is a function-based interface that is primarily implemented by resource DLLs written in C or C++. This API also includes a few callback functions that are used by the resource DLL to report events and status.

Cluster Automation Server is a COM-based dual interface used by cluster management applications written in Microsoft® Visual Basic® or one of the scripting languages. Cluster Automation Server is implemented in MSCLUS.DLL.

The Cluster Administrator Extension API is a set of COM-based interfaces that are implemented and used by Cluster Administrator extension DLLs written in C or C++. Cluster Administrator extension DLLs implement interfaces for enhancing Cluster Administrator objects and invoking commands. The DLLs call other interfaces in the API to retrieve information from Cluster Administrator and to add to a Cluster Administrator property sheet, wizard, or context menu.


About Property Tables

A property table is an array of RESUTIL_PROPERTY_ITEM structures that is useful for working with multiple properties. Rather than using the CLUSPROP_BUFFER_HELPER structure to step through each property, applications and resource DLLs can use a property table. In combination with the utility functions written to manipulate property values, property lists, and property tables, using a property table offers developers a simpler solution to the potentially complex task of property management.

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 buffer known as a parameter block. A parameter block is typically a structure that contains one member for each data value that belongs to a property in the property table. However, because an offset is used to identify the location of data, parameter block structures can contain non-property members as well as property members.

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 | LPWSTR pointing to the data followed by a DWORD to indicate 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 size of the data in bytes
CLUSPROP_FORMAT_SZ | Pointer to a null-terminated Unicode string if non-null | LPWSTR


About Value Lists

A value list is a collection of data values that is used as the data portion of a property value in a property list and is returned from the following control code operations:

  • CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES
  • CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO
  • CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES
  • CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS

Because each of the data values in a value list can have a different format, type, and length, each entry in the list begins with a CLUSPROP_VALUE structure. The CLUSPROP_VALUE structure describes the data that follows it and has two members: a syntax member and a length member. The syntax member is a CLUSPROP_SYNTAX structure, a union that describes data as either a single DWORD such as CLUSPROP_SYNTAX_SCSI_ADDRESS or as a format and type such as CLUSPROP_FORMAT_DWORD and CLUSPROP_TYPE_CHARACTERISTICS.

For some types of data, one way is definitely preferred. User-defined types fall into this category and must be described with a format and type. A user-defined value type might be used with a user-defined control function. The CLUSPROP_VALUE structure's Syntax member for user-defined numeric data would be set as follows. Notice that the wType member is set to a value beginning with CLUSPROP_TYPE_USER, the beginning of the range for user-defined data types.

#define CLUSPROP_TYPE_MY_TYPE (CLUSPROP_TYPE_USER+1)
CLUSPROP_SYNTAX Syntax;
Syntax.wFormat = CLUSPROP_FORMAT_DWORD;
Syntax.wType = CLUSPROP_TYPE_MY_TYPE;

Other types of data can set to appropriate values either the dw member of the CLUSPROP_VALUE structure or the wFormat and wType members of the CLUSPROP_SYNTAX structure. For example, you could describe a disk number in either of the following two ways:

CLUSPROP_SYNTAX Syntax;
Syntax.dw = CLUSPROP_SYNTAX_DISK_NUMBER;

CLUSPROP_SYNTAX Syntax;
Syntax.wFormat = CLUSPROP_FORMAT_DWORD;
Syntax.wType = CLUSPROP_TYPE_DISK_NUMBER;

The only difference between the two definitions is that the first example combines the format and type values at compile time while the second example combines them at run time.

The last entry in a value list is special. Because its purpose is solely to mark the end of the list, it contains only the CLUSPROP_SYNTAX portion of the CLUSPROP_VALUE structure. There is no length member and no data. The last entry appears as follows:

CLUSPROP_SYNTAX Syntax;
Syntax.dw = CLUSPROP_SYNTAX_ENDMARK;

For information about property lists, see About Property Lists.


About Property Lists

A property list is similar to a value list in that both types of lists consist of one or more entries and a unique last entry, identified by CLUSPROP_SYNTAX_ENDMARK. The entries in a property list, however, are more complex than in a value list. While an entry in a value list consists of a CLUSPROP_VALUE structure and a data value, an entry in a property list consists of a property name and a property value. The property name is made up of:

  • A CLUSPROP_VALUE structure
  • A name string
  • Additional padding if necessary for alignment

The property value is a value list plus padding if the value list is not DWORD aligned. Because each property value in a property list must always be DWORD aligned, padding is required only if the value is not yet property aligned. Typically the value list for a property value will contain two entries: one to describe the data in the property value and the other to mark the end of the list.

Any of the control codes that work with properties use a property list for input or return a property list as output. For example, ClusterResourceControl returns a property list from its handling of CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES and requires a property list to handle CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES.

The following diagram shows the layout of a property list. Gray shading is used to indicate data that is only required if the data is not DWORD aligned.

To locate a specific property in a property list, use the utility function called ResUtilFindSzProperty. ResUtilFindSzProperty returns a pointer to the string in the property list for the specified property. ResUtilFindDwordProperty is also available. These functions are defined in the resource utility library, RESUTILS.DLL. The prototypes for these functions are located in RESAPI.H. Another option for locating information is to loop through each property until you are finished. If you don't know exactly what you are looking for, this is the only option.

The CLUSPROP_BUFFER_HELPER structure is also helpful for parsing or constructing a property list or value list. This structure is a union of pointers to the individual CLUSPROP value structures defined in CLUSAPI.H.

For more information about value lists, see About Value Lists.


Enumerating Cluster Objects

One of the most common tasks of cluster-aware and cluster management applications is to enumerate objects in the cluster. Applications can enumerate specific types of objects such as resources, or choose to limit their enumeration to objects that affect a particular group or resource.

To find the cluster Network Name resource
  • Create a resource enumerator by calling ClusterOpenEnum and specifying CLUSTER_ENUM_RESOURCE for the dwType parameter.
  • Loop through all of the resources in the cluster by calling ClusterEnum repeatedly with the contents of the lpdwType parameter set to CLUSTER_ENUM_RESOURCE. For each resource:
    1. Call OpenClusterResource, setting the lpszResourceName parameter to the contents of the lpszName parameter returned from ClusterEnum.
    2. Call ClusterResourceControl with the dwControlCode parameter set to CLUSCTL_RESOURCE_GET_FLAGS.
    3. If the CLUS_FLAG_CORE flag is set, indicating that the resource is a core cluster resource, call ClusterResourceControl with the dwControlCode parameter set to CLUSCTL_RESOURCE_GET_RESOURCE_TYPE.
    4. The resource type will be set to "Network Name" for the cluster Network Name resource. There will only be one core resource in the cluster with the "Network Name" resource type.


Choosing Between Control Codes and Cluster API Functions

Control codes describe a great many operations, some of which can also be performed with a Cluster API function. This can be confusing — do you use a control code function or one of the other Cluster API functions? The rule of thumb is to always use a control code if possible, especially if the operation involves accessing the cluster database. For example, there are two ways to set a resource's private properties in the cluster database:

  1. Call ClusterResourceControl with the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code.
  2. Call ClusterRegOpenKey to access the appropriate key in the database and ClusterRegSetValue to perform the update.

Although the end result is the same, using the control code function is preferrable.


Control Codes and Quorum Resources

The ResourceControl entry point function for quorum resources must handle the following control codes:

  • CLUSCTL_RESOURCE_GET_CLASS_INFO
  • CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO

Handling CLUSCTL_RESOURCE_GET_CLASS_INFO identifies a quorum resource as a storage device. Handling CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO allows Cluster Administrator to display partition information about a quorum resource.

In your handling of CLUSCTL_RESOURCE_GET_CLASS_INFO, return a CLUS_RESOURCE_CLASS_INFO structure that is set as follows:

CLUS_RESOURCE_CLASS_INFO ClassInfo;
ClassInfo.rc = CLUS_RESCLASS_STORAGE;
ClassInfo.SubClass = CLUS_RESSUBCLASS_SHARED;

Setting these values in the CLUS_RESOURCE_CLASS_INFO structure makes a resource look like shared storage.


Cluster API

The Cluster API enables the use of services provided by the Cluster Service. It includes functions to retrieve and update data for the following purposes:

  • Network management
  • Network interface management
  • Cluster management
  • Node management
  • Resource management
  • Group management
  • Cluster database management

The Cluster API is used by cluster-aware applications, by cluster management applications, by resource DLLs, and by the Cluster Service. Cluster-aware applications such as database server applications use the Cluster API to discover resources and monitor changes in their state. Cluster management applications such as Cluster Administrator use the Cluster API to perform administration and configuration.

Access to a cluster through the Cluster API is unaffected by a node failure if the user has connected to the cluster rather than to a node and an alternate node is available. Individual calls may return errors resulting from node failures, but the cluster will remain available.

The following diagram shows how the Cluster API is accessed. The components inside the dashed line represent one node in a two node cluster. The node is running the Cluster Service, several resource DLLs, and one or more cluster-aware server applications. On another cluster node or a system unrelated to the cluster, there are cluster management applications such as Cluster Administrator and cluster-aware client applications. All of these components use the Cluster Service through the Cluster API.


Network Management Functions

The network management functions in the Cluster API provide access to information about networks that are monitored by the Cluster Service. The following functions are included in the Cluster API for network management:

Function | Description
CloseClusterNetwork | Closes a connection to a network by invalidating its handle.
ClusterNetworkCloseEnum | Closes an enumerator for iterating through objects on a network.
ClusterNetworkControl | Initiates an operation affecting a network.
  • 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.
  • 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.


CloseClusterNetwork

The CloseClusterNetwork function closes a connection to a network by invalidating its handle.

BOOL WINAPI CloseClusterNetwork(
  HNETWORK hNetwork
);

Parameters

hNetwork
[in] Handle to the network to close.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful; call the Win32 function GetLastError to obtain more detailed information.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterNetworkCloseEnum

The ClusterNetworkCloseEnum function closes an enumerator for iterating through objects on a network.

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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterNetworkCloseEnum returns a Win32 error value.

Remarks

ClusterNetworkCloseEnum closes the enumerator object by invalidating its handle, a handle returned from ClusterNetworkOpenEnum.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterNetworkEnum

The ClusterNetworkEnum function enumerates 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 lpcbName
);

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 is returned with each call:
CLUSTER_NETWORK_ENUM_NETINTERFACES
The object is a network interface.
lpszName
[out] Pointer to the name of the returned object, a NULL-terminated string.
lpcbName
[in, out] On input, pointer to a buffer. On output, pointer to the count of characters in the name pointed to by the lpszName parameter minus the terminating NULL character.

Return Values

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 long enough to hold the required number of characters. The lpcbName parameter has been set to the required buffer length.

Remarks

The ClusterNetworkEnum function is typically used to iterate through a collection of network objects of one or more types. 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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:
CLUSTER_NETWORK_ENUM_NETINTERFACES
Enumerate the network interface objects on the network.
CLUSTER_NETWORK_ENUM_ALL
Enumerate all objects on the network.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterNetworkControl

The ClusterNetworkControl function initiates an operation affecting a network.

DWORD WINAPI ClusterNetworkControl(
  HNETWORK hNetwork,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lplnBuffer,
  DWORD cblnBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hNetwork
[in] Handle to the network to be affected by the operation.
hHostNode
[in] Optional handle to the node hosting the affected network.
dwControlCode
[in] Control code that defines the operation to perform. For a list of the valid values for the dwControlCode parameter, see Control Codes for Networks.
lplnBuffer
[in] Pointer to the input buffer with information needed for the operation, or NULL if no information is needed.
cblnBufferSize
[in] Number of bytes in the buffer pointed to by lplnBuffer.
lpOutBuffer
[out] Pointer to the output buffer with information resulting from the operation, or NULL if nothing needs to 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 ClusterNetworkControl need not pass back the number of bytes in the output buffer.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer is not large enough to hold the data being returned. The lpcbBytesReturned parameter points to the size required for the output buffer.

If the operation was unsuccessful, ClusterNetworkControl returns a Win32 error value.

Remarks

ClusterNetworkControl is a general-purpose function for initiating an operation that affects a network. The scope of allowable operations is defined by the set of control codes specified for networks. For a complete description of how to use control codes and control code functions, see Cluster Control Codes.

When ClusterNetworkControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

If the operation was successful, GetClusterNetworkState returns the current state of the network, which is represented by one of the following values:

State | Description
ClusterNetworkStateDown | The network is not operational; none of the nodes on the network can communicate.
ClusterNetworkStatePartitioned | The network is operational, but two or more nodes on the network cannot communicate. Typically a path-specific problem has occurred.
ClusterNetworkStateUp | The network is operational; all of the nodes in the cluster can communicate.
ClusterNetworkStateUnavailable | State information for the network is unavailable. The network's Role property is set to ClusterNetworkRoleNone.

If the operation was unsuccessful, GetClusterNetworkState returns ClusterNetworkStateUnknown. For more detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 terminating NULL character.
lpcchNetworkId
[in, out] On input, pointer to a buffer. On output, pointer to a count of characters in the network identifier pointed to by lpszNetworkId, including the terminating NULL character.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The buffer pointed to by lpszNetworkId is not long enough to hold the required number of characters. The lpcchNetworkId parameter is set to the required buffer length.

If the operation was unsuccessful for a reason other than insufficient size in the buffer pointed to by lpszNetworkId, GetClusterNetworkId returns a Win32 error value.

Remarks

When GetClusterNetworkId returns, the variable pointed to by lpcchNetworkId contains the number of characters stored in the buffer. The count returned does not include the terminating NULL character.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 network.
lpszNetworkName
[in] Pointer to the name of an existing network.

Return Values

NULL
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterNetwork returns a network handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the new network name.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, SetClusterNetworkName returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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. All networks that can be used for node-to-node communication must appear in the list and there can be no duplicates.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_NOT_ENOUGH_MEMORY
The operation was unsuccessful due to insufficient memory.
ERROR_INVALID_PARAMETER
There was a duplicate network in NetworkList.

If the operation was unsuccessful, SetClusterNetworkPriorityOrder can also return a Win32 error value.

Remarks

Internal communication is always carried on the highest priority network that is available between two nodes.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Network Interface Management Functions

The functions in the Cluster API for managing a network interface in a cluster open and close the network interface, perform selected operations, and retrieve information. The following functions are included in the Cluster API for managing network interfaces:

Function | Description
CloseClusterNetInterface | Closes a network interface handle.
ClusterNetInterfaceControl | Initiates an operation affecting 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

TRUE
The operation was successful.
FALSE
The operation was unsuccessful; call the Win32 function GetLastError to obtain more detailed information.

Remarks

The network interface handle specified in hNetInterface should be a handle obtained from a call to OpenClusterNetInterface.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterNetInterfaceControl

The ClusterNetInterfaceControl function initiates an operation affecting a network interface.

DWORD WINAPI ClusterNetInterfaceControl(
  HNETINTERFACE hNetInterface,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lplnBuffer,
  DWORD cblnBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hNetInterface
[in] Handle to the network interface to be affected by the operation.
hHostNode
[in] Optional handle to the node hosting the affected network interface.
dwControlCode
[in] Control code that defines the operation to perform. For a list of the valid values for the dwControlCode parameter, see Control Codes for Network Interfaces.
lplnBuffer
[in] Pointer to the input buffer with information needed for the operation, or NULL if no information is needed.
cblnBufferSize
[in] Number of bytes in the buffer pointed to by lplnBuffer.
lpOutBuffer
[out] Pointer to the output buffer with information resulting from the operation, or NULL if nothing need 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 ClusterNetInterfaceControl need not pass back the number of bytes in the output buffer.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer is not large enough to hold the data being returned. The lpcbBytesReturned parameter points to the size required for the output buffer.

If the operation was unsuccessful, ClusterNetInterfaceControl returns a Win32 error value.

Remarks

ClusterNetInterfaceControl is a general-purpose function for initiating an operation that affects a network interface. The scope of allowable operations is defined by the set of control codes specified for network interfaces. For a complete description of how to use control codes and control code functions, see Cluster Control Codes.

When ClusterNetInterfaceControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 lpcbInterfaceName
);

Parameters

hCluster
[in] Handle to a cluster.
lpszNodeName
[in] Pointer to the name of the node in the cluster.
lpszNetworkName
[in] Pointer to the name of the network.
lpszInterfaceName
[out] Pointer to an output buffer holding the name of the network interface.
lpcbInterfaceName
[in, out] On input, pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpszInterfaceName, including the terminating NULL character. On output, pointer to a variable that contains the number of characters stored in the output buffer not including the terminating NULL character.

Return Values

ERROR_SUCCESS
The network interface name was returned successfully.
ERROR_MORE_DATA
The name to be returned is longer than can fit in the buffer pointed to by lpszInterfaceName.

If the operation was unsuccessful, GetClusterNetInterface can also return a Win32 error.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

If the operation was successful, GetClusterNetInterfaceState returns the current state of the network, which is represented by one of the following values:

State | Description
ClusterNetInterfaceFailed | The network interface is not operational; typically a hardware failure has occurred.
ClusterNetInterfaceUnreachable | None of the active nodes in the cluster can access the network interface.
ClusterNetworkUp | The network interface is operational.
ClusterNetworkUnavailable | State information for the network interface is unavailable.

If the operation was unsuccessful, GetClusterNetInterfaceState returns ClusterNetInterfaceStateUnknown. For more detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of the network interface to open.

Return Values

NULL
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterNetInterface returns an open handle to the specified network interface.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Cluster Management Functions

The cluster management functions in the Cluster API provide access to event notification, cluster objects, and overall cluster state information. The following functions are included in the Cluster API for cluster management:

Function | Description
CloseCluster | Closes a connection to a cluster by invalidating its handle.
  • CloseClusterNotifyPort
 Closes a notification port established through CreateClusterNotifyPort by invalidating its handle.
  • ClusterCloseEnum
 Closes a cluster enumerator object by invalidating its handle, a handle returned from ClusterOpenEnum.
  • 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.
ClusterResourceTypeControl | Initiates an operation affecting a resource type.
  • CreateClusterNotifyPort
 Creates a notification port to handle cluster event notification.
CreateClusterResourceType | Creates a new resource type in a cluster.
DeleteClusterResourceType | Removes a resource type from a cluster.
  • 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 connection to a cluster by invalidating its handle.

BOOL WINAPI CloseCluster(
  HCLUSTER hCluster
);

Parameters

hCluster
[in] Handle to the cluster to close.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful; call the Win32 function GetLastError to obtain more detailed information.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CloseClusterNotifyPort

The CloseClusterNotifyPort function closes a notification port established through CreateClusterNotifyPort by invalidating its handle.

BOOL WINAPI CloseClusterNotifyPort(
  HCHANGE hChange
);

Parameters

hChange
[in] Handle to the notification port to close.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful; call the Win32 function GetLastError for more detailed information.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterCloseEnum

The ClusterCloseEnum function closes a cluster enumerator object by invalidating its handle, a handle returned from ClusterOpenEnum.

DWORD WINAPI ClusterCloseEnum(
  HCLUSENUM hEnum
);

Parameters

hEnum
[in] Handle to the cluster enumerator to close. This is a handle originally returned by the ClusterOpenEnum function.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterCloseEnum returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterEnum

The ClusterEnum function enumerates 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 lpcbName
);

Parameters

hEnum
[in] Handle to an existing enumeration object originally 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:
CLUSTER_ENUM_NODE
The object is a node in the cluster.
CLUSTER_ENUM_RESTYPE
The object is a resource type in the cluster.
CLUSTER_ENUM_RESOURCE
The object is a resource in the cluster.
CLUSTER_ENUM_GROUP
The object is a group in the cluster.
lpszName
[out] Pointer to the name of the returned object, a NULL-terminated string.
lpcbName
[in, out] On input, pointer to a buffer. On output, pointer to the count of characters in the name pointed to by the lpszName parameter minus the terminating NULL character.

Return Values

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 long enough to hold the required number of characters. The lpcbName parameter has been set to the required buffer length.

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 wanted to enumerate groups in addition to nodes, it would set dwType 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterOpenEnum

The ClusterOpenEnum function opens an enumerator for iterating through 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:
CLUSTER_ENUM_GROUP
Enumerate the groups in the cluster.
CLUSTER_ENUM_NODE
Enumerate the nodes in the cluster.
CLUSTER_ENUM_RESTYPE
Enumerate the resource types in the cluster.
CLUSTER_ENUM_RESOURCE
Enumerate the resources in the cluster.

Return Values

NULL
The operation was unsuccessful. For more detailed 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, and/or resources. 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterResourceTypeControl

The ClusterResourceTypeControl function initiates an operation affecting a resource type.

DWORD WINAPI ClusterResourceTypeControl(
  HCLUSTER hCluster,
  LPCWSTR ResourceTypeName,
  HNODE hHostNode,
  DWORD dwControlCode,
  LPVOID lplnBuffer,
  DWORD cblnBufferSize,
  LPVOID lpOutBuffer,
  DWORD cbOutBufferSize,
  LPDWORD lpcbBytesReturned
);

Parameters

hCluster
[in] Handle to the cluster containing the resource type identified in ResourceTypeName.
ResourceTypeName
[in] Pointer to the name of the resource type to be affected.
hHostNode
[in] Optional handle to the node hosting the affected resource type.
dwControlCode
[in] Control code that defines the operation to perform. For a list of the valid values for the dwControlCode parameter, see Control Codes for Resource Types.
lplnBuffer
[in] Pointer to the input buffer with information needed for the operation, or NULL if no information is needed.
cblnBufferSize
[in] Number of bytes in the buffer pointed to by lplnBuffer.
lpOutBuffer
[out] Pointer to the output buffer with information resulting from the operation, or NULL if nothing need 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 need not pass back the number of bytes in the output buffer.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer is not large enough to hold the data being returned. The lpcbBytesReturned parameter points to the size required for the output buffer.

If the operation was unsuccessful, ClusterResourceTypeControl returns a Win32 error value.

Remarks

ClusterResourceTypeControl is a general-purpose function for initiating an operation that affects a resource type. The scope of allowable operations is defined by the set of control codes specified for resource types. For a complete description of how to use control codes and control code functions, see Cluster Control Codes.

When ClusterResourceTypeControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CreateClusterNotifyPort

The CreateClusterNotifyPort function creates a notification port to handle cluster event notification.

HCHANGE WINAPI CreateClusterNotifyPort(
  HCHANGE hChange,
  HCLUSTER hCluster,
  DWORD dwFilter,
  DWORD 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 describes the events to cause notifications to be stored in the queue. One or more of the following flags can be set using the OR operator:
CLUSTER_CHANGE_CLUSTER_PROPERTY
Indicates that a notification should be issued when the prioritized list of internal networks has changed.
CLUSTER_CHANGE_CLUSTER_STATE
This notification is reserved for future use.
CLUSTER_CHANGE_GROUP_ADDED
Indicates that a notification should be issued when a new group is created in the cluster. Groups are created with a call to the CreateClusterGroup function.
CLUSTER_CHANGE_GROUP_DELETED
Indicates that a notification should be issued when an existing group is deleted. Groups are deleted with a call to the DeleteClusterGroup function.
CLUSTER_CHANGE_GROUP_PROPERTY
Indicates that a notification should be issued when the properties of an existing group change. Events that can trigger this notification include calling SetClusterGroupName to change a group's name and adding or removing a resource from a group.
CLUSTER_CHANGE_GROUP_STATE
Indicates that a notification should be issued when a group changes state. For a list of the possible group state values, see GetClusterGroupState.
CLUSTER_CHANGE_HANDLE_CLOSE
Indicates that a notification should be issued when a handle associated with a cluster object has closed.
CLUSTER_CHANGE_NETINTERFACE_ADDED
Indicates that a notification should be issued when a new network interface is added to a cluster node.
CLUSTER_CHANGE_NETINTERFACE_DELETED
Indicates that a notification should be issued when a network interface is permanently removed from a cluster node.
CLUSTER_CHANGE_NETINTERFACE_PROPERTY
Indicates that a notification should be issued when the properties of an existing network interface change.
CLUSTER_CHANGE_NETINTERFACE_STATE
Indicates that a notification should be issued when a network interface changes state. For a list of the possible network interface state values, see GetClusterNetInterfaceState.
CLUSTER_CHANGE_NETWORK_ADDED
Indicates that a notification should be issued when a new network is added to the cluster environment.
CLUSTER_CHANGE_NETWORK_DELETED
Indicates that a notification should be issued when a network is permanently removed from the cluster environment.
CLUSTER_CHANGE_NETWORK_PROPERTY
Indicates that a notification should be issued when the properties of an existing network change.
CLUSTER_CHANGE_NETWORK_STATE
Indicates that a notification should be issued when a network changes state. For a list of the possible network state values, see GetClusterNetworkState.
CLUSTER_CHANGE_NODE_ADDED
Indicates that a notification should be issued when a new node is added to the cluster. A node can only be added when Cluster Server is initially installed on the node.
CLUSTER_CHANGE_NODE_DELETED
Indicates that a notification should be issued 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
This notification is reserved for future use.
CLUSTER_CHANGE_NODE_STATE
Indicates that a notification should be issued when a node changes state. For a list of possible node state values, see GetClusterNodeState.
CLUSTER_CHANGE_QUORUM_STATE
This notification is reserved for future use.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES
Indicates that a notification should be issued 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
Indicates that a notification should be issued when the name of a cluster database key has changed. Name changes can occur through the ClusterRegCreateKey function which creates a new database key and the ClusterRegDeleteKey function which deletes a key.
CLUSTER_CHANGE_REGISTRY_SUBTREE
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
Indicates that a notification should be issued 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
Indicates that a notification should be issued when a new resource is created in the cluster. Resources can be created with the CreateClusterResource function.
CLUSTER_CHANGE_RESOURCE_DELETED
Indicates that a notification should be issued when a resource is deleted. Resources can be deleted with the DeleteClusterResource function.
CLUSTER_CHANGE_RESOURCE_PROPERTY
Indicates that a notification should be issued when the properties of a resource change. Events that can trigger this notification include changing the name of a resource with SetClusterResourceName, changing a resource's list of possible owner nodes with AddClusterResourceNode and RemoveClusterResourceNode, and changing a resource's dependencies with AddClusterResourceDependency or RemoveClusterResourceDependency.
CLUSTER_CHANGE_RESOURCE_STATE
Indicates that a notification should be issued when a resource changes state. For a list of the possible resource state values, see GetClusterResourceState.

This notification is also issued when a resource is moved from one group to another with ChangeClusterResourceGroup.

CLUSTER_CHANGE_RESOURCE_TYPE_ADDED
Indicates that a notification should be issued when a new resource type is created in the cluster. Resource types can be created with the CreateClusterResourceType function.
CLUSTER_CHANGE_RESOURCE_TYPE_DELETED
Indicates that a notification should be issued when an existing resource type is deleted. Resource types can be deleted with the DeleteClusterResourceType function.
dwNotifyKey
[in] Any value that is to be associated with retrieving notifications from the created notification port. The dwNotifyKey is returned from GetClusterNotify when an event of one of the types specified in dwFilter occurs.

Return Values

NULL
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterNotifyPort returns a notification port handle.

Remarks

A notification port stores notifications of events occurring within a cluster for applications. Applications register to store events using CreateClusterNotifyPort, setting dwFilter to one or more events of interest and dwNotifyKey to a value that represents the registration. For example, if an application wants to be informed when there is any change to the cluster's resource types, it would set dwFilter to:

CLUSTER_CHANGE_RESOURCE_TYPE_ADDED | CLUSTER_CHANGE_RESOURCE_TYPE_DELETED

Once registered, the notification port maintains a queue of notification events. The application must call GetClusterNotify to retrieve the notifications associated with the events and the affected data. An application can have zero or more notification ports.

Applications that want to add other event types after the CreateClusterNotifyPort function has completed can do so by calling RegisterClusterNotify.

To receive notifications of cluster database changes, one or more of the flags applicable to the cluster database must be set in the dwFilter parameter. Applicable flags begin with the prefix CLUSTER_CHANGE_REGISTRY.

By specifying one of the cluster database flags, an application can learn of events that apply to the database root for the cluster specified by the hCluster parameter.

The CLUSTER_CHANGE_HANDLE_CLOSE event is meant to prevent a potential race condition that can occur when one thread trying to close a notification port calls CloseClusterNotifyPort and completes while simultaneously another thread is trying to retrieve an event from this port by calling GetClusterNotify. Prevent this potential problem by having the thread calling GetClusterNotify watch for the CLUSTER_CHANGE_HANDLE_CLOSE notification as follows:

do {
    Status = GetClusterNotify(hChange,...)
    if (Status == ERROR_SUCCESS) {
        if (dwFilter == CLUSTER_CHANGE_HANDLE_CLOSE) {
            //
            // Clean up and terminate
            //
            break;
        }

        // do something
    }
while (Status == ERROR_SUCCESS);

For information about the data that is returned to an application when it makes the call to retrieve a notification, see GetClusterNotify.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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 contents of lpszResourceTypeName should uniquely identify the resource type on all clusters, the contents 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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, CreateClusterResourceType returns a Win32 error value.

Remarks

Developers of new resource types must keep in mind that 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of the resource type to be removed.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, 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 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of the cluster identified by hCluster, including the terminating NULL character.
lpcchClusterName
[in, out] On input, pointer to a buffer. On output, pointer to a count of characters in the cluster name pointed to by lpszClusterName, including the terminating NULL character.
lpClusterInfo
[out] Either NULL or a pointer to a CLUSTERVERSIONINFO structure describing the version of the Cluster API for the cluster. When lpClusterInfo is not NULL, the dwVersionInfoSize member of this structure should be set as follows:
lpClusterInfo->dwVersionInfoSize =
sizeof(CLUSTERVERSIONINFO);

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The buffer pointed to by lpszClusterName is not long enough to hold the required number of characters. The lpcchClusterName parameter is set to the required buffer length.

If the operation was unsuccessful for a reason other than insufficient size in the buffer pointed to by lpszClusterName, GetClusterInformation returns a Win32 error value.

Remarks

When GetClusterInformation returns, the variable pointed to by lpcchClusterName contains the number of characters stored in the buffer. The count returned does not include the terminating NULL character.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


GetClusterNotify

The GetClusterNotify function returns information relating to the next notification event stored for a notification port.

DWORD WINAPI GetClusterNotify(
  HCHANGE hChange,
  LPDWORD 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 the type of returned event. See CreateClusterNotifyPort for the list of valid event types.
lpszName
[out] Pointer to the name of the object that triggered the event. The following table describes the contents 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_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] On input, pointer to the count of characters in the buffer pointed to by lpszName. On output, pointer to the count of characters stored in the buffer pointed to by lpszName, excluding the trailing NULL.
dwMilliseconds
[in] Optional time-out value that specifies how long the caller is willing to wait for the notification.

Return Values

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.

If the notification was not successfully returned, GetClusterNotify returns a Win32 error value. For more detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


GetClusterQuorumResource

The GetClusterQuorumResource function returns the name of a cluster's quorum resource.

DWORD WINAPI GetClusterQuorumResource(
  HCLUSTER hCluster,
  LPWSTR lpszResourceName,
  LPDWORD lpcbResourceName,
  LPWSTR lpszDeviceName,
  LPDWORD lpcbDeviceName,
  LPDWORD lpdwMaxQuorumLogSize
);

Parameters

hCluster
[in] Handle to an existing cluster.
lpszResourceName
[out] Pointer to a NULL-terminated string containing the name of the cluster's quorum resource.
lpcbResourceName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszResourceName parameter including the terminating NULL character. On output, pointer to the count of characters stored in the buffer, excluding the terminating NULL character.
lpszDeviceName
[out] Pointer to a NULL-terminated string containing the name of the device on which the quorum resource resides.
lpcbDeviceName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszDeviceName parameter including the terminating NULL character. On output, pointer to the count of characters stored in the buffer, excluding the terminating NULL character.
lpdwMaxQuorumLogSize
[out] Pointer to the maximum size of the log being maintained by the quorum resource.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The buffer pointed to by lpszResourceName is not long enough to hold the required number of characters. The lpcbResourceName parameter has been set to the required buffer length.

If the operation was unsuccessful, GetClusterQuorumResource can also return a Win32 error value.

Remarks

For information about a cluster's quorum resource, see Quorum Resource.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


OpenCluster

The OpenCluster function opens a connection to a cluster and returns a handle to it.

HCLUSTER WINAPI OpenCluster(
  LPCWSTR lpszClusterName
);

Parameters

lpszClusterName
[in] Pointer to the name of an existing cluster or NULL, indicating that a handle to the cluster to which the local computer belongs should be returned.

Return Values

NULL
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenCluster returns a cluster handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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:
CLUSTER_CHANGE_GROUP_DELETED
Indicates that a notification should be issued when an existing resource group is deleted.
CLUSTER_CHANGE_GROUP_PROPERTY
Indicates that a notification should be issued when the properties of an existing resource group change.
CLUSTER_CHANGE_GROUP_STATE
Indicates that a notification should be issued when a resource group changes state.
CLUSTER_CHANGE_HANDLE_CLOSE
Indicates that a notification should be issued when a handle to a cluster object has closed.
CLUSTER_CHANGE_NODE_DELETED
Indicates that a notification should be issued when a node is permanently removed from a cluster.
CLUSTER_CHANGE_NODE_PROPERTY
This notification is reserved for future use.
CLUSTER_CHANGE_NODE_STATE
Indicates that a notification should be issued when a node changes state.
CLUSTER_CHANGE_REGISTRY_ATTRIBUTES
Indicates that a notification should be issued when a cluster database key's attributes are changed.
CLUSTER_CHANGE_REGISTRY_NAME
Indicates that a notification should be issued when a change to a name is made in the cluster database.
CLUSTER_CHANGE_REGISTRY_SUBTREE
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
Indicates that a notification should be issued when a value of the specified cluster database key is changed or deleted.
CLUSTER_CHANGE_RESOURCE_DELETED
Indicates that a notification should be issued when a resource is deleted.
CLUSTER_CHANGE_RESOURCE_PROPERTY
Indicates that a notification should be issued when the properties of a resource change.
CLUSTER_CHANGE_RESOURCE_STATE
Indicates that a notification should be issued when a resource changes state.
hObject
[in] Handle to the object affected by the event specified in the dwFilter parameter. The type of handle depends on the value of dwFilter as is described in the following table:
Value of dwFilter | Value of hObject
CLUSTER_CHANGE_GROUP_DELETED | HGROUP
CLUSTER_CHANGE_GROUP_PROPERTY | HGROUP
CLUSTER_CHANGE_GROUP_STATE | HGROUP
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 that will be returned from GetClusterNotify when the requested event occurs.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, 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, will not cause notifications to be generated.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the new cluster name.

Return Values

ERROR_RESOURCE_PROPERTIES_STORED
The operation was successful.

If the operation was unsuccessful, SetClusterName returns a Win32 error value.

Remarks

The cluster name is the Name property of the core Network Name resource, 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


SetClusterQuorumResource

The SetClusterQuorumResource function sets 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] Pointer to the name of the device where the quorum resource resides.
dwMaxQuoLogSize
[in] Maximum size for the log file to be maintained by the quorum resource.

Return Values

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Node Management Functions

The node management functions in the Cluster API allow callers to change a node's state, perform operations, and retrieve information. The node management functions are implemented primarily by the Cluster Service's Membership Manager and are briefly described as follows:

Function | Description
CloseClusterNode | Closes a node by invalidating its handle.
ClusterNodeControl | Initiates an operation affecting a node.
EvictClusterNode | Deletes a node from the cluster database.
GetClusterNodeId | Returns the identifier of a cluster node.
GetClusterNodeState | Returns the current state of 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 by invalidating its handle.

BOOL WINAPI CloseClusterNode(
  HNODE hNode
);

Parameters

hNode
[in] Handle to an existing node.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterNodeControl

The ClusterNodeControl function initiates an operation affecting a node.

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 that will handle the operation.
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] Control code that defines the operation to be performed. For a list of the valid values for the dwControlCode parameter, see Control Codes for Nodes.
lplnBuffer
[in] Pointer to the input buffer with information needed for the operation, or NULL if no information is needed.
cblnBufferSize
[in] Number of bytes in the buffer pointed to by lplnBuffer.
lpOutBuffer
[out] Pointer to the output buffer with information resulting from the operation, or NULL if nothing needs to be returned.
cbOutBufferSize
[in] Number of bytes in the output buffer pointed to by lpOutBuffer.
lpcbBytesReturned
[in, out] Pointer to the number of bytes in the buffer pointed to by lpOutBuffer that were actually filled as a result of the operation. The caller can pass NULL for lpcbBytesReturned if ClusterNodeControl need not pass back the number of bytes in the output buffer.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer is not large enough to hold the data being returned. The lpcbBytesReturned parameter points to the size required for the output buffer.

If the operation was unsuccessful, ClusterNodeControl returns a Win32 error value.

Remarks

ClusterNodeControl is a general-purpose function for initiating an operation that affects a node. The scope of allowable operations is defined by the set of control codes specified for nodes. For a complete description of how to use control codes and control code functions, see Cluster Control Codes.

When ClusterNodeControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, EvictClusterNode returns a Win32 error value.

Remarks

To reinstate an evicted node, you must first remove Cluster Server from the node and then reinstall it. During installation, choose the Join an Existing Cluster option.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 contents 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

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 contents of lpcchNodeId to the required length.

If the operation was unsuccessful, GetClusterNodeId returns a Win32 error value.

Remarks

If hNode is set to NULL and the caller is running on an active cluster node, GetClusterNodeId 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 if the node's name is changed.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

If the operation was successful, GetClusterNodeState returns the current state of the node, which is represented by one of the following values:

State | Description
ClusterNodeUp | The node is operational.
ClusterNodeDown | The node is not operational.
ClusterNodeJoining | The node is in the process of joining a cluster.
ClusterNodePaused | The node has temporarily suspended activity.

If the operation was unsuccessful, GetClusterNodeState returns ClusterNodeStateUnknown. For more detailed information about the error, call the Win32 function GetLastError.

Remarks

When a node is trying to form or rejoin a cluster or is down, it is in the ClusterNodeDown state. A node that is down is not an active cluster member and it may or may not be running. The Cluster Service may have started and then failed, or may have failed to start completely.

When a node is operating as an active member of a cluster, it is in the ClusterNodeUp state. An node that is up responds to updates to the cluster database, can host and manage groups, and can maintain communication with other nodes in the cluster.

When a node is operating as an active member of a cluster but cannot host any resources or resource groups, it is in the ClusterNodePaused state. Nodes that are undergoing maintenance are typically placed in this state.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

NULL
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterNode returns a node handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, 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 failover 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResumeClusterNode

The ResumeClusterNode function requests that a node resume its cluster activity following a temporary suspension.

DWORD WINAPI ResumeClusterNode(
  HNODE hNode
);

Parameters

hNode
[in] Handle to the node to resume activity.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ResumeClusterNode returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Group Management Functions

The group management functions in the Cluster API provide access to each of the groups in a cluster. These functions allow callers to change a group's membership or state and retrieve a variety of information. The group management functions are implemented primarily by the Cluster Service's Resource and Failover Managers and are briefly described in the following table:

Function | Description
CloseClusterGroup | Closes a group by invalidating its handle, a handle returned from either OpenClusterGroup or CreateClusterGroup.
ClusterGroupCloseEnum | Closes a group enumerator object by invalidating its handle, a handle returned from ClusterGroupOpenEnum.
ClusterGroupControl | Initiates an operation that affects a group.
ClusterGroupEnum | Enumerates the resources in a group and/or the nodes that are possible 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 possible owners.
CreateClusterGroup | Adds a group to a cluster and returns a handle to the newly added group.
DeleteClusterGroup | Removes a group from a cluster.
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 by invalidating its handle, a handle returned from OpenClusterGroup or CreateClusterGroup.

BOOL WINAPI CloseClusterGroup(
  HGROUP hGroup
);

Parameters

hGroup
[in] Handle to the group to close.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterGroupCloseEnum

The ClusterGroupCloseEnum function closes a group enumerator object by invalidating its handle, a handle returned from ClusterGroupOpenEnum.

DWORD WINAPI ClusterGroupCloseEnum(
  HGROUPENUM hGroupEnum
);

Parameters

hGroupEnum
[in] Handle to the enumerator object to close.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterGroupCloseEnum returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterGroupControl

The ClusterGroupControl function initiates an operation that affects a group.

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] Control code that defines the operation to be performed. For a list of the valid values for the dwControlCode parameter, see Control Codes for Groups.
lplnBuffer
[in] Pointer to the input buffer with information needed for the operation, or NULL if no information is needed.
cblnBufferSize
[in] Number of bytes in the buffer pointed to by lplnBuffer.
lpOutBuffer
[out] Pointer to the output buffer with information resulting from the operation, or NULL if nothing need be returned.
cbOutBufferSize
[in] Number of bytes in the output buffer pointed to by lpOutBuffer.
lpcbBytesReturned
[in, out] Pointer to the number of bytes in the buffer pointed to by lpOutBuffer that were actually filled as a result of the operation. The caller can pass NULL for lpcbBytesReturned if ClusterGroupControl need not pass back the number of bytes in the output buffer.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer is not large enough to hold the data being returned. The lpcbBytesReturned parameter points to the size required for the output buffer.

If the operation was unsuccessful, ClusterGroupControl returns a Win32 error value.

Remarks

ClusterGroupControl is a general-purpose function for initiating an operation that affects a group. The scope of allowable operations is defined by the set of control codes specified for groups. For a complete description of how to use control codes and control code functions, see Cluster Control Codes.

When ClusterGroupControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterGroupEnum

The ClusterGroupEnum function enumerates the resources in a group and/or the nodes that are possible 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 lpcbName
);

Parameters

hGroupEnum
[in] Handle to a group enumerator object 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. Valid values are:
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 that are in the possible owners list of the group.
lpszResourceName
[out] Pointer to the name of the returned resource or node, including the terminating NULL character.
lpcbName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszResourceName parameter. This size should include the terminating NULL character. On output, pointer to the count of characters stored in the buffer, excluding the terminating NULL character.

Return Values

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 long enough to hold the required number of characters in the cluster component's name. ClusterGroupEnum sets the contents of the lpcbName parameter to the required buffer length.

If the operation was unsuccessful 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 possible owners.

HGROUPENUM WINAPI ClusterGroupOpenEnum(
  HGROUP hGroup,
  DWORD dwType
);

Parameters

hGroup
[in] Handle to the group to be enumerated.
dwType
[in] Bitmask describing the objects to be enumerated. Valid values are:
CLUSTER_GROUP_ENUM_CONTAINS
Enumerate all of the resources in the group identified by hGroup.
CLUSTER_GROUP_ENUM_NODES
Enumerate all of the nodes that are in the possible owners list of the group identified by hGroup.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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

NULL
The operation was unsuccessful. For more detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterGroup returns a group handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, DeleteClusterGroup returns a Win32 error value.

Remarks

Because the DeleteClusterGroup function only removes groups that are empty, a group must have no resources before it can successfully be deleted.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


GetClusterGroupState

The GetClusterGroupState function returns the current state of a group.

CLUSTER_GROUP_STATE WINAPI GetClusterGroupState(
  HGROUP hGroup,
  LPWSTR lpszNodeName,
  LPDWORD lpcbNodeName
);

Parameters

hGroup
[in] Handle to the group for which state information should be returned.
lpszNodeName
[out] Optional pointer to the name of the node in the cluster where the group identified by hGroup is currently online or NULL.
lpcbNodeName
[in, out] On input, pointer to a count of characters in the buffer pointed to by lpszNodeName, including the terminating NULL character. On output, pointer to a count of characters in the name contained in the buffer pointed to by lpszNodeName, excluding the terminating NULL character.

Return Values

If the operation was successful, GetClusterGroupState returns the current state of the group, which is represented by one of the following values:

State | Description
ClusterGroupFailed | The group is not operational but has not yet been taken offline.
ClusterGroupOnline | The group is operational.
ClusterGroupOffline | The group is not operational.
ClusterGroupPartialOnline | One or more of the resources in the group has been brought online.

If the operation was unsuccessful, this function returns ClusterGroupStateUnknown. For more detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The reassignment of ownership of the group has completed.
ERROR_IO_PENDING
The reassignment of ownership of the group is in progress.

If the operation was unsuccessful, MoveClusterGroup returns a Win32 error value.

Remarks

The return value from MoveClusterGroup indicates whether or not the group has successfully changed ownership. It does not imply anything about the state of the group and all of its resources. That is, if the group was in the online state prior to the move, it may or may not be online on its new node when MoveClusterGroup returns, regardless of the return value.

After the ownership of the group has been successfully reassigned, MoveClusterGroup returns and the Cluster Service attempts to restore the group and its resources to its previous state on the new node. For example, if before the move the group was partially online with an offline Generic Service resource and an online Physical Disk resource, after the move the Cluster Service attempts to bring the Physical Disk resource online on the new node. The Generic Service resource remains offline.

Since the ERROR_SUCCESS return value indicates only that the ownership of the group has changed, callers of MoveClusterGroup must assume that ERROR_SUCCESS implies ERROR_IO_PENDING and wait for completion. The caller may wait by either:

  • Polling the state of each resource in the group.
  • Creating a notification port and waiting for the appropriate CLUSTER_CHANGE_RESOURCE_STATE events to arrive.

When all of the resources in the group have been brought online, the caller can assume that the move operation has completed and that the resources have been restored to their original state.

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


OfflineClusterGroup

The OfflineClusterGroup function takes an online group offline.

DWORD WINAPI OfflineClusterGroup(
  HGROUP hGroup
);

Parameters

hGroup
[in] Handle to the group to be taken offline.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_IO_PENDING
The operation is in progress.

If the operation was unsuccessful, OfflineClusterGroup returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


OnlineClusterGroup

The OnlineClusterGroup function brings an offline 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

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 unsuccessful, OnlineClusterGroup can also return a Win32 error value.

Remarks

If the group cannot be brought online on the node identified by the hDestinationNode parameter, OnlineClusterGroup fails.

If the hDestinationNode parameter is set to NULL, OnlineClusterGroup brings the group online on the current node.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

NULL
The operation was unsuccessful. For detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterGroup returns a group handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, SetClusterGroupName returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, SetClusterGroupNodeList returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Resource Management Functions

The resource management functions in the Cluster API allow callers to perform a wide variety of operations on one or more resources. For example, resource management functions enable callers to retrieve information about dependencies, to create and delete resources, and to initiate an operation defined with one of the many resource control codes.

The following functions manage resources in a cluster:

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 by invalidating its handle, a handle returned from either OpenClusterResource or CreateClusterResource.
ClusterResourceCloseEnum | Closes a resource enumerator object by invalidating its handle, a handle returned from ClusterResourceOpenEnum.
ClusterResourceControl | Initiates an operation affecting a resource.
ClusterResourceEnum | Enumerates a resource's dependent resources and/or nodes, returning the name of one 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.
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 node from the list of nodes that can host a resource.
RemoveClusterResourceNode | Removes a dependency relationship between two resources.
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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, AddClusterResourceDependency returns a Win32 error value.

Remarks

A dependency relationship 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.


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.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, AddClusterResourceNode returns a Win32 error value.


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 or may not depend.

Return Values

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

In order for the resource identified by hResource to be dependent on the resource identified by hResourceDependent:

  • 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ChangeClusterResourceGroup returns a Win32 error value.

Remarks

Both the group that the resource currently belongs to and its new group must be owned by the same node regardless of the resource's state.

If the resource identified by hResource has dependencies, all of the resources in its dependency tree will be moved to the group identified by hGroup. That is, if Resource A depends on Resource B and Resource B depends on Resource C, a call to ChangeClusterResourceGroup with hResource representing either Resource A, Resource B, or Resource C will result in all three resources being moved.


CloseClusterResource

The CloseClusterResource function closes a resource by invalidating its handle, a handle returned from either OpenClusterResource or CreateClusterResource.

BOOL WINAPI CloseClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource to be closed.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful. For detailed information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterResourceCloseEnum

The ClusterResourceCloseEnum function closes a resource enumerator object by invalidating its handle, a handle returned from ClusterResourceOpenEnum.

DWORD WINAPI ClusterResourceCloseEnum(
  HRESENUM hResEnum
);

Parameters

hResEnum
[in] Handle to the resource enumerator to be closed.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterResourceCloseEnum returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterResourceControl

The ClusterResourceControl function initiates an operation affecting a resource.

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 controlled.
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] Resource control code that defines the operation to be performed. For a list of the valid values for the dwControlCode parameter, see Control Codes for Resources.
lpInBuffer
[in] Pointer to a 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 a buffer with information resulting from the operation, or NULL if nothing need be returned.
cbOutBufferSize
[in] Number of bytes in the buffer pointed to by lpOutBuffer.
lpcbBytesReturned
[in, out] Pointer to the number of bytes of lpOutBuffer filled in as a result of the operation. The caller can pass NULL for lpcbBytesReturned if ClusterResourceControl need not pass back the number of bytes in the output buffer.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_MORE_DATA
The output buffer pointed to by lpOutBuffer is not large enough to hold the data being returned. The lpcbBytesReturned parameter points to the size required for the output buffer.

If the operation was unsuccessful, ClusterResourceControl returns a Win32 error value.

Remarks

ClusterResourceControl is a general-purpose function for initiating an operation that affects a resource. The scope of allowable operations is defined by the set of control codes specified for resources. For a complete description of how to use control codes and control code functions, see Cluster Control Codes.

When ClusterResourceControl returns ERROR_MORE_DATA, set cbOutBufferSize to the number of bytes pointed to by lpcbBytesReturned and call the function again.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterResourceEnum

The ClusterResourceEnum function enumerates a resource's dependent resources and/or nodes, returning the name of one object with each call.

DWORD WINAPI ClusterResourceEnum(
  HRESENUM hResEnum,
  DWORD dwIndex,
  LPDWORD lpdwType,
  LPWSTR lpszName,
  LPDWORD lpcchName
);

Parameters

hResEnum
[in] Handle to a resource enumerator object — a 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. Valid types are:
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 the name of the returned object, including the terminating NULL character.
lpcchName
[in, out] Pointer to the count of characters in the buffer pointed to by the lpszName parameter. This size should include the terminating NULL character. On output, pointer to the count of characters stored in the buffer, excluding the terminating NULL character.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_NO_MORE_ITEMS
There are no more objects to be returned.

If the operation was unsuccessful due to a problem other than not having any more objects to return, ClusterResourceEnum returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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:
CLUSTER_RESOURCE_ENUM_DEPENDS
Enumerate resources that the resource identified by hResource directly depends on.
CLUSTER_RESOURCE_ENUM_PROVIDES
Enumerate resources that directly depend on the resource identified by hResource.
CLUSTER_RESOURCE_ENUM_NODES
Enumerate nodes that can host the resource identified by hResource.

Return Values

NULL
The operation was unsuccessful. For detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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

NULL
The operation was not successful. For detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, CreateClusterResource returns a resource handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


DeleteClusterResource

The DeleteClusterResource function removes an offline resource from a cluster.

DWORD WINAPI DeleteClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to an offline resource.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_RESOURCE_NOT_OFFLINE
The resource identified by hResource is not currently offline.

If the operation was unsuccessful, DeleteClusterResource can also return a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, 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 FailClusterResource to test their policies for restarting resources and groups.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


GetClusterResourceNetworkName

The GetClusterResourceNetworkName function retrieves the network name from 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] Pointer to a buffer containing a NULL-terminated character string containing the network name of the Network Name resource.

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 terminating NULL character.

Return Values

TRUE
The operation was successful.
FALSE
The operation was unsuccessful.

Remarks

Applications and resource DLLs call GetClusterResourceNetworkName to enumerate the dependencies of the resource identified by hResource in an attempt to find a Network Name resource on which the resource depends. GetClusterResourceNetworkName can help third-party developers determine the network name that their applications should be using.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 to the resource for which state information should be returned.
lpszNodeName
[out] Pointer to the name of the node in the cluster where the group of the resource identified by hResource is currently online or NULL, if the node name is not required.
lpcchNodeName
[in, out] On input, pointer to a count of characters in the buffer pointed to by lpszNodeName. On output, pointer to a count of characters in the name contained in the buffer pointed to by lpszNodeName, excluding the terminating NULL character.
lpszGroupName
[out] Pointer to the name of the group that has as a member the resource identified by hResource. This parameter can be NULL if the group name is not required.
lpcchGroupName
[in, out] On input, pointer to a count of characters in the buffer pointed to by lpszGroupName, including the terminating NULL character. On output, pointer to a count of characters stored in the buffer pointed to by lpszGroupName, excluding the terminating NULL character. If lpszGroupName is NULL, this parameter is ignored.

Return Values

If the operation was successful, 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.

If the operation was unsuccessful, this function returns ClusterResourceStateUnknown. ClusterResourceStateUnknown indicates that an error has occurred and the exact state of the resource could not be determined. For more detailed information about the error, call the Win32 function GetLastError.

Remarks

Resource state changes can occur during the failover process or when the administrator manually makes a state transition. When a group is failed over, the states of each resource are altered according to their dependencies on the other resources in the group. The Resource Monitor is responsible for managing these state transitions in response to Cluster Service commands and a resource DLL's response when calls are made to its IsAlive and LooksAlive entry points.

The initial state for any resource is the ClusterResourceOffline state. When a resource is offline, it is unavailable for use by a client or another resource. The Cluster Service may request that the Resource Monitor bring an offline resource online.

To place a resource in the ClusterResourceOffline state, the Resource Monitor calls the resource's Offline entry point function and unloads the resource DLL. The resource is removed from the Resource Monitor's list and any Resource Monitor state related to that resource is discarded.

When a resource is in the ClusterResourceOnline state, it is available for use.

When a resource is in one of the pending states, either ClusterResourceOfflinePending or ClusterResourceOnlinePending, it is in the process of either being brought online or taken offline. The pending states are transitional. If after a predetermined amount of time the resource cannot be brought online or taken offline, the resource is set to the ClusterResourceFailed state.

The pending states are entered whenever the Online or Offline entry points return ERROR_IO_PENDING. The pending states are expected to last less than a few seconds. If the resource DLL does not complete the transition from a pending state to a more stable state within a fixed period of time (typically three minutes), the Cluster Service's Resource Manager terminates the resource by calling its Terminate entry point function and tries again according to the policies defined for the resource.

A resource enters the ClusterResourceFailed state if either its IsAlive or LooksAlive entry point fails. The Cluster Service is subsequently notified by the Resource Monitor which continues to poll the resource to detect transient faults. When the resource recovers, the Resource Monitor brings the resource back online unless the Cluster Service explicitly asks the Resource Monitor to take it offline.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


OfflineClusterResource

The OfflineClusterResource function takes an online resource offline.

DWORD WINAPI OfflineClusterResource(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource to be taken offline.

Return Values

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 unsuccessful, OfflineClusterResource can also return a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

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 unsuccessful, OnlineClusterResource can also return a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of the resource to be opened.

Return Values

NULL
The operation was unsuccessful. For detailed information about the error, call the Win32 function GetLastError.

If the operation was successful, OpenClusterResource returns a handle to the opened resource.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 which should be removed from the list of potential host nodes belonging to the resource identified by hResource.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, RemoveClusterResourceNode returns a Win32 error value.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, RemoveClusterResourceDependency returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, SetClusterResourceName returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Cluster Database Management Functions

The cluster database management functions allow a cluster-aware application or resource DLL to access and update the cluster database. The cluster database management functions provide one way to access the cluster database. The other way is through the control code functions of the Cluster API:

ClusterResourceControl

ClusterResourceTypeControl

ClusterGroupControl

ClusterNodeControl

It is recommended that applications and resource DLLs use the control code functions to access the cluster database. The cluster database management functions should only be used when the control code functions are inadequate. Never use the Win32 registry functions. Although the registry functions are similar to the cluster database management functions, they are unsupported in the cluster environment because they do not support data replication or logging.

The following functions can be used to manage the cluster database:

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.
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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegCloseKey returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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 only be set to:
REG_OPTION_VOLATILE
The opened or created key is volatile; the information is stored in memory and is not preserved when the system is restarted.
samDesired
[in] Access mask that specifies the desired security access for the new key. Valid values are:
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 contents 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. Valid values are:
REG_CREATED_NEW_KEY
The key did not exist and was created.
REG_OPENED_EXISTING_KEY
The key existed and was opened.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegCreateKey returns a Win32 error value.

Remarks

Callers should call ClusterRegCloseKey to close the key handle created by ClusterRegCreateKey when they are done with it. For more information, see the related Win32 registry functions RegCreateKey and RegCreateKeyEx.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegDeleteKey returns a Win32 error value.

Remarks

Unlike the RegDeleteKey function that deletes a key from the system registry on Microsoft® Windows® 95 operating systems, ClusterRegDeleteKey cannot delete a key that has one or more subkeys. This behavior is identical to the behavior of RegDeleteKey on the Microsoft® Windows NT® Server network operating system.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of the value to be removed.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegDeleteValue returns a Win32 error value.

Remarks

For more information, see the related Win32 function RegDeleteValue.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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] Currently open key, or NULL. If NULL is specified, ClusterRegEnumKey enumerates keys from the root of the cluster database on the node on which the application is running.
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 will have 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 terminating NULL character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.
lpcchName
[in, out] On input, pointer to a count of characters in the buffer pointed to by the lpszName parameter including the terminating NULL character. On output, pointer to a count of characters stored in the buffer, excluding the terminating NULL character.
lpftLastWriteTime
[out] Pointer to the last time the enumerated subkey was modified.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_NO_MORE_ITEMS
There are no more subkeys to be returned.

If the operation was unsuccessful due to a problem other than not having any more subkeys to return, ClusterRegEnumKey returns a Win32 error value.

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 will have an arbitrary index. This means that ClusterRegEnumValue may return values in any order.

lpszValueName
[out] Pointer to the name of the returned value, including the terminating NULL character.
lpcchValueName
[in, out] On input, pointer to a count of characters in the buffer pointed to by the lpszValueName parameter including the terminating NULL character. On output, pointer to a count of characters stored in the buffer, excluding the terminating NULL character.
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:
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 stored in the buffer, excluding the terminating NULL character. This parameter can be NULL only if lpbData is NULL.

Return Values

ERROR_SUCCESS
The operation was successful.
ERROR_NO_MORE_ITEMS
There are no more values to be returned.

If the operation was unsuccessful due to a problem other than not having any more values to return, ClusterRegEnumValue returns a Win32 error value.

Remarks

For more information, see the related Win32 function RegEnumKey.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterRegGetKeySecurity

The ClusterRegGetKeySecurity function returns a copy of the security descriptor protecting the specified cluster database key.

LONG WINAPI ClusterGetKeySecurity(
  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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegGetKeySecurity returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterRegOpenKey

The ClusterRegOpenKey function opens a 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 string specifying the name of a subkey that ClusterRegOpenKey opens or creates. The contents of lpszSubKey must be a subkey of the key identified by hKey, must not begin with the backslash character ( \ ), and must not be NULL.
samDesired
[in] Access mask that specifies the desired security access for the new key.
phkResult
[out] Pointer to a handle to the opened or created key.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, 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. For more information, see the related Win32 functions RegOpenKey and RegOpenKeyEx.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusterRegQueryInfoKey

The ClusterRegQueryInfoKey function returns information about a cluster database key.

LONG WINAPI ClusterRegQueryInfoKey(
  HKEY hKey,
  LPDWORD lpcSubKeys,
  LPDWORD lpcbMaxSubKeylen,
  LPDWORD lpcValues,
  LPDWORD lpcbMaxValueNameLen,
  LPDWORD lpcbMaxValueLen,
  LPDWORD lpcbSecurityDescriptor,
  PFILETIME lpftLastWriteTime
);

Parameters

hKey
[in] Handle to a cluster database key.
lpcSubKeys
[in] Pointer to a count of the number of subkeys contained by the cluster database key represented by hKey.
lpcbMaxSubKeylen
[in] Pointer to a count of the number of characters in the subkey with the longest name, excluding the terminating NULL character. This parameter can be NULL.
lpcValues
[in] Pointer to a count of the number of values associated with the cluster database key. This parameter can be NULL.
lpcbMaxValueNameLen
[in] Pointer to a count of the number of characters in the cluster database key's longest value name, excluding the terminating NULL character. This parameter can be NULL.
lpcbMaxValueLen
[in] Pointer to a count of the number of bytes of the longest data component among the cluster database key's values. This parameter can be NULL.
lpcbSecurityDescriptor
[in] Pointer to a count of the number of bytes in the cluster database key's security descriptor. This parameter can be NULL.
lpftLastWriteTime
[in] Pointer to the time that the cluster database key or any of its value entries was last modified. This parameter can be NULL.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegQueryInfoKey returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of the value to be queried.
lpdwValueType
[out] Pointer to the key's value type. The value returned through this parameter will be one of the following:
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.

The lpdwType parameter can be NULL if the type is not required.

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 contents of lpbData if the caller passes in a valid pointer.

The lpcbData parameter can be NULL only if lpbData is also NULL.

Return Values

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 contents of lpcbData.
ERROR_NO_MORE_ITEMS
There are no more values.

Remarks

If lpbData is NULL, ClusterRegQueryValue returns ERROR_SUCCESS and stores the size of the value's data in the contents 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 will also include a NULL terminator.

For more information, see the related Win32 function RegQueryValue.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 contents 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

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegSetKeySecurity returns a Win32 error value.

Remarks

ClusterRegSetKeySecurity will generate a CLUSTER_CHANGE_REGISTRY_ATTRIBUTES event for all registered notification ports.

For more information, see the related Win32 function RegSetKeySecurity.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 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:
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 lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating NULL character.

Return Values

ERROR_SUCCESS
The operation was successful.

If the operation was unsuccessful, ClusterRegSetValue returns a Win32 error value. For detailed information about the error, call the Win32 function GetLastError.

Remarks

For more information, see the related Win32 function RegSetValue.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 desired security access for the new key.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 desired security access for the new key.

Return Values

NULL
The operation was unsuccessful. For detailed 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.


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 desired security access for the new key.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 desired security access for the new key.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 desired security access for the new key.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 desired security access for the opened key.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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 the name of a resource type.
samDesired
[in] Access mask that describes the desired security access for the opened key.

Return Values

NULL
The operation was unsuccessful. For more detailed 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Resource API

The Resource API defines functions, structures, and macros that allow the Cluster Service to communicate with resources. The communication is indirect; the Cluster Service initiates requests with a Resource Monitor and the Resource Monitor passes them on to the resource. Status and event information are passed back from the resource DLL to the Cluster Service.

The following diagram shows how control flows from the Cluster Service through the Resource Monitor and a resource DLL to resources. The diagram shows four resource DLLs, three for Cluster Service resource types and one for a resource type defined by a third-party developer.

The Resource API consists of:

  • Entry point functions
  • Callback functions
  • Structures and macros


Resource API Entry Point Functions

The Resource API entry point functions are implemented in a resource DLL to allow a Resource Monitor to manage its resources. Most of the entry point functions are required, but some are optional depending on the functionality provided by the resource. 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 following table briefly describes the entry point functions in the Resource API.

Entry point function | Description
Arbitrate | Allows a node to attempt to regain ownership of a quorum resource.
Close | Closes a resource.
IsAlive | Determines if a resource is available for use.
LooksAlive | Determines if a resource appears to be available for use.
Offline | Marks a resource as unavailable for use after cleanup processing is completed.
Online | Marks a resource as available for use.
Open | Opens a resource.
Release | Releases a quorum resource from arbitration.
ResourceControl | Performs an operation that applies to a resource.
ResourceTypeControl | Performs an operation that applies to a resource type.
Startup | Loads a resource's resource DLL and returns a structure containing a function table and version number.
Terminate | Marks a resource as unavailable for use without waiting for cleanup processing to finish.

The function table returned by Startup contains pointers to each of the entry point functions. Startup is the only entry point function that is exported. The other entry point functions are accessed through the function table.

A resource DLL is non-reentrant for a given instance of a resource. That is, with one exception, resource DLL developers should expect each of their entry points to be called only once for each resource instance. The exception is Terminate. Calls to Terminate can occur at any time, even if other threads within the resource DLL are blocked waiting for an Online or Offline call to complete.

A resource DLL is reentrant with respect to resource identifiers, represented by the RESID data type. Resource identifiers are returned from the Open entry point function and supplied to all other entry points to identify a resource. Resource DLLs that handle multiple resource identifiers must be prepared to synchronize the use of any shared global data.


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 the arbitration fails and control of the quorum resource is lost after being successfully gained.

Return Values

ERROR_SUCCESS
The arbitration was successful and the quorum resource remains defended.
Win32 error code
The arbitration was not successful.

Notes to Implementers

Arbitrate 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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.

Notes to Implementers

Expect Close to be called only once for a particular resource. In your implementation, deallocate all of the structures that were allocated by any of the following functions:

  • Open
  • Online
  • ResourceControl
  • ResourceTypeControl

If the resource to be closed is not yet offline, call Terminate to forcibly take it offline.

Make your implementation of Close take less than 300 milliseconds to complete if at all possible. However, if this time limit is exceeded, the Cluster Service handles the situation properly.

Call the Win32 function SetLastError just before returning.

Example

In Cluster Server's File Share resource DLL, Close uses the resource identifier in ResourceId as an index into a resource table that keeps track of all of the resources that are handled by the DLL. Close retrieves the address of the resource structure, deallocates it, and enters NULL in the appropriate entry in the resource table to indicate that the entry was indeed deallocated.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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

TRUE
The resource is online and functioning properly.
FALSE
The resource is not functioning properly.

Notes to Implementers

Unlike LooksAlive, which determines whether a resource appears to be available, IsAlive determines whether the resource is in fact available. The set of procedures that you need to implement to determine availability depends on your resource. You can implement a simple procedure as Cluster Server does in its resource DLL for the Generic Application resource, which determines only if the application is running. Most likely you will want to do more, such as determining if data can be read or written and checking for a particular state.

Make your implementation of IsAlive take 50 milliseconds or less to complete if at all possible. At the very most, you should not allow IsAlive to block processing for more than 300 milliseconds. However, if your implementation must take longer than 300 milliseconds:

  1. Have a separate thread dedicated to performing the polling operation.
  2. Return the result of the last poll performed by the separate thread.

Call the Win32 function SetLastError just before returning.

Example

In Cluster Server's File Share resource DLL, IsAlive uses the resource identifier in ResourceId as an index into a resource table that keeps track of all of the resources that are handled by the DLL. IsAlive retrieves the address of the resource structure and then makes a call to the Win32 function NetShareGetInfo to thoroughly check if the resource is alive.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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

TRUE
The resource is probably online and available for use.
FALSE
The resource is not functioning properly.

Notes to Implementers

Unlike IsAlive, which determines whether a resource is in fact available for use, LooksAlive determines whether the resource appears to be available. LooksAlive should involve a cursory check that takes l50 milliseconds or less to complete if possible. At the very most, you should not allow LooksAlive to block processing for more than 300 milliseconds. However, if your implementation must take longer than 300 milliseconds:

  1. Have a separate thread dedicated to performing the polling operation.
  2. Return the result of the last poll performed by the separate thread.

If LooksAlive fails, the Resource Monitor will call your IsAlive entry point function to determine if the resource is indeed not functioning.

Call the Win32 function SetLastError just before returning.

Example

In Cluster Server's File Share resource DLL, LooksAlive uses the resource identifier in ResourceId as an index into a resource table that keeps track of all resources that are handled by the DLL. LooksAlive retrieves the address of the resource structure and then calls the IsAlive entry point to perform its check of the resource.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


Offline

The Offline entry point function marks a resource as unavailable for use after cleanup processing is completed.

DWORD WINAPI Offline(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the resource to be taken offline.

Return Values

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 unsuccessful for other reasons, Offline should return a Win32 error value.

Remarks

If Offline returns a Win32 error value, the Resource Monitor logs an event and calls the Terminate entry point.

Notes to Implementers

Your implementation of Offline should take less than 300 milliseconds to complete. However, if it requires more than 300 milliseconds:

  1. Start a separate thread to complete the request.
  2. Return ERROR_IO_PENDING immediately.
  3. Make the thread that is processing the request periodically report status information to the Resource Monitor by calling the SetResourceStatus callback function. Keep calling SetResourceStatus until one of the following two situations occurs:
    • The resource is placed in the ClusterResourceOffline state.
    • The request has exceeded the time limit, set to three minutes by default. This time limit is stored in the PendingTimeout common property.

A time-out causes the Resource Monitor to call Terminate to abort the offline request. Make sure that all necessary cleanup operations have finished before you return from Offline.

Example

In Cluster Server's File Share resource DLL, Offline uses the resource identifier in ResourceId as an index into a resource table that keeps track of all resources handled by the DLL. Offline retrieves the address of the resource structure for the appropriate resource and uses the information in this resource structure to call the Win32 function NetShareDel to remove the share name from the server.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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. Usually, this is a handle to a system object, such as a process. On output, EventHandle contains a handle that is signaled when the resource detects a failure. For example, if EventHandle represents a process and the process is terminated, the EventHandle is signaled and the Resource Monitor will be notified.

EventHandle can also be set to NULL on output, indicating that the resource does not support asynchronous event notification.

Return Values

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.
ERROR_IO_PENDING
The request is pending and a thread has been activated to process the online request.

Notes to Implementers

Refresh the private properties of the resource to be brought online in your Online entry point function. It is important to get a more recent copy of the properties you initially received from your Open entry point function in the event that changes have occurred since that time. To refresh these private properties, call ClusterResourceControl twice, passing CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES in the dwControlCode parameter for the first call and CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES for the second call.

Make your implementation of Online take less than 300 milliseconds to complete if at all possible. However, if your implementation requires more than 300 milliseconds:

  1. Start a separate thread to complete the request.
  2. Return ERROR_IO_PENDING immediately.
  3. Make the thread that is processing the request periodically report status information to the Resource Monitor by calling the SetResourceStatus callback function. Keep calling SetResourceStatus until one of these situations occurs:
    • The resource is placed in the ClusterResourceOnline state.
    • The request has exceeded the three minute default time limit. A time out causes the Resource Monitor to call Terminate to abort the online request. The time limit is stored in the PendingTimeout common property.

Return a valid handle in EventHandle to use event notification to inform the Resource Monitor of a resource's state. When a resource DLL supports event notification, the Resource Monitor will still call its IsAlive function to thoroughly check for status but will not call LooksAlive.

Whenever possible, do not handle node-specific properties. If you must maintain node-specific properties, record them in the cluster database under a local machine key based on the node identifier. You can retrieve the node identifier by calling GetClusterNodeId.

For example, your resource DLL for managing a disk resource may need to maintain different drive names for each node if the nodes maintain different numbers of disks. That is, the physical drive may assume one name on one node and a different name on another node. Handle this situation by having cluster database keys for each of the node's computer names, and parse for additional parameters under the node-specific cluster database keys which are based on the node identifier.

Example

In Cluster Server's File Share resource DLL, Online uses the resource identifier in ResourceId as an index into a resource table that keeps track of all resources handled by the DLL. Online retrieves the address of the resource structure for the appropriate resource and uses the information in this resource structure to call the Win32 function NetShareAdd to add the share name to the server.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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 unsuccessful, Open returns NULL.

Remarks

The Open entry point 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.

Notes to Implementers

Make your implementation of Open complete as quickly as possible, preferably in under 300 milliseconds. However, if you require a longer processing time, this situation is handled properly by the Cluster Service.

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 or SetResourceStatus callback functions.

Open should allocate all of the structures necessary to bring the new resource online and retrieve its private properties. To retrieve the private properties of a resource, call ClusterResourceControl twice, passing CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES in the dwControlCode parameter for the first call and CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES for the second call. Resource DLLs should also retrieve their private properties in their Online function, a function that can be called repeatedly for a resource.

To make sure that the resource is in the offline state when Open returns, read the resource's PersistentState property. This is important if a resource cannot be online on more than one node simultaneously, such as when two nodes cannot simultaneously use the same IP address. If there is no chance that the resource could be online prior to the start of the Cluster Service, then taking the resource offline in your implementation of Open is not necessary.

Whenever possible, do not handle node-specific properties. If you must maintain node-specific properties, record them in the cluster database under a local machine key based on the node identifier. You can retrieve the node identifier by calling GetClusterNodeId.

For example, your resource DLL for managing a disk resource may need to maintain different drive names for each node if the nodes maintain different numbers of disks. That is, the physical drive may assume one name on one node and a different name on another node. Handle this situation by having cluster database keys for each of the node's computer names, and parse for additional parameters under the node-specific cluster database keys which are based on the node identifier.

Call the Win32 function SetLastError just before returning.

Example

In Cluster Server's File Share resource DLL, Open allocates a resource structure to contain the ShareName and Path properties. Open queries the cluster database using the functions in the Cluster API to find these properties and then saves them in the resource structure, saving the address of the resource structure in a global resource table. Open returns the index as the resource identifier.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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

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

Release 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.

Notes to Implementers

Attempt to make your implementation of Release finish in less than 300 milliseconds.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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. For a list of the valid values for the ControlCode parameter, see Control Codes for Resources.
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] Number of bytes in the buffer pointed to by OutBuffer that actually contain data.

Return Values

ERROR_SUCCESS
The operation associated with ControlCode was completed successfully.
ERROR_INVALID_FUNCTION
The resource DLL may not support the operation represented by ControlCode. In some cases this is a signal to the Resource Monitor for it to process the request.

If the operation was unsuccessful, ResourceControl returns a Win32 error value.

Notes to Implementers

ResourceControl should be implemented by all resource DLLs. However, it is not necessary to provide code to handle all of the control codes that are defined for resources. As a minimum, you should support the following control codes that manipulate private properties:

  • CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES

Without support for CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES, you will not be able to set nonstring private properties on a newly created resource using the command-line tool CLUSTER.EXE. Without support for CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES, you will not be able to validate the properties before setting them.

Without support for CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES, Cluster Administrator will not be able to automatically validate your private properties before setting them.

If resources handled by your resource DLL have required dependencies, you must support CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES.

If your resource DLL needs to replicate a portion of the system registry, you must support CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS.

Support for any of the other control codes is optional. To determine how and why to support a particular control code, see its reference entry in the documentation. It is preferable not to provide support for some of the codes because they depend on the standard processing that the Resource Monitor supplies. In particular, do not include support for CLUSCTL_RESOURCE_GET_CHARACTERISTICS because it is important not to override the processing provided by the Resource Monitor.

To request that the Resource Monitor process a control code, return ERROR_INVALID_FUNCTION. You can return this value for a control code regardless of whether you include support for the code in ResourceControl. Some resource DLLs support a control code to augment the functionality that the Resource Monitor supplies.

If at all possible, make your implementation of ResourceControl finish in less than 300 milliseconds.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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 Control Codes for Resource Types.
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

ERROR_SUCCESS
The operation indicated by ControlCode was completed successfully.
ERROR_INVALID_FUNCTION
The resource DLL may not support the operation represented by ControlCode. In some cases this is a signal to the Resource Monitor for it to process the request.

If the operation was unsuccessful, ResourceTypeControl should return a Win32 error value.

Notes to Implementers

ResourceTypeControl should be implemented by all resource DLLs. However, it is not necessary to provide code to handle all of the control codes that are defined for resource types. As a minimum, you should support the following control codes that manipulate private properties:

  • CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES

If your resource type has required dependencies, you must support CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES.

If your resource type needs to replicate a portion of the system registry, you must support CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS.

Support for any of the other control codes is optional. To determine how and why to support a particular control code, see its reference entry in the documentation. It is preferable not to provide support for some of the codes because they depend on the standard processing that the Resource Monitor supplies. In particular, do not include support for CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS because it is important not to override the processing provided by the Resource Monitor.

To request that the Resource Monitor process a control code, return ERROR_INVALID_FUNCTION. You can return this value for a control code regardless of whether you include support for the code in ResourceTypeControl. Some resource DLLs support a control code to augment the functionality that the Resource Monitor supplies.

If at all possible, make your implementation of ResourceTypeControl finish in less than 300 milliseconds.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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 Cluster Server.
MaxVersionSupported
[in] Maximum version of the Resource API supported by Cluster Server.
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

ERROR_SUCCESS
The request was successful.
ERROR_REVISION_MISMATCH.
The resource does not support a version that falls in the range identified by the MinVersionSupported and MaxVersionSupported parameters.

If the operation was unsuccessful, Startup should return a Win32 error value.

Remarks

The Startup entry point function returns a function table that describes:

  • The supported interface version of the Resource API.
  • 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.

Notes to Implementers

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.

Attempt to make your implementation of Startup finish in less than 300 milliseconds.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


Terminate

The Terminate entry point function immediately marks a resource as unavailable for use without waiting for cleanup processing to complete.

VOID WINAPI Terminate(
  RESID ResourceId
);

Parameters

ResourceId
[in] Resource identifier for the resource to be made unavailable.

Return Values

None.

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.

Notes to Implementers

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

In Cluster Server's File Share resource DLL, Terminate uses the resource identifier in ResourceId as an index into a resource table that keeps track of all resources that are handled by the DLL. Terminate retrieves the address of the resource structure for the appropriate resource and uses the information in this resource structure to call the Win32 function NetShareDel to remove the share name from the server.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


Resource API Callback Functions

The Resource API provides four callback functions, three that are implemented by the Resource Monitor and called by a resource DLL and one that is implemented by a resource DLL and called by the Cluster Service. A resource DLL invokes a Resource Monitor callback function to report status and to log events. A resource DLL implements the ResourceCallback function to perform tasks in response to the cluster utility function ResUtilEnumResources enumerating resources.

These functions are briefly described as follows:

Callback function | Description
LogEvent | Records an event for a resource.
QuorumResourceLost | Reports that control of the quorum resource has been lost.
ResourceCallback | Called by the cluster utility function ResUtilEnumResources for each resource that it enumerates to perform resource-specific tasks.
SetResourceStatus | Updates the status of a resource.


LogEvent

The LogEvent callback function records an event for a resource.

VOID WINAPI LogEvent(
  RESOURCE_HANDLE ResourceHandle,
  LOG_LEVEL LogLevel,
  LPCWSTR FormatString
);

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 is for information only. Valid values are shown next, in order from least to most severe:
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] Pointer to a formatted Unicode string that includes the information to be recorded. This string must be in the same format as is passed to the Win32 function FormatMessage.

Return Values

None.

Remarks

The LogEvent function is implemented by the Resource Monitor and called by a resource DLL to report events and errors to the cluster debugging log. Resource DLLs receive a pointer to the LogEvent function as an input parameter to their Startup entry point function.

To enable the cluster debugging log:

  • Set the CLUSTERLOG environment variable to a complete path identifying the location of the log file. The default name for the log file is cluster.log and the default location is the cluster directory.
  • Set the size of the log file in the ClusterLogSize entry in the cluster database under HKEY_LOCAL_MACHINE\Cluster. The size is a DWORD value that indicates the number of megabytes that the log file can hold. If this value is set to zero, logging is disabled.

LogEvent does not write entries to the Microsoft® Windows NT® event log. To report events in the Windows NT event log, a resource DLL must call the Win32 function ReportEvent.

The format of the logged message looks like:

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


QuorumResourceLost

The QuorumResourceLost 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

None.

Remarks

The QuorumResourceLost function is called by a resource DLL to notify the Resource Monitor that control of the quorum resource has been lost in the Arbitrate entry point function. A pointer to the Resource Monitor's QuorumResourceLost function is passed to a quorum resource DLL in the call to Arbitrate.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


ResourceCallback

The ResourceCallback function is called by the cluster utility function ResUtilEnumResources for each resource that it enumerates to perform resource-specific tasks.

DWORD ResourceCallback(
  RESOURCE_HANDLE hOriginal,
  RESOURCE_HANDLE hResource,
  PVOID lpParams
);

Parameters

hOriginal
[in] Handle identifying the original resource, the resource identified by hSelf in ResUtilEnumResources. If hSelf is specified as NULL, hOriginal will also be NULL.
hResource
[in] Handle to a resource of the same type as the original resource.
lpParams
[in] Pointer to the parameter passed to ResUtilEnumResources.

Return Values

ERROR_STATUS
The operation associated with the ResourceCallback function was successful.
If the operation is unsuccessful, ResourceCallback returns one or more Win32 error values that are appropriate for the functionality included in the callback. For example, the IIS Virtual Root resource DLL's implementation of ResourceCallback returns ERROR_DUP_NAME for a duplicate resource error and ERROR_INVALID_PARAMETER for a parameter error.

Notes to Implementers

If a non-NULL value is specified for hSelf in the call to ResUtilEnumResources, your ResourceCallback function will be invoked for each resource except the hSelf resource. Also, if lpszResourceType is specified in the call to ResUtilEnumResources, it will only be called for resources of that type.

Implement whatever tasks make sense for your resource DLL. For example, Cluster Server's Print Spooler resource DLL checks that the group for the resource contains a single Print Spooler resource. The IIS Virtual Root resource DLL validates that the resource's properties are unique and returns ERROR_DUP_NAME if the resource is the same as the resource identified by hOriginal.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


SetResourceStatus

The SetResourceStatus function is called to update the status of a resource.

VOID 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

None.

Remarks

Resource DLLs call SetResourceStatus 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.

Notes to Implementers

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 two 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


Resource API Structures and Macros

The Resource API contains structures and macros that are used to:

  • Describe the function table that is returned by the Startup entry point function.
  • Describe the status of a resource.

The function table contains the version number of the Resource API being used by a resource DLL and holds pointers to each of the resource DLL entry point functions. Resource DLLs that support multiple resource types must provide one function table for each resource type.

The structure that is used to describe status information for a resource, RESOURCE_STATUS, is passed as a parameter with the SetResourceStatus function.

Cluster Server defines the following macros and structures:

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_FUNCTION_TABLE | Macro that creates a function table for Resource API version 1.0.
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.


CLRES_FUNCTION_TABLE

The CLRES_FUNCTION_TABLE structure describes a function table for any version of the Resource API. The CLRES_FUNCTION_TABLE structure is defined in RESAPI.H.

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

The CLRES_FUNCTION_TABLE structure contains the version of the Resource API that the DLL is using and a structure that has pointers to all Resource API entry points except Startup.

Except for the following entry points, there must be valid pointers for all Resource API entry point functions:

  • Arbitrate
  • Release
  • ResourceControl
  • ResourceTypeControl

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 which Resource API version is supported.

To create a function table for version 1.0 of the Resource API, use the CLRES_V1_FUNCTION_TABLE macro.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


CLRES_V1_FUNCTION_TABLE

The CLRES_V1_FUNCTION_TABLE macro initializes a function table for version 1 of the Resource API. The CLRES_V1_FUNCTION_TABLE macro is defined in RESAPI.H.

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:

PrefixOpen | The name of the Open entry point.
PrefixClose | The name of the Close entry point.
PrefixOnline | The name of the Online entry point.
PrefixOffline | The name of the Offline entry point.
PrefixTerminate | The name of the Terminate entry point.
PrefixLooksAlive | The name of the LooksAlive entry point.
PrefixIsAlive | The name of the IsAlive entry point.
PrefixArbitrate | The name of the Arbitrate entry point or NULL.
PrefixRelease | The name of the Release entry point or NULL.
PrefixResControl | The name of the ResourceControl entry point or NULL.
PrefixResTypeControl | The name of the ResourceTypeControl entry point or NULL.

To view the format of the function table, see CLRES_FUNCTION_TABLE structure.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


CLRES_V1_FUNCTIONS

The CLRES_V1_FUNCTIONS structure contains pointers to all Resource API version 1.0 entry points except Startup. The CLRES_VI_FUNCTIONS structure is defined in RESAPI.H.

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. All function pointers must be non-NULL except for these Resource API entry points:

  • Arbitrate
  • Release
  • ResourceControl
  • ResourceTypeControl

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 which Resource API interface version is supported.

To create a function table for version 1.0 of the Resource API, use the CLRES_V1_FUNCTION_TABLE macro.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


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. The RESOURCE_STATUS structure is defined in RESAPI.H.

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:
ClusterResourceUnavailable
An error occurred trying to retrieve the state, typically because the server is no longer available. The caller should call the Win32 function GetLastError for more information.
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 put offline.
CheckPoint
A value that increases sequentially by 1 whenever a new status is reported for the resource. The starting value for CheckPoint should be zero.
WaitHint
The number of milliseconds expected until the next time that status is reported.
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, then the CheckPoint member should be greater than the previous value reported for CheckPoint.

Before returning the ClusterResourceUnavailable 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in resapi.h.


Cluster Administrator Extension API

The Cluster Administrator Extension API allows developers of custom resource types to create an extension DLL for administering resources associated with these new types with resources associated with the standard Cluster Server types. Implementing a Cluster Administrator extension DLL enables all resource types to be administered with a consistent, graphical interface. To insure this consistency, Cluster Server requires that anyone implementing a resource DLL also implement a Cluster Administrator extension DLL.

The Cluster Administrator Extension API consists of interfaces based on the Component Object Model (COM). Most of these interfaces are implemented by Cluster Administrator and called by the extension. Only a few are implemented by the extension directly. The interfaces are defined in the CLUADMEX.IDL file and the CLUADMEX.H header file. Related to the COM-based API are several functions that are used for registering an extension DLL with Cluster Administrator.

A Cluster Administrator extension DLL is implemented as an in-process server. An in-process server provides a service, such as a property page that displays resource properties, to clients with a specific set of COM interfaces. These interfaces are made available through objects represented by unique identifiers called class identifiers (CLSID). In-process servers include these CLSIDs in the system registry to enable them to be recognized by the clients that require their services.

Cluster Administrator extensions can be created with or without the Resource Type AppWizard provided with the Microsoft® Developer Studio™ visual development system. Using the Resource Type AppWizard saves time and effort by producing a Cluster Administrator extension that is complete and fully operational. For more information about using the Resource Type AppWizard to generate a Cluster Administrator extension, see Using the Resource Type AppWizard.

The Cluster Administrator extension created by the Resource Type AppWizard relies on the ActiveX Template Library (ATL) version 1.1. Developers creating Cluster Administrator extensions without using the AppWizard can base their extensions on ATL classes, classes from an alternate class library, or implement their classes without a library. Using ATL is recommended because it is an effective way to implement a Cluster Administrator extension.


Cluster Administrator Extension Interfaces

The interfaces in the Cluster Administrator Extension API allow developers to create property sheets and integrate them into Cluster Administrator's graphical environment and to retrieve data from Cluster Administrator.

The following table describes each of the extension interfaces:

Interface | Description
IGetClusterDataInfo | Retrieves information about a cluster.
IGetClusterGroupInfo | Retrieves information about a group.
IGetClusterNodeInfo | Retrieves information about a node.
IGetClusterObjectInfo | Retrieves information about a cluster object.
IGetClusterResourceInfo | Retrieves information about a resource.
IGetClusterUIInfo | Retrieves information about Cluster Administrator's user interface.
IWCContextMenuCallback | Adds menu items to Cluster Administrator's context menu.
IWCPropertySheetCallback | Adds property sheets to Cluster Administrator's property pages.
IWCWizardCallback | Adds a property page to Cluster Administrator's Create Group or Create Resource and manages navigation.
IWEExtendContextMenu | Enhances a Cluster Administrator context menu.
IWEExtendPropertySheet | Enhances a Cluster Administrator property sheet.
IWEExtendWizard | Enhances Cluster Administrator's Create Group or Create Resource wizard.
IWEInvokeCommand | Performs commands associated with items added to Cluster Administrator context menus.

Note Cluster Administrator extensions must make all calls to interface methods in the Cluster Administrator Extension API from a single thread. This style of threading is referred to as apartment model threading.


IGetClusterDataInfo : IUnknown

The IGetClusterDataInfo interface is called by a Cluster Administrator extension to retrieve information about a cluster.

Vtable Order

GetClusterName | Retrieves the name of the current cluster.
GetClusterHandle | Retrieves a handle to the current cluster.
GetObjectCount | Retrieves a count of the number of selected objects.

Remarks

To call the methods in the IGetClusterDataInfo interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. An extension can access this pointer by calling the IUnknown::QueryInterface method with the piData pointer passed to one of these methods:

IWEExtendPropertySheet::CreatePropertySheetPages

IWEExtendContextMenu::AddContextMenuItems

IWEExtendWizard::CreateWizardPages

IWEInvokeCommand::InvokeCommand

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterDataInfo::GetClusterName

The IGetClusterDataInfo::GetClusterName method retrieves the name of the current cluster.

HRESULT GetClusterName(
  BSTR lpszName,
  LONG *pcchName
);

Parameters

lpszName
[out] Pointer to the name of the cluster, or NULL, indicating that the caller is requesting only the length of the name.
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 terminating null character.

Return Values

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 contents of pcchName.

If GetClusterName is unsuccessful, it can also return an OLE-defined error value.

Remarks

If the lpszName parameter is set to NULL and the pcchName parameter is not set to NULL, GetClusterName returns NOERROR.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterDataInfo::GetClusterHandle

The IGetClusterDataInfo::GetClusterHandle method retrieves a handle to the current cluster.

HCLUSTER GetClusterHandle();

Parameters

None.

Return Values

If GetClusterHandle is successful, it returns a cluster handle.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterDataInfo::GetObjectCount

The IGetClusterDataInfo::GetObjectCount method retrieves a count of the number of selected objects.

LONG GetObjectCount();

Parameters

None.

Return Values

A count of the number of selected objects.

Remarks

At present, because Cluster Administrator supports only one selected object, GetObjectCount always returns 1. However, Cluster Administrator extensions should be prepared to handle the case where more than one object is selected.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterGroupInfo : IUnknown

The IGetClusterGroupInfo interface is called by a Cluster Administrator extension to retrieve information about a group.

Vtable Order

GetGroupHandle Retrieves a handle to a group.

Remarks

To call the methods in the IGetClusterGroupInfo interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. An extension can access this pointer by calling the IUnknown::QueryInterface method with the piData pointer passed to one of these methods:

IWEExtendPropertySheet::CreatePropertySheetPages

IWEExtendContextMenu::AddContextMenuItems

IWEExtendWizard::CreateWizardPages

IWEInvokeCommand::InvokeCommand

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterGroupInfo::GetGroupHandle

The IGetClusterGroupInfo::GetGroupHandle method retrieves a handle to a group.

HGROUP GetGroupHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target group. At present, 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 unsuccessful, it returns NULL. For more information about the error, call the Win32® function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterNodeInfo : IUnknown

The IGetClusterNodeInfo interface is called by a Cluster Administrator extension to retrieve information about a node.

Vtable Order

GetNodeHandle Retrieves a handle to a node.

Remarks

To call the methods in the IGetClusterNodeInfo interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. An extension can access this pointer by calling the IUnknown::QueryInterface method with the piData pointer passed to one of these methods:

IWEExtendPropertySheet::CreatePropertySheetPages

IWEExtendContextMenu::AddContextMenuItems

IWEExtendWizard::CreateWizardPages

IWEInvokeCommand::InvokeCommand

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterNodeInfo::GetNodeHandle

The IGetClusterNodeInfo::GetNodeHandle method retrieves a handle to a node.

HNODE GetNodeHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target node. At present, 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 unsuccessful, it returns NULL. For more information about the error, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterObjectInfo : IUnknown

The IGetClusterObjectInfo interface is called by a Cluster Administrator extension to retrieve information about a cluster object.

Vtable Order

GetObjectName | Retrieves the name of a cluster object.
GetObjectType | Retrieves the type of a cluster object.

Remarks

Cluster objects include the cluster, nodes, groups, resources, and resource types.

To call the methods in the IGetClusterObjectInfo interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. An extension can access this pointer by calling the IUnknown::QueryInterface method with the piData pointer passed to one of these methods:

IWEExtendPropertySheet::CreatePropertySheetPages

IWEExtendContextMenu::AddContextMenuItems

IWEExtendWizard::CreateWizardPages

IWEInvokeCommand::InvokeCommand

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterObjectInfo::GetObjectName

The IGetClusterObjectInfo::GetObjectName method retrieves the name of a cluster object.

HRESULT GetObjectName(
  LONG lObjIndex,
  BSTR lpszName,
  LONG *plMaxLength
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target object. At present, lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.
lpszName
[out] Pointer to the name of the object associated with lObjIndex. The lpszName parameter can be NULL, indicating that the caller is requesting only the name length.
plMaxLength
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszName parameter. The plMaxLength parameter cannot be NULL. On output, pointer to the count of characters in the name stored in the contents of lpszName, including the terminating null character.

Return Values

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 contents of plMaxLength.

If GetObjectName is unsuccessful, it can also return an OLE-defined error value.

Remarks

If the lpszName parameter is specified as NULL, GetObjectName returns NOERROR.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterObjectInfo::GetObjectType

The IGetClusterObjectInfo::GetObjectType method retrieves the type of an object.

CLUADMEX_OBJECT_TYPE GetObjectType(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target object. At present, 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_Node
CLUADMEX_OT_Group
CLUADMEX_OT_Resource
CLUADMEX_OT_ResourceType

If GetObjectType is unsuccessful, it returns –1. For more information, call the Win32 function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterResourceInfo : IUnknown

The IGetClusterResourceInfo interface is called by a Cluster Administrator extension to retrieve information about a resource.

Vtable Order

GetResourceHandle | Retrieves a handle to a resource.
GetResourceNetworkName | Retrieves the name of the first Network Name resource on which a resource depends, whether the dependency is direct or indirect.
GetResourceTypeName | Retrieves the resource type of a specific resource.

Remarks

To call the methods in the IGetClusterResourceInfo interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. An extension can access this pointer by calling the IUnknown::QueryInterface method with the piData pointer passed to one of these methods:

IWEExtendPropertySheet::CreatePropertySheetPages

IWEExtendContextMenu::AddContextMenuItems

IWEExtendWizard::CreateWizardPages

IWEInvokeCommand::InvokeCommand

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterResourceInfo::GetResourceHandle

The IGetClusterResourceInfo::GetResourceHandle method retrieves a handle to a resource.

HRESOURCE GetResourceHandle(
  LONG lObjIndex
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target resource. At present, 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 unsuccessful, it returns NULL. For more information about the error, call the Win32® function GetLastError.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterResourceInfo::GetResourceNetworkName

The IGetClusterResourceInfo::GetResourceNetworkName method retrieves the name of the first Network Name resource on which a resource depends, whether the dependency is direct or indirect.

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. At present, lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.
lpszNetName
[out] Pointer to the name of the Network Name resource upon which the resource indexed by lObjIndex depends.
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 contents of lpszNetName.

Return Values

TRUE
The resource indexed by lObjIndex has a dependency on a Network Name resource and the name of the resource was successfully returned.
FALSE
The resource indexed by lObjIndex does not have a dependency on a Network Name resource.

Remarks

The IGetClusterResourceInfo::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.

MAX_COMPUTERNAME_LENGTH is a constant defined in the Win32 header file WINBASE.H.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterResourceInfo::GetResourceTypeName

The IGetClusterResourceInfo::GetResourceTypeName method retrieves the type of a resource.

HRESULT GetResourceTypeName(
  LONG lObjIndex,
  BSTR lpszResourceTypeName,
  LONG *pcchName
);

Parameters

lObjIndex
[in] A number representing the zero-based index of the target resource. At present, lObjIndex is restricted to the number that can be retrieved by calling IGetClusterDataInfo::GetObjectCount.
lpszResourceTypeName
[out] Pointer to the type of the resource associated with lObjIndex. The lpszResourceTypeName parameter can be NULL, indicating that the caller is requesting only the length of the resource type.
pcchName
[in, out] On input, pointer to the count of characters in the buffer pointed to by the lpszResourceTypeName parameter. The pcchName parameter cannot be NULL. On output, pointer to the count of characters in the resource type name stored in the contents of lpszResourceTypeName, including the terminating null character.

Return Values

NOERROR
The operation was successful.
E_INVALIDARG
One or more of the parameters are invalid.
ERROR_MORE_DATA
The buffer pointed to by lpszResourceTypeName is too small to hold the requested resource type. GetResourceTypeName returns the required number of characters in the contents of pcchName.

If GetResourceTypeName is unsuccessful, it can also return an OLE-defined error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterUIInfo : IUnknown

The IGetClusterUIInfo interface is called by a Cluster Administrator extension to retrieve information about Cluster Administrator's user interface.

Vtable Order

GetLocale | Retrieves the locale identifier to be used with property and wizard pages.
GetFont | Retrieves a handle to the font to be displayed on property and wizard pages.
GetIcon | Retrieves a handle to the icon to use in the upper left corner of property and wizard pages.

Remarks

To call the methods in the IGetClusterUIInfo interface, Cluster Administrator extensions use an interface pointer provided by the Cluster Administrator. An extension can access this pointer by calling the IUnknown::QueryInterface method with the piData pointer passed to one of these methods:

IWEExtendPropertySheet::CreatePropertySheetPages

IWEExtendContextMenu::AddContextMenuItems

IWEExtendWizard::CreateWizardPages

IWEInvokeCommand::InvokeCommand

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterUIInfo::GetLocale

The IGetClusterUIInfo::GetLocale method retrieves the locale identifier to be used with property and wizard pages.

LCID GetLocale();

Parameters

None.

Return Values

GetLocale always returns the locale identifier for the current Cluster Administrator instance.

Remarks

Cluster Administrator extensions call the IGetClusterUIInfo::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.

At present, GetLocale returns NULL. Cluster Administrator extensions should not use this return value in their user interface displays.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterUIInfo::GetFont

The IGetClusterUIInfo::GetFont method retrieves a handle to the font to be displayed on property and wizard pages.

HFONT IGetClusterUIInfo::GetFont();

Parameters

None.

Return Values

If GetFont is successful, it returns a font handle.

Remarks

At present, GetFont returns the font handle as NULL. Cluster Administrator extensions should not use this return value in their user interface displays.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IGetClusterUIInfo::GetIcon

The IGetClusterUIInfo::GetIcon method retrieves a handle to the icon to use in the upper left corner on property and wizard pages.

HICON GetIcon();

Parameters

None.

Return Values

GetIcon always returns a handle to an icon.

Remarks

Each wizard page or property page should have an icon control positioned at (8,7) with a size of (18,20).

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCContextMenuCallback : IUnknown

The IWCContextMenuCallback interface is called by a Cluster Administrator extension to add items to a Cluster Administrator context menu.

Vtable Order

AddExtensionMenuItem Adds a menu item to a Cluster Administrator context menu.

Remarks

To call the methods in the IWCContextMenuCallback interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. This pointer is passed in the piCallback parameter when Cluster Administrator calls an extension's IWEExtendContextMenu::AddContextMenuItems method.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCContextMenuCallback::AddExtensionMenuItem

The IWCContextMenuCallback::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 the name of the item to be added to the menu.
lpszStatusBarText
[in] Pointer to text to display on the status bar when the new item is selected.
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. At present, 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:
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.
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 will be 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 string. This is the default interpretation.

Return Values

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.

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCPropertySheetCallback : IUnknown

The IWCPropertySheetCallback interface is called by a Cluster Administrator extension to add property pages to a Cluster Administrator property sheet.

Vtable Order

AddPropertySheetPage Adds a property page to a Cluster Administrator property sheet.

Remarks

To call the method in the IWCPropertySheetCallback interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. This pointer is passed in the piCallback parameter when Cluster Administrator calls an extension's IWEExtendPropertySheet::CreatePropertySheetPages method.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCPropertySheetCallback::AddPropertySheetPage

The IWCPropertySheetCallback::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

NOERROR
The operation was successful.
E_INVALIDARG
The hpage parameter represents an unknown page.

If AddPropertySheetPage was unsuccessful, it can also return an OLE-defined error value.

Remarks

Cluster Administrator extensions call AddPropertySheetPage from their IWEExtendPropertySheet::CreatePropertySheetPages methods. Prior to calling AddPropertySheetPage, extensions must call the Win32 function CreatePropertySheet to retrieve a handle to pass in the hpage parameter.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCWizardCallback : IUnknown

The IWCWizardCallback interface is called by a Cluster Administrator extension to add a property page to Cluster Administrator's Create Group or Create Resource wizard and to manage navigation.

Vtable Order

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 or not the current page is last.

Remarks

To call the methods in the IWCWizardCallback interface, Cluster Administrator extensions use an interface pointer provided by Cluster Administrator. This pointer is passed in the piCallback parameter when Cluster Administrator calls an extension's IWEExtendWizard::CreateWizardPages method.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCWizardCallback::AddWizardPage

The IWCWizardCallback::AddWizardPage method adds a property page to Cluster Administrator's Create Group or Create Resource wizard.

HRESULT IWCWizardCallback::AddWizardPage(
  HPROPSHEETPAGE hpage
);

Parameters

hpage
[in] Handle to the property page to be added.

Return Values

NOERROR
The operation was successful.
E_INVALIDARG
The hpage parameter represents an unknown page.

If AddWizardPage is unsuccessful, it can also return an OLE-defined error value.

Notes to Callers

Cluster Administrator extensions call AddWizardPage from their IWEExtendWizard::CreateWizardPages methods. Prior to calling AddWizardPage, extensions must call the Win32® function CreatePropertySheet to retrieve a handle to pass in the hpage parameter.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWCWizardCallback::EnableNext

The IWCWizardCallback::EnableNext method enables or disables the Next or Finish button on a Cluster Administrator wizard page, depending on whether or not 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

NOERROR
The operation was successful.
E_INVALIDARG
The hpage parameter represents an unknown page.

If EnableNext is unsuccessful, it can also return an OLE-defined error value.

Remarks

Extensions should call EnableNext in their handling of the PSN_SETACTIVE message for a property page that they have added to the Cluster Administrator wizard. Cluster Administrator will determine whether the Next button or the Finish button should be displayed based on the page specified in the hpage parameter.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEExtendContextMenu : IUnknown

The IWEExtendContextMenu interface is implemented by a Cluster Administrator extension to enhance a Cluster Administrator context menu.

Vtable Order

Add ContextMenuItems Adds items to a Cluster Administrator context menu.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEExtendContextMenu::AddContextMenuItems

The IWEExtendContextMenu::AddContextMenuItems method adds items to a Cluster Administrator context menu.

HRESULT AddContextMenuItems(
  IUnknown * piData,
  IWCContextMenuCallback *piCallback
);

Parameters

piData
[in] Pointer to an IUnknown interface implementation that can be used to obtain pointers to interface implementations relating to objects on the Cluster Administrator context menu. When Cluster Administrator uses piData to call IUnknown::QueryInterface, it should be able to retrieve a pointer to these interfaces:

IGetClusterUIInfo

IGetClusterDataInfo

IGetClusterObjectInfo

Depending on the type of object related to the context menu, an extension should also make a pointer available to one of these interfaces:

IGetClusterNodeInfo, if a node is being extended.

IGetClusterGroupInfo, if a group is being extended.

IGetClusterResourceInfo, if a resource is being extended.

piCallback
[in] Pointer to an IWCContextMenuCallback interface implementation for adding new items to the Cluster Administrator context menu.

Return Values

NOERROR
The operation was successful.
E_INVALIDARG
One or both of the parameters was invalid.
E_FAIL
There was an error adding the context menu item.
E_NOTIMPL
The Cluster Administrator extension does not implement this method.

If AddContextMenuItems is unsuccessful, it can also return an OLE-defined error value.

Remarks

Cluster Administrator calls an extension's IWEExtendContextMenu::AddContextMenuItems method to extend its context menu for a node, group, resource, or resource type.

Notes to Implementers

For each item to be added to the context menu
  1. Call the QueryInterface method of the IUnknown interface 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEExtendPropertySheet : IUnknown

The IWEExtendPropertySheet interface is implemented by a Cluster Administrator extension to enhance a Cluster Administrator property sheet.

Vtable Order

CreatePropertySheetPages Creates property pages and adds them to a Cluster Administrator property sheet.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEExtendPropertySheet::CreatePropertySheetPages

The IWEExtendPropertySheet::CreatePropertySheetPages method creates property pages and adds them to a Cluster Administrator property sheet.

HRESULT CreatePropertySheetPages(
  IUnknown *piData,
  IWCPropertySheetCallback *piCallback
);

Parameters

piData
[in] Pointer to an IUnknown interface implementation that can be used to obtain pointers to interface implementations relating to objects on the Cluster Administrator context menu. When Cluster Administrator uses piData to call IUnknown::QueryInterface, it should be able to retrieve a pointer to these interfaces:

IGetClusterUIInfo

IGetClusterDataInfo

IGetClusterObjectInfo

Depending on the type of object related to the context menu, an extension should also make a pointer available to one of these interfaces:

IGetClusterNodeInfo, if a node is being extended.

IGetClusterGroupInfo, if a group is being extended.

IGetClusterResourceInfo, if a resource is being extended.

piCallback
[in] Pointer to an IWCPropertySheetCallback interface implementation for adding the new property pages to the property sheet.

Return Values

NOERROR
The operation was successful.
E_INVALIDARG
One or both of the parameters was invalid.
E_OUTOFMEMORY
The operation failed due to insufficient memory.
E_FAIL
A property page could not be created.
E_NOTIMPL
The extension does not support adding property pages.

If the operation was unsuccessful, CreatePropertySheetPages can also return an OLE-defined error value.

Remarks

Cluster Administrator calls an extension's IWEExtendPropertySheet::CreatePropertySheetPages method to extend a property sheet to handle an additional node, group, resource, or resource type.

Notes to Implementers

For each property page to be added
  1. Call the IUnknown::QueryInterface method of the interface pointed to by piData to retrieve a pointer to an interface implementation providing information about the cluster component associated with the sheet.
  2. Call the Win32 function CreatePropertySheetPage to create the page.
  3. Call the AddPropertySheetPage method of the IWCPropertySheetCallback interface pointed to by piCallback to add the page to the property sheet.

Each new property page should be no larger than 252 dialog units wide and 218 dialog units high and contain two standard controls:

  • Icon control positioned at (8,7) with a size of (18,20).
  • Static control positioned at (38,12) with a size of (206,10).

These guidelines result in extension pages having a similar appearance to the pages provided by Cluster Administrator.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEExtendWizard : IUnknown

The IWEExtendWizard interface is implemented by a Cluster Administrator extension to enhance Cluster Administrator's Create Group or Create Resource wizard.

Vtable Order

CreateWizardPages Creates property sheet pages and adds them to the Create Group or Create Resource Wizard.

Remarks

The IWEExtendWizard interface is implemented by Cluster Administrator extensions.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEExtendWizard::CreateWizardPages

The IWEExtendWizard::CreateWizardPages method creates property pages and adds them to the Create Group or Create Resource Wizard.

HRESULT CreateWizardPages(
  IUnknown *piData,
  IWCWizardCallback *piCallback
);

Parameters

piData
[in] Pointer to an IUnknown interface implementation that can be used to obtain pointers to interface implementations relating to the object associated with the new property page. When Cluster Administrator uses piData to call IUnknown::QueryInterface, it should be able to retrieve a pointer to these interfaces:

IGetClusterUIInfo

IGetClusterDataInfo

IGetClusterObjectInfo

Depending on the type of object to appear in the new property page, an extension should also make a pointer available to one of these interfaces:

IGetClusterNodeInfo, if the cluster component is a node.

IGetClusterGroupInfo, if the cluster component is a group.

IGetClusterResourceInfo, if the cluster component is a resource.

piCallback
[in] Pointer to an IWCWizardCallback interface implementation used to add the new property pages to the wizard.

Return Values

NOERROR
The operation was successful.
E_INVALIDARG
One or both of the parameters was invalid.
E_OUTOFMEMORY
The operation failed due to insufficient memory.
E_FAIL
A property page could not be created.
E_NOTIMPL
The extension does not support adding a property page to the Create Group or Create Resource Wizard.

If the operation was unsuccessful, CreateWizardPages can also return an OLE-defined error value.

Remarks

Cluster Administrator calls IWEExtendWizard::CreateWizardPages to extend the Create Group or Create Resource Wizard whenever the user creates a new group or a new resource.

Notes to Implementers

For each property page to be added
  1. Call the IUnknown::QueryInterface method of the interface pointed to by piData to retrieve a pointer to an interface that can provide information about the object associated with the new page.
  2. Call the Win32 function CreatePropertySheetPage to create the page.
  3. Call IWCPropertySheetCallback::AddPropertySheetPage using the piCallback pointer to add the page to the Cluster Administrator Wizard.

Each new property page should be no larger than 293 dialog units wide and 172 dialog units high and contain two standard controls:

  • Icon control positioned at (8,7) with a size of (18,20).
  • Static control positioned at (38,12) with a size of (247,10).

These guidelines result in an extension's pages having a similar appearance to the pages provided by Cluster Administrator.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEInvokeCommand : IUnknown

The IWEInvokeCommand interface is implemented by a Cluster Administrator extension to perform commands that are included in a Cluster Administrator context menu.

Vtable Order

InvokeCommand Runs a command that is included in a Cluster Administrator context menu.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


IWEInvokeCommand::InvokeCommand

The IWEInvokeCommand::InvokeCommand method runs commands associated with items added to Cluster Administrator context menus.

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] Pointer to an IUnknown interface implementation that can be used to obtain pointers to interfaces with information about the object associated with the command identified by nCommandID. When Cluster Administrator calls IUnknown::QueryInterface using the piData pointer, it should be able to retrieve a pointer to these interfaces:

IGetClusterUIInfo

IGetClusterDataInfo

IGetClusterObjectInfo

Depending on the type of object associated with the command, a Cluster Administrator extension should also provide a pointer to one of these interfaces:

IGetClusterNodeInfo, if a node is being extended.

IGetClusterGroupInfo, if a group is being extended.

IGetClusterResourceInfo, if a resource is being extended.

Return Values

NOERROR
The operation was successful.
E_FAIL
There was no error adding the context menu item.
E_NOTIMPL
The operation is not implemented for this data type.

If InvokeCommand is unsuccessful, it can also return an OLE-defined error value.

Remarks

Cluster Administrator calls IWEInvokeCommand::InvokeCommand to run a command added to a Cluster Administrator context menu.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


Cluster Administrator Extension Registration Functions

A Cluster Administrator extension DLL must be registered for each computer that is running Cluster Administrator. There are two parts to the registration:

  • Registering the extension with the cluster.
  • Registering the extension with the COM library.

To register a Cluster Administrator extension with a cluster, implement the DllRegisterCluAdminExtension entry point function. DllRegisterCluAdminExtension creates or modifies the AdminExtensions property for the resource type supported by the extension. DllRegisterCluAdminExtension is exported only by Cluster Administrator extensions.

To register a Cluster Administrator extension with the COM library, implement the DllRegisterServer entry point function. DllRegisterServer registers the extension by creating two new keys in the system registry: a key for the ProgId below HKEY_CLASSES_ROOT and a key for the CLSID below HKEY_CLASSES_ROOT\CLSID. DllRegisterServer is exported by all COM servers.

Applications that need to register an extension should call a program named REGCLADM.EXE. REGCLADM calls both the DllRegisterCluAdminExtension and DllRegisterServer entry point functions to take care of both types of registration. Setup programs that need to register extension DLLs must be modified to also call these entry point functions. However, if the setup program is run on a non-cluster node, only the COM registration must be performed. Cluster registration should occur only when the extension is running on a node in a cluster.

Because it is necessary at times to cancel registration, the Cluster Administrator Extension API defines two entry point functions for that purpose: DllUnregisterCluAdminExtension and DllUnregisterServer. As with DllRegisterCluAdminExtension, DllUnregisterCluAdminExtension is specific to Cluster Administrator extensions. As with DllRegisterServer, DllUnregisterServer is exported by all COM servers.

The following table briefly describes the two registration functions and the functions that can be used to cancel registration:

Function | Description
DllRegisterCluAdminExtension | Registers a Cluster Administrator extension DLL with the cluster by adding information to the cluster database.
DllRegisterServer | Registers a Cluster Administrator extension DLL with COM by adding information to the Microsoft® Windows NT® system registry.
DllUnregisterCluAdminExtension | Cancels the registration of a Cluster Administrator extension DLL with the cluster by removing information from the cluster database.
DllUnregisterServer | Cancels the registration of a Cluster Administrator extension DLL with COM by removing information from the Windows NT system 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

NOERROR
The Cluster Administrator Extension DLL was successfully registered.

If DllRegisterCluAdminExtension is unsuccessful, it returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


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

NOERROR
Registration for the Cluster Administrator extension DLL was successfully removed.

If DllUnregisterCluAdminExtension is unsuccessful, it returns a Win32 error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


DllRegisterServer

The DllRegisterServer function registers a Cluster Administrator extension DLL with the COM library by adding information to the Microsoft® Windows NT® system registry.

STDAPI DllRegisterServer(void);

Remarks

Client-side registration must be done on each computer on which Cluster Administrator runs.

When Cluster Administrator calls the OLE function CoCreateInstance, the system registry is examined to find out how to load the extension. Since the Cluster Administrator extension is providing the user interface, the extension must be implemented as an in-process (INPROC) server.

In order 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.

Here is an example of the registry entries for a Cluster Administrator extension named FileSmpEx with a CLSID of {00000000-0000-0000-0000-000000000000}:

HKEY_CLASSES_ROOT

CLSID {00000000-0000-0000-0000-000000000000} =
Cluster Administrator File Share Sample Extension (FileSmpEx) 1.0
InprocServer32 = filesmpex.dll
ProgID = CLUADMEX.FileSmpEx
VersionIndependentProgID = CLUADMEX.FileSmpEx
CLUADMEX.FileSmpEx = Cluster Administrator File Share Sample Extension(FileSmpEx) 1.0
CLSID = {00000000-0000-0000-0000-000000000000}

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


DllUnregisterServer

The DllUnregisterServer function cancels the registration of a Cluster Administrator extension DLL with the COM library by removing information from the Microsoft® Windows NT® system registry.

STDAPI DllUnregisterServer();

Parameters

None.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in cluadmex.h.


REGCLADM

The REGCLADM.EXE program registers a Cluster Administrator extension DLL with the cluster and the COM library.

REGCLADM
  [/U]
  [/Ccluster]
[drive:][path] filename

Parameters

/U
Uninstalls the Cluster Administrator extension DLL specified by the drive, path, and filename parameters.
/Ccluster
Identifies the cluster in which to register the Cluster Administrator extension DLL. The default cluster is the cluster running on the local computer.
drive:path filename
Identifies the Cluster Administrator extension DLL to register.

Remarks

To run REGCLADM, specify the name of the cluster, a path to the Cluster Administrator extension DLL, and an option to uninstall the DLL if necessary. A Cluster Administrator extension DLL must be registered on each computer that is running Cluster Administrator.


Cluster Utility Functions

The Cluster Utility functions provide a shortcut to implementing common application or resource DLL tasks. By calling a utility function, developers of these components can save significant time and effort.

The Cluster Utility functions are implemented in RESUTILS.DLL, a dynamic link library that is provided with Cluster Administrator. Applications and resource DLLs that want to use the Cluster Utility functions must include RESAPI.H in addition to CLUSAPI.H and link to RESUTILS.LIB.


Types of Cluster Utility Functions

The cluster utility functions can be categorized by the type of work that they do. There are six types of utility functions:

· Utility functions to access resource information.

  • Utility functions to access values of different types from the cluster database.
  • Utility functions to handle the parsing and construction of property lists that are passed to and from the control code functions of the Resource and Cluster APIs.
  • Utility functions to handle multiple properties using an array of RESUTIL_PROPERTY_ITEM structures, commonly referred to as a property table.
  • Utility functions to manage threads.
  • Utility functions to perform a variety of tasks.


Resource Utility Functions

The resource utility functions allow applications and resource DLLs to enumerate resources, retrieve information about dependencies, and determine whether or not two resources or resource types are equal. The following table describes the resource utility functions:

Resource utility function | Description
ResUtilEnumResources | Enumerates all of the resources in a cluster and initiates an operation for each resource.
ResUtilGetResourceDependency | Returns a handle to a dependent resource of a specified type.
ResUtilGetResourceNameDependency | Returns a handle to a dependent resource with a specified name and type.
ResUtilResourcesEqual | Tests whether or not two resource handles represent the same resource.
ResUtilResourceTypesEqual | Tests whether or not a resource type matches the resource type of a specified resource.


Cluster Database Utility Functions

The cluster database utility functions are wrappers for the Cluster API functions that access the cluster database. These functions handle memory allocation if necessary and verify that the stored data is the appropriate type. The following table lists the cluster database utility functions:

Cluster database utility function | Description
ResUtilGetBinaryValue | Returns a binary value from the cluster database.
ResUtilGetDwordValue | Returns a numeric value from the cluster database.
ResUtilGetMultiSzValue | Returns a multiple string value from the cluster database.
ResUtilGetSzValue | Returns a string value from the cluster database.
ResUtilSetBinaryValue | Sets a binary value in the cluster database.
ResUtilSetDwordValue | Sets a numeric 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.


Property List Utility Functions

The following table describes the utility functions that can be used with property lists:

Function | Description
ResUtilAddUnknownProperties | Adds unknown properties for a given object to the end of a property list.
ResUtilEnumPrivateProperties | Enumerates private properties of a resource.
ResUtilEnumProperties | Enumerates the properties of a resource.
ResUtilFindDwordProperty | Locates a numeric property in a property list.
ResUtilFindSzProperty | Locates a string property in a property list.
ResUtilGetAllProperties | Returns all of the default and unknown properties for a resource.
ResUtilGetPrivateProperties | Returns the private properties of a cluster object.
ResUtilGetProperties | Returns specified properties for a resource.
ResUtilGetPropertiesToParameterBlock | Returns properties and stores them in a parameter block.
ResUtilPropertyListFromParameterBlock | Constructs a property list from a parameter block.
ResUtilSetPrivatePropertyList | Sets private properties of a resource.
ResUtilVerifyPrivatePropertyList | Validates private properties of a resource.


Property Table Utility Functions

The property table utility functions handle multiple properties using an array of RESUTIL_PROPERTY_ITEM structures. Also known as a property table, the RESUTIL_PROPERTY_ITEM array describes properties. Each entry in the table includes the property's name, cluster database key, format, default value, minimum and maximum values, a set of flags, and an offset to a parameter block containing the location of the property's data. A parameter block is a structure that includes as members either the data for properties in a property table or pointers to the properties' data.

For example, the following structure shows a typical parameter block for a Generic Application resource:

typedef struct _GENAPP_PARAMS {
    LPWSTR CommandLine;
    LPWSTR CurrentDirectory;
    DWORD  UseNetworkName;
    DWORD  InteractWithDesktop;
}  GENAPP_PARAMS, *PGENAPP_PARAMS;

The GENAPP_PARAMS structure contains one member for each of the properties defined for a Generic Application resource. The first two members are pointers to the CommandLine and CurrentDirectory strings; the second two members are the actual UseNetworkName and InteractWithDesktop values.

Each of the entries in the property table created to describe these Generic Application properties has an offset to the member in the GENAPP_PARAMS parameter block that either points to or contains the data. The property table would be defined as follows:

RESUTIL_PROPERTY_ITEM GenAppResPrivateProps[] = {
    {PARAM_NAME__COMMAND_LINE, NULL,
      CLUSPROP_FORMAT_SZ, 0, 0, 0,
      RESUTIL_PROPITEM_REQUIRED,
      FIELD_OFFSET(GENAPP_PARAMS,CommandLine) },
    {PARAM_NAME__CURRENT_DIRECTORY, NULL,
    CLUSPROP_FORMAT_SZ, 0, 0, 0,
      RESUTIL_PROPITEM_REQUIRED,
      FIELD_OFFSET(GENAPP_PARAMS,CurrentDirectory) },
    {PARAM_NAME__INTERACTWITHDESKTOP, NULL,
      CLUSPROP_FORMAT_DWORD,
      PARAM_DEFAULT__INTERACTWITHDESKTOP,
      PARAM_MIN__INTERACTWITHDESKTOP,
      PARAM_MAX__INTERACTWITHDESKTOP,
      RESUTIL_PROPITEM_REQUIRED,
      FIELD_OFFSET(GENAPP_PARAMS,InteractWithDesktop) },
    {PARAM_NAME__USENETWORKNAME, NULL,
      CLUSPROP_FORMAT_DWORD,
      PARAM_DEFAULT__USENETWORKNAME,
      PARAM_MIN__USENETWORKNAME,
      PARAM_MAX__USENETWORKNAME,
      RESUTIL_PROPITEM_REQUIRED,
      FIELD_OFFSET(GENAPP_PARAMS,UseNetworkName) },
    {0 }
};

The property table utility functions are briefly described in the following table; notice that some of the property table functions are also used for property lists:

Function | Description
ResUtilDupParameterBlock | Duplicates a parameter block.
ResUtilEnumProperties | Enumerates the properties of a resource.
ResUtilFreeParameterBlock | Frees a specified parameter block.
ResUtilGetAllProperties | Returns all of the default and unknown properties for a cluster object, such as a resource or group. This function is also used for working with a property list.
ResUtilGetProperties | Returns specified properties for a resource. This function is also used for working with a property list.
ResUtilGetProperty | Returns one of a resource's properties.
ResUtilGetPropertySize | Returns the total number of bytes required for one or more property values.
ResUtilSetPropertyParameterBlock | Sets properties for a resource from a parameter block.
ResUtilSetPropertyTable | Sets properties for a resource based on a property list from a property table.
ResUtilVerifyPropertyTable | Validates properties for a resource based on a property list from a property table.


Service Utility Functions

The service utility functions start and stop a service and verify if a service is up and running. There are five service utility functions:

Function | Description
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.


Miscellaneous Utility Functions

The miscellaneous utility functions take care of implementing common tasks that are useful in a variety of situations. The following table briefly describes these utility functions:

Function | Description
ResUtilDupString | Duplicates a character string.
ResUtilGetEnvironmentWithNetName | Creates an environment block that appends a CLUSTER_NETWORK_NAME environment variable to the current environment block.
ResUtilIsPathValid | Checks whether or not a path is syntactically valid.
ResUtilOpenDriver | Opens an I/O driver.
ResUtilInitializeResourceStatus | Initializes a RESOURCE_STATUS structure.


Thread Management Utility Functions

The thread management utility functions create and start a worker thread and allow a pending operation to be cancelled with correct synchronization. There are four thread management utility functions:

Function | Description
ClusWorkerCheckTerminate | Determines whether or not a worker thread should exit as soon as possible.
ClusWorkerCreate | Creates a worker thread.
ClusWorkerTerminate | Terminates a worker thread.


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 or not 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 processed by the worker thread.
lpParameter
[in] A parameter to pass to the function whose address is pointed to by lpStartAddress.

Return Values

ERROR_SUCCESS
The thread was created successfully.

If the operation was unsuccessful, ClusWorkerCreate returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ClusWorkerCheckTerminate

The ClusWorkerCheckTerminate utility function determines whether or not 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

TRUE
The thread should terminate.
FALSE
The thread should not terminate.

Notes to Callers

ClusWorkerCheckTerminate checks the Terminate member of the CLUS_WORKER structure to determine whether or not the thread pointed to by Worker should exit. The Terminate member is used to prevent a race condition from occurring when multiple threads call ClusWorkerCheckTerminate on the same worker thread. The first call sets Terminate to TRUE. The second and subsequent calls will check that Terminate is set and return immediately without waiting for the worker thread to exit.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

None.

Notes to Callers

ClusWorkerTerminate 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilAddUnknownProperties

The ResUtilAddUnknownProperties utility function adds unknown properties for a given object to the end of a property list. Unknown properties are properties that are specific to a resource, but foreign to the resource DLL.

DWORD WINAPI ResUtilAddUnknownProperties(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

ClusterKey
[in] Pointer to the cluster database key that identifies the location for the properties to add.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing known properties.
OutBuffer
[in, out] Pointer to a property list. The unknown properties are appended to this list.
OutBufferSize
[in] Size of the property list pointed to by OutBuffer.
BytesReturned
[in, out] On input, pointer to the number of bytes in use in the property list pointed to by OutBuffer. On output, pointer to the total number of bytes in the property list pointed to by OutBuffer.
Required
[in, out] Pointer to the required number of bytes if the property list is too small to hold the unknown properties.

Return Values

ERROR_SUCCESS
The unknown properties were added successfully.
ERROR_NOT_ENOUGH_MEMORY
There was an error allocating memory.

If the operation was unsuccessful, ResUtilAddUnknownProperties can also return a Win32® error value.

Notes to Callers

ResUtilAddUnknownProperties supports unknown properties by reading them directly from the cluster database without involving the resource DLL, thereby allowing a resource to be extended by another resource or an application. Unknown properties are considered private properties; unknown common properties are disallowed.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilDupParameterBlock

The ResUtilDupParameterBlock utility function duplicates a parameter block.

DWORD WINAPI ResUtilDupParameterBlock(
  LPBYTE OutParams,
  const LPBYTE InParams,
  const PRESUTIL_PROPERTY_ITEM PropertyTable
);

Parameters

OutParams
[out] Pointer to the duplicated parameter block.
InParams
[in] Pointer to the original parameter block.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing properties in the original parameter block.

Return Values

ERROR_SUCCESS
The parameter block was duplicated successfully.

If the operation was unsuccessful, ResUtilDupParameterBlock returns a Win32® error value.

Notes to Callers

A parameter block is a buffer or structure that contains the data or pointers to data for the properties described in a property table. ResUtilDupParameterBlock copies the data found in the input parameter block pointed to by InParams to the output parameter block pointed to by OutParams. If a variable in the parameter block is a pointer, memory for the data is allocated using 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilDupString

The ResUtilDupString utility function duplicates a character string.

PWSTR WINAPI ResUtilDupString(
  LPCWSTR Value
);

Parameters

Value
[in] Pointer to the string to duplicate.

Return Values

If the operation was successful, ResUtilDupString returns a pointer to a buffer containing the duplicate string.

If the operation was unsuccessful, ResUtilDupString returns NULL. A call can be made to the Win32® function GetLastError for more information.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilEnumPrivateProperties

The ResUtilEnumPrivateProperties utility function enumerates private properties of a resource.

DWORD WINAPI ResUtilEnumPrivateProperties(
  PVOID ClusterKey,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

ClusterKey
[in] Key identifying the location of the private properties in the cluster database.
OutBuffer
[out] Pointer to an output buffer containing the names of the enumerated properties.
OutBufferSize
[in] Size of the output buffer pointed to by OutBuffer.
BytesReturned
[out] Pointer to the total number of bytes in returned in the output buffer.
Required
[out] Pointer to the required number of bytes if the output buffer is too small to hold all of the enumerated properties.

Return Values

ERROR_SUCCESS
The enumeration was successful.
ERROR_BAD_ARGUMENTS
One or more of the input parameters were invalid.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilEnumProperties

The ResUtilEnumProperties utility function enumerates the properties of a resource.

DWORD WINAPI ResUtilEnumProperties(
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing properties to enumerate.
OutBuffer
[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 string. The last property name is followed by a final terminating null character.
OutBufferSize
[in] Size in bytes of the output buffer pointed to by OutBuffer.
BytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by OutBuffer.
Required
[out] Number of bytes required if the output buffer is too small.

Return Values

ERROR_SUCCESS
The enumeration was successful.
ERROR_BAD_ARGUMENTS
One or more of the input parameters were invalid.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilEnumResources

The ResUtilEnumResources utility function enumerates all of the resources in a cluster and initiates an operation for each resource.

DWORD WINAPI ResUtilEnumResources(
  HRESOURCE hSelf,
  LPCWSTR lpszResTypeName,
  LPRESOURCE_CALLBACK pResCallBack,
  PVOID pParameter
);

Parameters

hSelf
[in] Optional handle to a resource that belongs to the cluster with the resources to enumerate.
lpszResTypeName
[in] Optional pointer to a name of a resource type narrowing the scope of resources to enumerate. If lpszResTypeName is specified, only resources of the specified type are enumerated.
pResCallBack
[in] Pointer to the ResourceCallback function to call for each resource, or for each resource that matches the filter described by lpszResTypeName.
pParameter
[in] Parameter to pass to the ResourceCallback function.

Return Values

ERROR_SUCCESS
The resources were successfully enumerated and subsequent calls to the resource callback functions were successful.
ERROR_NO_MORE_ITEMS
All of the resources have been enumerated.

If the operation was unsuccessful, ResUtilEnunResources can also return a Win32® error.

Notes to Callers

ResUtilEnumResources invokes the ResourceCallback function for every resource enumerated when hSelf is NULL. However, when hSelf is set to a valid resource handle, ResourceCallback is not invoked for the resource identified by hSelf. Additionally, if lpszResTypeName is specified, ResourceCallback will be called only for resources of the specified type.

ResourceCallback performs whatever tasks make sense for the resource. For example, Cluster Server's Print Spooler resource DLL checks that the group for the resource contains a single Print Spooler resource. It is a requirement for that resource type that there be only one Print Spooler resource per group.

ResUtilEnumResources opens the current cluster by calling OpenCluster and returns a resource enumeration handle by calling ClusterOpenEnum with the dwType parameter set to CLUSTER_ENUM_RESOURCE.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilFindDwordProperty

The ResUtilFindDwordProperty utility function locates a numeric property in a property list.

DWORD WINAPI ResUtilFindDwordProperty(
  const PVOID Buffer,
  DWORD BufferSize,
  LPCWSTR PropName,
  LPDWORD FoundDword
);

Parameters

Buffer
[in] Pointer to the value list in which to locate the numeric value.
BufferSize
[in] Size in bytes of the data included in Buffer.
PropName
[in] Pointer to the name of the value to locate.
FoundDword
[out] Pointer to the located numeric value.

Return Values

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 numeric property could not be located in the property list.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilFindSzProperty

The ResUtilFindSzProperty utility function locates a string property in a property list.

DWORD WINAPI ResUtilFindSzProperty(
  const PVOID Buffer,
  DWORD BufferSize,
  LPCWSTR PropName,
  LPWSTR *FoundString
);

Parameters

Buffer
[in] Pointer to the property list in which to locate the string property.
BufferSize
[in] Size in bytes of the data included in Buffer.
PropName
[in] Pointer to the name of the string property to locate.
FoundString
[out] Pointer to the value from the property list containing the string property pointed to by PropName.

Return Values

ERROR_SUCCESS
A successful attempt was made to locate the string.
ERROR_NOT_ENOUGH_MEMORY
Insufficient memory available for completing the operation.
ERROR_INVALID_DATA
The data is in an incorrect format.
ERROR_FILE_NOT_FOUND
The string property could not be located in the value list.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilFreeParameterBlock

The ResUtilFreeParameterBlock utility function deallocates memory that has been allocated for a parameter block.

void WINAPI ResUtilFreeParameterBlock(
  LPBYTE OutParams,
  const LPBYTE InParams,
  const PRESUTIL_PROPERTY_ITEM PropertyTable
);

Parameters

OutParams
[in, out] Pointer to the parameter block to deallocate.
InParams
[in] Pointer to the parameter block to use as a reference.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties in the input parameter block.

Return Values

None.

Notes to Callers

A parameter block is a buffer or structure that contains the data or pointers to data for the properties described in a property table. ResUtilFreeParameterBlock deallocates any memory allocated for a variable that is a member of the output parameter block that is not also pointed to by the input parameter block.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

ClusterKey
[in] Pointer to the cluster database key that identifies the location of the properties to retrieve.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describe the properties to retrieve.
OutBuffer
[out] Pointer to an output buffer in which to return the property list.
OutBufferSize
[in] Size in bytes of the output buffer pointed to by OutBuffer.
BytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by OutBuffer.
Required
[out] Pointer to the number of bytes that is required if OutBuffer is too small.

Return Values

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.

If the operation was unsuccessful, ResUtilGetAllProperties can also return a Win32® error value.

Notes to Callers

ResUtilGetAllProperties 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetBinaryValue

The ResUtilGetBinaryValue utility function returns a binary value from the cluster database.

DWORD WINAPI ResUtilGetBinaryValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  LPBYTE * OutValue,
  DWORD * OutValueSize
);

Parameters

ClusterKey
[in] Key in the cluster database that identifies the location of the value to retrieve.
ValueName
[in] Pointer to the name of the value to retrieve.
OutValue
[out] Address of the pointer to the retrieved value.
OutValueSize
[out] Pointer to a DWORD in which the size in bytes of the buffer pointed to by OutValue is returned.

Return Values

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 also return Win32® error codes that are returned by ClusterRegQueryValue.

Notes to Callers

ResUtilGetBinaryValue takes care of allocating the necessary memory for the value and calls the Cluster API function ClusterRegQueryValue. When you are finished with the allocated memory, you must call the Win32 function LocalFree to release it.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetDwordValue

The ResUtilGetDwordValue utility function returns a numeric value from the cluster database.

DWORD WINAPI ResUtilGetDwordValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  LPDWORD OutValue,
  DWORD DefaultValue
);

Parameters

ClusterKey
[in] Key identifying the location of the numeric value in the cluster database.
ValueName
[in] Pointer to the name of the value to retrieve.
OutValue
[out] Pointer to the retrieved value.
DefaultValue
[in] Value to return if the value pointed to by ValueName is not found.

Return Values

ERROR_SUCCESS
The operation completed successfully.
ERROR_INVALID_PARAMETER
The value pointed to by ValueName is not a numeric value.
ResUtilGetDwordValue can also return Win32® error codes that are returned by ClusterRegQueryValue.

Notes to Callers

ResUtilGetDwordValue calls the Cluster API function ClusterRegQueryValue to retrieve the value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetEnvironmentWithNetName

The ResUtilGetEnvironmentWithNetName utility function creates an environment block that appends a CLUSTER_NETWORK_NAME environment variable to the current environment block.

LPVOID WINAPI ResUtilGetEnvironmentWithNetName(
  HRESOURCE hResource
);

Parameters

hResource
[in] Handle to the resource dependent on the Network Name resource used to set the CLUSTER_NETWORK_NAME environment variable.

Return Values

If the operation was successful, ResUtilGetEnvironmentWithNetName returns a pointer to the new environment block.

If the operation was unsuccessful, ResUtilGetEnvironmentWithNetName returns NULL. For more information, call the Win32 function GetLastError.

Notes to Callers

The environment variable that is appended to the current environment block is set to the Name property of the Network Name resource for the resource identified by hResource.

Callers can pass this environment block to the Win32 function CreateProcess to create an environment appropriate for Cluster Server operations.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetMultiSzValue

The ResUtilGetMultiSzValue utility function returns a multiple string value from the cluster database.

DWORD WINAPI ResUtilGetMultiSzValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  LPBYTE * OutValue,
  LPDWORD OutValueSize
);

Parameters

ClusterKey
[in] Key identifying the location of the multiple string value in the cluster database.
ValueName
[in] Pointer to the name of the value to retrieve.
OutValue
[out] Address of the pointer to the retrieved value.
OutValueSize
[out] Pointer to a DWORD in which the size in bytes of the buffer pointed to by OutValue is returned.

Return Values

ERROR_SUCCESS
The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY
An error occurred during memory allocation.

ResUtilGetMultiSzValue can also return Win32® error codes that are returned by ClusterRegQueryValue.

Notes to Callers

When you are finished with the memory allocated for the value, you must call the Win32 function LocalFree to release it.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetPrivateProperties

The ResUtilGetPrivateProperties utility function returns private properties for a resource.

DWORD WINAPI ResUtilGetPrivateProperties(
  PVOID ClusterKey,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

ClusterKey
[in] Pointer to the cluster database key that identifies the location of the private properties to retrieve.
OutBuffer
[out] Pointer to an output buffer in which a property list with the names and values of the private properties is returned.
OutBufferSize
[in] Size of the output buffer pointed to by OutBuffer.
BytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by OutBuffer.
Required
[out] Pointer to the number of bytes that is required if OutBuffer is too small to hold all of the private properties.

Return Values

ERROR_SUCCESS
The private 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.

If the operation was unsuccessful, ResUtilGetPrivateProperties can also return a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetProperties

The ResUtilGetProperties utility function returns a property list containing specified properties for a cluster object.

DWORD WINAPI ResUtilGetProperties(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

ClusterKey
[in] Pointer to the cluster database key that identifies the location of the properties to retrieve.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describe the properties to retrieve.
OutBuffer
[out] Pointer to an output buffer in which to return the property list.
OutBufferSize
[in] Size in bytes of the output buffer pointed to by OutBuffer.
BytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by OutBuffer.
Required
[out] Pointer to the number of bytes that is required if OutBuffer is too small.

Return Values

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.

If the operation was unsuccessful, ResUtilGetProperties can also return a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetPropertiesToParameterBlock

The ResUtilGetPropertiesToParameterBlock utility function returns properties and stores them in a parameter block.

DWORD WINAPI ResUtilGetPropertiesToParameterBlock(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  LPBYTES OutParams,
  BOOL CheckForRequiredProperties,
  LPWSTR *NameOfPropInError
);

Parameters

ClusterKey
[in] Pointer to the cluster database key that identifies the location of the properties to retrieve.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describes the properties to process.
OutParams
[out] Pointer to the output parameter block to fill.
CheckForRequiredProperties
[in] Specifies whether or not an error should be generated if required properties are missing.
NameOfPropInError
[out] Address of the string pointer in which to return the name of the error generated by a missing required property. The NameOfPropInError property is optional.

Return Values

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 unsuccessful, ResUtilGetPropertiesToParameterBlock can also return a Win32® error value.

Notes to Callers

The property table pointed to by PropertyTable can include default values.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetProperty

The ResUtilGetProperty utility function returns a specified property.

DWORD WINAPI ResUtilGetProperty(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM Property,
  PVOID *OutBuffer,
  LPDWORD OutBufferSize
);

Parameters

ClusterKey
[in] Pointer to the cluster database key identifying the location of the property to retrieve.
Property
[in] Pointer to a RESUTIL_PROPERTY_ITEM structure that describes the property to retrieve.
OutBuffer
[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.
OutBufferSize
[in, out] Pointer to the size in bytes of the output buffer pointed to by OutBuffer.

Return Values

ERROR_SUCCESS
The property was successfully retrieved.
ERROR_BAD_ARGUMENTS
One or more of the input parameters were invalid.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetPropertySize

The ResUtilGetPropertySize utility function returns the total number of bytes required for a specified property.

DWORD WINAPI ResUtilGetPropertySize(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM Property,
  LPDWORD BufferSize,
  LPDWORD ItemCount
);

Parameters

ClusterKey
[in] Cluster database key identifying the location of the property to size.
Property
[in] Pointer to a RESUTIL_PROPERTY_ITEM structure describing the property to size.
BufferSize
[in, out] Pointer to the total number of bytes required for the property value, which includes the CLUSPROP_VALUE structure and the data.
ItemCount
[in, out] Pointer to the total number of properties. This value is incremented to include this property if ResUtilGetPropertySize is successful.

Return Values

ERROR_SUCCESS
The size of the property was successfully retrieved.
ERROR_BAD_ARGUMENTS
One or more of the input parameters were invalid.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetResourceDependency

The ResUtilGetResourceDependency utility function returns a handle to a dependent resource of a specified type.

HRESOURCE WINAPI ResUtilGetResourceDependency(
  HANDLE hSelf,
  LPCWSTR lpszResourceType
);

Parameters

hSelf
[in] Handle to the resource upon which the dependent resource depends.
lpszResourceType
[in] Pointer to the type of the dependent resource.

Return Values

If the operation was successful, ResUtilGetResourceDependency returns a handle to the dependent resource. The caller is responsible for closing that handle by calling CloseClusterResource.

If the operation was unsuccessful, ResUtilGetResourceDependency returns NULL. A call can be made to the Win32 function GetLastError for more information.

Notes to Callers

ResUtilGetResourceDependency returns the name of a dependent resource by calling:

  1. OpenCluster to open the current cluster.
  2. ClusterResourceOpenEnum with dwType set to CLUSTER_RESOURCE_ENUM_DEPENDS to open the appropriate enumerator for the resource identified by hSelf.
  3. ClusterResourceEnum to enumerate a dependent resource.
  4. OpenClusterResource to open the enumerated resource.
  5. ResUtilResourceTypesEqual to compare the type of the enumerated resource with the type pointed to by lpszResourceType. If it matches, a handle to the dependent resource is returned. If it does not match, steps 3 through 5 are repeated.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetResourceNameDependency

The ResUtilGetResourceNameDependency utility function returns a handle to a dependent resource with a specified name and type.

HRESOURCE WINAPI ResUtilGetResourceNameDependency(
  LPCWSTR lpszResourceName,
  LPCWSTR lpszResourceType
);

Parameters

lpszResourceName
[in] Pointer to the name of the resource whose dependency is to be retrieved.
lpszResourceType
[in] Pointer to the type of the dependent resource.

Return Values

If the operation was successful, ResUtilGetResourceNameDependency returns a handle to the dependent resource. The caller is responsible for closing that handle by calling CloseClusterResource.

If the operation was unsuccessful, ResUtilGetResourceNameDependency returns NULL. A call can be made to the Win32 function GetLastError for more information.

Notes to Callers

ResUtilGetResourceNameDependency returns the name of a dependent resource by calling:

  1. OpenCluster to open the current cluster.
  2. OpenClusterResource to open the resource pointed to by lpszResourceName.
  3. ClusterResourceOpenEnum with dwType set to CLUSTER_RESOURCE_ENUM_DEPENDS to open the appropriate enumerator.
  4. ClusterResourceEnum to enumerate a dependent resource.
  5. OpenClusterResource to open the enumerated resource.
  6. ResUtilResourceTypesEqual to compare the type of the enumerated resource with the type pointed to by lpszResourceType. If it matches, a handle to the dependent resource is returned. If it does not match, steps 4 through 6 are repeated.

For more information, see ResUtilGetResourceDependency.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilGetSzValue

The ResUtilGetSzValue utility function returns a string value from the cluster database.

LPWSTR WINAPI ResUtilGetSzValue(
  HKEY ClusterKey,
  LPCWSTR ValueName
);

Parameters

ClusterKey
[in] Key identifying the location of the value in the cluster database.
ValueName
[in] 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 unsuccessful, ResUtilGetSzValue returns NULL. A call can be made to the Win32 function GetLastError for more information.

Notes to Callers

ResUtilGetSzValue 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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

None.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilIsPathValid

The ResUtilIsPathValid utility function is used to check whether or not a path is syntactically valid.

BOOL WINAPI ResUtilIsPathValid(
  LPCWSTR Path
);

Parameters

Path
[in] Pointer to the path to check.

Return Values

TRUE
The path pointed to by Path is valid.
FALSE
The path pointed to by Path is not valid.

Notes to Callers

ResUtilIsPathValid is not a network-aware function.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilOpenDriver

The ResUtilOpenDriver utility function opens an I/O driver.

DWORD WINAPI ResUtilOpenDriver(
  HANDLE *Handle,
  LPWSTR DriverName
);

Parameters

Handle
[out] Pointer to a handle to the opened driver.
DriverName
[in] Pointer to the name of the driver to open.

Return Values

ERROR_SUCCESS
The operation completed successfully.

If the operation was unsuccessful, ResUtilOpenDriver returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilPropertyListFromParameterBlock

The ResUtilPropertyListFromParameterBlock utility function constructs a property list from a parameter block.

DWORD WINAPI ResUtilPropertyListFromParameterBlock(
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID OutBuffer,
  DWORD OutBufferSize,
  const LPBYTE InParams,
  LPDWORD BytesReturned,
  LPDWORD Required
);

Parameters

PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures that describes the parameter block to process.
OutBuffer
[out] Pointer to an output buffer in which a property list with the names and values of the properties in the parameter block should be returned.
OutBufferSize
[in] Size of the output buffer.
InParams
[in] Parameter block containing the properties out of which the property list returned in OutBuffer is constructed.
BytesReturned
[out] Pointer to the total number of bytes in the property list pointed to by OutBuffer.
Required
[out] Pointer to the number of bytes that is required if OutBuffer is too small to hold the properties from the parameter block.

Return Values

ERROR_SUCCESS
The 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.

If the operation was unsuccessful, ResUtilPropertyListFromParameterBlock can also return a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilResourcesEqual

The ResUtilResourcesEqual utility function tests whether or not 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

TRUE
The resources are equal.
FALSE
The resources are not equal.

Notes to Callers

ResUtilResourcesEqual 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilResourceTypesEqual

The ResUtilResourceTypesEqual utility function tests whether or not a resource type matches the resource type name of a specified resource.

BOOL WINAPI ResUtilResourcesTypesEqual(
  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

TRUE
The resource types are equal.
FALSE
The resource types are not equal.

Notes to Callers

ResUtilResourceTypesEqual 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetBinaryValue

The ResUtilSetBinaryValue utility function sets a binary value in the cluster database.

DWORD WINAPI ResUtilSetBinaryValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  const LPBYTE NewValue,
  DWORD NewValueSize,
  LPBYTE * OutValue,
  LPDWORD OutValueSize
);

Parameters

ClusterKey
[in] Key identifying the location of the binary value in the cluster database.
ValueName
[in] Name of the value to update.
NewValue
[in] Pointer to the new binary value.
NewValueSize
[in] Size of the new binary value.
OutValue
[in, out] Address of a pointer to the new binary value.
OutValueSize
[in, out] Pointer to a DWORD in which the size in bytes of the value pointed to by OutValue is returned.

Return Values

ERROR_SUCCESS
The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY
An error occurred during memory allocation.

ResUtilSetBinaryValue can also return Win32® error codes that are returned by ClusterRegSetValue.

Notes to Callers

ResUtilSetBinaryValue allocates memory for the OutValue 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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetDwordValue

The ResUtilSetDwordValue utility function sets a numeric value in the cluster database.

DWORD WINAPI ResUtilSetDwordValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  DWORD NewValue,
  LPDWORD OutValue
);

Parameters

ClusterKey
[in] Key identifying the location of the numeric value in the cluster database.
ValueName
[in] Name of the value to update.
NewValue
[in] New DWORD value.
OutValue
[in, out] Pointer to where the updated value should be copied to.

Return Values

ERROR_SUCCESS
The operation completed successfully.

If the operation was unsuccessful, ResUtilSetDwordValue returns a Win32® error value.

Notes to Callers

ResUtilSetDwordValue updates the cluster database by calling the Cluster API function ClusterRegSetValue.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetExpandSzValue

The ResUtilSetExpandSzValue utility function sets an expandable string value in the cluster database.

DWORD WINAPI ResUtilSetExpandSzValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  LPCWSTR NewValue,
  LPWSTR * OutValue
);

Parameters

ClusterKey
[in] Key identifying the location of the expandable string value in the cluster database.
ValueName
[in] Name of the value to update.
NewValue
[in] Pointer to the new expandable string value.
OutValue
[in, out] Pointer to a string containing the updated value.

Return Values

ERROR_SUCCESS
The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY
An error occurred while attempting to allocate memory.

ResUtilSetExpandSzValue can also return Win32® error codes that are returned by ClusterRegSetValue.

Notes to Callers

ResUtilSetExpandSzValue 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 that contains unexpanded references to environment variables such as "%PATH%".

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetMultiSzValue

The ResUtilSetMultiSzValue utility function sets a multiple string value in the cluster database.

DWORD WINAPI ResUtilSetMultiSzValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  LPCWSTR NewValue,
  DWORD NewValueSize,
  LPWSTR * OutValue,
  LPDWORD OutValueSize
);

Parameters

ClusterKey
[in] Key identifying the location of the multiple string value in the cluster database.
ValueName
[in] Name of the value to update.
NewValue
[in] Pointer to the new multiple string value.
NewValueSize
[in] Size of the new value.
OutValue
[in, out] Address of the pointer to the new value.
OutValueSize
[in, out] Pointer to the size of the new value.

Return Values

ERROR_SUCCESS
The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY
An error occurred while attempting to allocate memory.

ResUtilSetMultiSzValue can also return Win32® error codes that are returned by ClusterRegSetValue.

Notes to Callers

ResUtilSetMultiSzValue allocates memory for the new value and calls the Cluster API function ClusterRegSetValue.

A multiple string value contains data that represents an array of null-terminated strings, terminated by two null characters.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetPrivatePropertyList

The ResUtilSetPrivatePropertyList utility function sets the private properties of a resource.

DWORD WINAPI ResUtilSetPrivatePropertyList(
  PVOID ClusterKey,
  const PVOID InBuffer,
  DWORD InBufferSize
);

Parameters

ClusterKey
[in] Cluster database key identifying the location of the properties to set.
InBuffer
[in] Pointer to an input buffer containing a property list with the names and values of the properties to set.
InBufferSize
[in] Pointer to the size in bytes of the input buffer pointed to by InBuffer.

Return Values

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 InBuffer was NULL.
ERROR_INVALID_PARAMETER
The syntax of a property name was invalid.

Notes to Callers

The properties that are set in ResUtilSetPrivatePropertyList 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 will be interpreted as a subkey name, and the last string following the last backslash character will be interpreted as the value name.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetPropertyParameterBlock

The ResUtilSetPropertyParameterBlock utility function is used to set properties in the cluster database from a parameter block.

DWORD WINAPI ResUtilSetPropertyParameterBlock(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID Reserved,
  const LPBYTE InParams,
  const LPVOID InBuffer,
  DWORD InBufferSize,
  LPBYTE OutParams
);

Parameters

ClusterKey
[in] Cluster database key identifying the location for the properties to set.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties to set.
Reserved
[in] Reserved.
InParams
[in] Pointer to an input parameter block containing the data for the properties described in the property table pointed to by PropertyTable.
InBuffer
[in] Pointer to the input buffer containing a property list or NULL. If InBuffer is not NULL, any properties listed in the property list that are not listed in the property table will also be set in the cluster database.
InBufferSize
[in] Size in bytes of the input buffer pointed to by InBuffer.
OutParams
[out] Optional pointer to a parameter block to receive data copied from the InParams parameter.

Return Values

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 PropertyTable is incorrect or a property is read-only and cannot be updated.
ERROR_BAD_ARGUMENTS
One or more of the input parameters were invalid.

Notes to Callers

A parameter block is a buffer or structure that contains the data or pointers to data for the properties described in a property table.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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(
  PVOID ClusterKey,
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID Reserved,
  BOOL AllowUnknownProperties,
  const PVOID InBuffer,
  DWORD InBufferSize,
  OPTIONAL LPBYTE OutParams
);

Parameters

ClusterKey
[in] Cluster database key identifying the location of the properties to set.
PropertyTable
[in] Pointer to an array of RESUTIL_PROPERTY_ITEM structures describing the properties to set.
Reserved
[in] Reserved.
AllowUnknownProperties
[in] Indicates whether or not unknown properties should be accepted. This parameter is set to TRUE if they should be accepted and FALSE otherwise.
InBuffer
[in] Pointer to the input buffer containing a property list.
InBufferSize
[in] Size in bytes of the input buffer pointed to by InBuffer.
OutParams
[out] Optional pointer to a parameter block to hold returned data. If specified, parameters will only be written if they differ from those in the input buffer.

Return Values

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 InBufferSize is too small.
ERROR_INVALID_DATA
The input buffer pointed to by InBuffer 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 PropertyTable is incorrect or a property is read-only and cannot be set.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilSetSzValue

The ResUtilSetSzValue utility function sets a string value in the cluster database.

DWORD WINAPI ResUtilSetSzValue(
  HKEY ClusterKey,
  LPCWSTR ValueName,
  LPCWSTR NewValue,
  LPWSTR * OutValue
);

Parameters

ClusterKey
[in] Key identifying the location of the string value in the cluster database.
ValueName
[in] Name of the value to update.
NewValue
[in] Pointer to the new string value.
OutValue
[in, out] Address of a pointer to the new string value.

Return Values

ERROR_SUCCESS
The operation completed successfully.
ERROR_NOT_ENOUGH_MEMORY
An error occurred while attempting to allocate memory.

ResUtilSetSzValue can also return Win32® error codes that are returned by ClusterRegSetValue.

Notes to Callers

ResUtilSetSzValue 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 contents of OutValue.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilStartResourceService

The ResUtilStartResourceService utility function starts a service.

DWORD WINAPI ResUtilStartResourceService(
  LPCTSTR ServiceName,
  LPHANDLE ServiceHandle
);

Parameters

ServiceName
[in] Name of the service to start.
ServiceHandle
[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

ERROR_SUCCESS
The service was successfully started.
ERROR_SERVICE_NEVER_STARTED
The service was not started.

If the operation was unsuccessful, ResUtilStartResourceService can also return a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilStopResourceService

The ResUtilStopResourceService utility function stops a service.

DWORD WINAPI ResUtilStopResourceService(
  LPCTSTR ServiceName
);

Parameters

ServiceName
[in] Name of the service to stop.

Return Values

ERROR_SUCCESS
The service was successfully stopped.
ERROR_TIMEOUT
Service did not stop after a reasonable number of retries.

If the operation was unsuccessful, ResUtilStopResourceService can also return a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilStopService

The ResUtilStopService utility function stops a service.

DWORD WINAPI ResUtilStopService(
  HANDLE ServiceHandle
);

Parameters

ServiceHandle
[in] Handle of the service to stop.

Return Values

ERROR_SUCCESS
The service was successfully stopped.
ERROR_TIMEOUT
Service did not stop after a reasonable number of retries.

If the operation was unsuccessful, ResUtilStopService can also return a Win32® error value.

Notes to Callers

ResUtilStopService closes the handle specified in ServiceHandle when it stops the service.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilVerifyPrivatePropertyList

The ResUtilVerifyPrivatePropertyList utility function verifies that a property list is correctly formatted.

DWORD WINAPI ResUtilVerifyPrivatePropertyList(
  const PVOID InBuffer,
  DWORD InBufferSize
);

Parameters

InBuffer
[in] Pointer to an input buffer containing the property list to verify.
InBufferSize
[in] Size of the input buffer pointed to by InBuffer.

Return Values

ERROR_SUCCESS
The property list was successfully verified.

If the operation was unsuccessful, ResUtilVerifyPrivatePropertyList returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilVerifyPropertyTable

The ResUtilVerifyPropertyTable utility function verifies that a property table is correctly formatted.

ResUtilVerifyPropertyTable(
  const PRESUTIL_PROPERTY_ITEM PropertyTable,
  PVOID Reserved,
  BOOL AllowUnknownProperties,
  const PVOID InBuffer,
  DWORD InBufferSize,
  LPBYTE OutParams
);

Parameters

PropertyTable
[in] Pointer to the array of RESUTIL_PROPERTY_ITEM structures to verify.
Reserved
[in] Reserved.
AllowUnknownProperties
[in] Indicates whether or not unknown properties should be allowed in the property table. This parameter is set to TRUE if they should be allowed and FALSE otherwise.
InBuffer
[in] Pointer to the input buffer containing the property list to process.
InBufferSize
[in] Size in bytes of the input buffer pointed to by InBuffer.
OutParams
[out] Optional pointer to the parameter block to hold returned data.

Return Values

ERROR_SUCCESS
The property list was successfully verified.

If the operation was unsuccessful, ResUtilVerifyPropertyTable returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilVerifyResourceService

The ResUtilVerifyResourceService utility function verifies that a named service is starting or currently running.

DWORD WINAPI ResUtilVerifyResourceService(
  LPCTSTR ServiceName
);

Parameters

ServiceName
[in] Name of the service to verify.

Return Values

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 or not the service is starting or currently running, it returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ResUtilVerifyService

The ResUtilVerifyService utility function checks if a service identified by a handle is starting or currently running.

DWORD WINAPI ResUtilVerifyService(
  HANDLE ServiceHandle
);

Parameters

ServiceHandle
[in] Handle of the service to verify.

Return Values

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 or not the service is starting or currently running, it returns a Win32® error value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Cluster Control Codes

Cluster control codes are 32-bit values used to describe an operation on a resource, resource type, group, or node. Control codes consist of the following seven components:

The 8-bit object component indicates the type of cluster object to which the control code applies. This component can be set to one of the following values:

  • CLUS_OBJECT_RESOURCE
  • CLUS_OBJECT_RESOURCE_TYPE
  • CLUS_OBJECT_GROUP
  • CLUS_OBJECT_NODE
  • CLUS_OBJECT_NETWORK
  • CLUS_OBJECT_NETINTERFACE
  • CLUS_OBJECT_USER

All of the values except CLUS_OBJECT_USER represent object types defined by Microsoft® Cluster Server. Third-party developers can define control codes for their own object types by setting the object component to a value greater than CLUS_OBJECT_USER.

The bit marked G indicates whether or not the control code represents a global operation which must be performed on each cluster node. Valid values for this component are CLUS_NOT_GLOBAL and CLUS_GLOBAL. Currently, CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS is the only global control code.

The bit marked M indicates whether or not the control code causes a modification to data which in turn may generate an event notification. Valid values for this component are CLUS_NO_MODIFY and CLUS_MODIFY.

The bit marked U indicates whether or not the control code is a user code defined by a third-party developer for use by his or her resource DLL. A control code defined by a user such as a third-party developer sets this bit; a control code defined by Cluster Server does not.

Cluster Server control codes are categorized as either internal or external, as indicated by the bit marked I. Internal control codes set this bit and 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. It is the external control codes that applications use to initiate an operation.

The 18-bit operation code describes the operation. All operation codes are defined as constants beginning with the prefix CLCTL. Some of the operation codes are applicable only to one type of object; others apply to multiple objects. For example, CLCTL_GET_CHARACTERISTICS describes the operation for retrieving an object's intrinsic attributes. Applications can get the characteristics of resources, resource types, groups, and nodes. CLCTL_ADD_CHECKPOINT describes the operation for adding a registry tree to the list of registry trees that are being replicated. This operation is valid only for resources.

The 2-bit access code indicates whether the initiator of the request requires any specific type of access to perform the operation described by the operation code. Valid values for the access code are CLUS_ACCESS_ANY, CLUS_ACCESS_READ, and CLUS_ACCESS_WRITE.


Using the Control Code Functions

To perform an operation using a control code, an application calls one of the following control code functions defined in the Cluster API:

  • ClusterResourceControl to handle control codes with their object component set to CLUS_OBJECT_RESOURCE.
  • ClusterResourceTypeControl to handle control codes with their object component set to CLUS_OBJECT_RESOURCE_TYPE.
  • ClusterGroupControl to handle control codes with their object component set to CLUS_OBJECT_GROUP.
  • ClusterNodeControl to handle control codes with their object component set to CLUS_OBJECT_NODE.
  • ClusterNetworkControl to handle control codes with their object component set to CLUS_OBJECT_NETWORK.
  • ClusterNetInterfaceControl to handle control codes with their object component set to CLUS_OBJECT_NETINTERFACE.

When a call is made to ClusterGroupControl, ClusterNodeControl, ClusterNetworkControl, or ClusterNetInterfaceControl, the Cluster Service performs the operation and returns to the caller. When a call is made to either ClusterResourceControl or ClusterResourceTypeControl, the Cluster Service calls the Resource Monitor to perform the operation. The Resource Monitor will in turn call the resource DLL's ResourceControl or ResourceTypeControl entry point function.

The Resource Monitor always gives the resource DLL the opportunity to process a control code and performs the processing only if the resource DLL is unable to do so. The following situations indicate when a resource DLL might request the help of the Resource Monitor in processing a control code:

  • When the resource DLL does not include the appropriate control code entry point function: either ResourceControl for resources or ResourceTypeControl for resource types.
  • When the resource DLL includes the appropriate control code entry point function, but it does not support the particular control code.
  • When the resource DLL includes the appropriate control code entry point function, but the resource DLL uses this support to augment the processing provided by the Resource Monitor.

Resource DLLs can choose whether or not to support most of the resource and resource type control codes. However, they should support at least the following control codes for manipulating private properties:

  • CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES
  • CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES

There are two other control codes that a resource DLL must support under certain conditions: CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES and CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS. If a resource DLL handles resources that have required dependencies, the DLL must support CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES. If a resource DLL needs to replicate a portion of the system registry, it must support CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS.

Resource DLLs can fully or partially support a control code. With full support, the resource DLL performs the operation described by the control code without help from the Resource Monitor. With partial support, the resource DLL and the Resource Monitor work together to perform the operation.

The control code functions share some of the same parameters and operate in a similar fashion. In addition to the control code that describes the operation to be performed, the functions include an input buffer to hold information needed for processing and an output buffer to hold information resulting from the processing in the parameter list.

Depending on the operation, either the input buffer or the output buffer may be unused. Operations to retrieve data typically do not use input buffers; operations to update data typically do not use output buffers. For example, the CLUSCTL_RESOURCE_GET_FLAGS control code is used to retrieve the attributes that can be set for a resource. When an application calls ClusterResourceControl with this control code and a null input buffer parameter, the function returns an output buffer with a bitmask indicating the flags that are set for the resource. The CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code updates the common properties of a resource. The new property settings must be passed in the input buffer when ClusterResourceControl is called. The output buffer is unused.

Data in the input and output buffers must fall on a DWORD boundary. Cluster Server defines several structures that can be used to work with data passed to or from a control code function. There are structures that describe specific types of data values, such as CLUSPROP_SZ to describe a character string and CLUSPROP_BINARY to describe binary data. These structures are used as entries in value and property lists, arrays that describe multiple data values.

For information about the layout of property and value lists, see About Property Lists and About Value Lists.

For information about individual structures, see Cluster Structures.


Control Codes for Networks

All of the control codes relating to networks are included in the following list. The codes are external control codes, or control codes that applications can pass to ClusterNetworkControl to initiate operations. The operations include retrieving properties and other data, updating properties and other data, and data enumeration and validation.

CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES

CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES

CLUSCTL_NETWORK_GET_CHARACTERISTICS

CLUSCTL_NETWORK_GET_COMMON_PROPERTIES

CLUSCTL_NETWORK_GET_FLAGS

CLUSCTL_NETWORK_GET_NAME

CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES

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 is used to retrieve a list of the common network properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_COMMON_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve the values for the read/write properties, call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code. To update them, use the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code. To validate them, use CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES.

To retrieve the values for the read-only properties, call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_ENUM_PRIVATE_PROPERTIES control code is used to retrieve a list of private network properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_PRIVATE_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve the values for the read/write properties, call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES control code. To update them, use the CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code. To validate them, use the CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES control code.

The CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES control code enables you to retrieve values for the read-only properties.

Note There are currently no private properties defined for networks.


CLUSCTL_NETWORK_GET_CHARACTERISTICS

The CLUSCTL_NETWORK_GET_CHARACTERISTICS control code is used to request the intrinsic characteristics of a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CHARACTERISTICS

Notes to Callers

The lpOutBuffer parameter of ClusterNetworkControl points to a bitmask that describes the network's characteristics. The bits can be set to the following value:

CHARACTERISTICS value | Description
CLUS_CHAR_UNKNOWN | Network has no known characteristics.


CLUSCTL_NETWORK_GET_COMMON_PROPERTIES

The CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code is used to request the read/write common properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to networks of any type and can be modified using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code. The following properties are returned:

Role

Description

For an overall description of the common network properties, see Common Network Properties.

To parse a property list, use the property list utility functions.


CLUSCTL_NETWORK_GET_FLAGS

The CLUSCTL_NETWORK_GET_FLAGS control code is used to request the flags that are set for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_FLAGS

Notes to Callers

ClusterNetworkControl returns a bitmask that describes the extrinsic attributes of the network. There are currently no flags defined for networks.


CLUSCTL_NETWORK_GET_NAME

The CLUSCTL_NETWORK_GET_NAME control code is used to retrieve the name of a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NAME

Notes to Callers

The name of a network is stored in the network's Name property. To retrieve the Name property along with the other common read-only network properties, call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES control code is used to request the read/write private properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply only to a specific network and can be modified using the CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

Note There are currently no private properties defined for networks.


CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES

The CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code is used to request the read-only common properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to all networks and cannot be modified using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code. The following properties are returned:

Name

Address

AddressMask

For an overall description of the common network properties, see Common Network Properties.

To parse the property list returned by ClusterNetworkControl, use the property list utility functions.


CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES control code is used to request the read-only private properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to the specific network and cannot be modified using the CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To parse the property list returned by ClusterNetworkControl, use the property list utility functions.

Note There are currently no private properties defined for networks.


CLUSCTL_NETWORK_SET_COMMON_PROPERTIES

The CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code is used to update the common properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_COMMON_PROPERTIES

Notes to Callers

The CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code enables you to set one or more of the read/write properties that apply to all networks. The following properties may be modified with CLUSCTL_NETWORK_SET_COMMON_PROPERTIES:

Description

Role

To retrieve the names and current values of the common network properties, use the CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code.

For an overall description of the common network properties, see Common Network Properties.

To construct a property list, use the property list utility functions.


CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code is used to update the private properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_SET_PRIVATE_PROPERTIES control code, pass a property list with the names and new values for the properties to update. This control code updates only those properties that are read/write and apply to a specific network type. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list, use the property list utility functions.

Note There are currently no private properties defined for networks.


CLUSCTL_NETWORK_UNKNOWN

The CLUSCTL_NETWORK_UNKNOWN control code indicates a request for an unknown operation. ClusterNetworkControl always returns ERROR_SUCCESS when the dwControlCode parameter is set to this code.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Control Code: | CLCTL_UNKNOWN


CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES control code is used to check whether or not specific properties and property values are valid as common network properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES control code, pass a property list with the names and values of all of the common read/write properties that you want to validate. A common property is a property that applies to all networks.

For an overall description of the common network properties, see Common Network Properties.

To build a property list, use the property list utility functions.


CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES control code is used to check whether or not specific properties and property values are valid as private properties for a network.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetworkControl with the CLUSCTL_NETWORK_VALIDATE_PRIVATE_PROPERTIES control code, pass a property list with the names and values for the read/write private properties to validate. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list, use the property list utility functions.

Note There are currently no private properties defined for networks.


Control Codes for Network Interfaces

All of the control codes relating to network interface operations appear in the following list. The codes are external control codes, or control codes that applications can pass to ClusterNetInterfaceControl to initiate operations. The operations include retrieving properties and other data, updating properties and other data, and data enumeration and validation.

CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES

CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES

CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS

CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES

CLUSCTL_NETINTERFACE_GET_FLAGS

CLUSCTL_NETINTERFACE_GET_NAME

CLUSCTL_NETINTERFACE_GET_NETWORK

CLUSCTL_NETINTERFACE_GET_NODE

CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES

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 is used to retrieve a list of the common network interface properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_COMMON_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve the values for the read/write properties, call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES control code. To update them, use the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code. To validate them, use CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES.

The CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code enables you to retrieve values for the read-only properties.


CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_ENUM_PRIVATE_PROPERTIES control code is used to retrieve a list of private network interface properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_PRIVATE_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve the values for the read/write properties, call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES control code. To update them, use the CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code. To validate them, use CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES.

The CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES control code enables you to retrieve values for the read-only properties.

Note There are currently no private properties defined for network interfaces.


CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS

The CLUSCTL_NETINTERFACE_GET_CHARACTERISTICS control code is used to request the intrinsic characteristics of a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CHARACTERISTICS

Notes to Callers

The lpOutBuffer parameter of ClusterNetInterfaceControl points to a bitmask that describes the network interface's characteristics. The bits can be set to the following value:

CHARACTERISTICS value | Description
CLUS_CHAR_UNKNOWN | Network interface has no known characteristics.


CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES control code is used to request the read/write common properties for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to all network interfaces and can be modified using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code. The Description property is the only common property for network interfaces that can be modified.

To parse the property list returned by ClusterNetInterfaceControl, use the property list utility functions.


CLUSCTL_NETINTERFACE_GET_FLAGS

The CLUSCTL_NETINTERFACE_GET_FLAGS control code is used to request the flags that are set for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_FLAGS

Notes to Callers

ClusterNetInterfaceControl returns a bitmask that describes the extrinsic attributes of the network interface. There are no flags currently defined for network interfaces.


CLUSCTL_NETINTERFACE_GET_NAME

The CLUSCTL_NETINTERFACE_GET_NAME control code is used to retrieve the name of a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NAME

Notes to Callers

The name of a network interface is stored in its Name property. To retrieve the Name property along with the other common read-only network interface properties, call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_NETINTERFACE_GET_NETWORK

The CLUSCTL_NETINTERFACE_GET_NETWORK control code is used to retrieve the name of the network to which a network interface is connected.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NETWORK

Notes to Callers

The network name is stored in the network interface's Network property. To retrieve the Network property along with the other common read-only properties for network interfaces, call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_NETINTERFACE_GET_NODE

The CLUSCTL_NETINTERFACE_GET_NODE control code is used to retrieve the name of the node in which a network interface is installed.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NODE

Notes to Callers

The name of the node is stored in the network interface's Node property. To retrieve the Node property along with the other common read-only network interface properties, call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES control code is used to request the read/write private properties for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply only to a specific network interface and to all others of its type and can be modified using the CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

Note There are currently no private properties defined for network interfaces.


CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code is used to request the read-only common properties for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to all network interfaces and cannot be modified using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code. The following properties are returned:

Adapter

Address

Name

Network

Node

For an overall description of the common network interface properties, see Common Network Interface Properties.

To parse the property list returned by ClusterNetInterfaceControl, use the property list utility functions.


CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES control code is used to request the read-only private properties for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to a specific network interface and cannot be modified using the CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

Note There are currently no private properties defined for network interfaces.


CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code is used to update the common properties of a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_COMMON_PROPERTIES

Notes to Callers

The CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code enables you to set one or more of the read/write properties that apply to all network interfaces. The following property may be modified with CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES:

Description

To retrieve the names and current values of the common network interface properties, use the CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES control code.

For an overall description of the common network interface properties, see Common Network Interface Properties.

To construct a property list to pass to ClusterNetInterfaceControl, use the property list utility functions.


CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code is used to update the private properties for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_SET_PRIVATE_PROPERTIES control code, pass a property list with the names and new values for the properties to update. This control code updates only those properties that are read/write and apply to a specific type of network interface. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list to pass to ClusterNetInterfaceControl, use the property list utility functions.

Note There are currently no private properties defined for network interfaces.


CLUSCTL_NETINTERFACE_UNKNOWN

The CLUSCTL_NETINTERFACE_UNKNOWN control code indicates a request for an unknown operation. ClusterNetInterfaceControl always returns ERROR_SUCCESS when the dwControlCode parameter is set to this code.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Control Code: | CLCTL_UNKNOWN


CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES control code is used to check whether or not specific properties and property values are valid as common network interface properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES control code, pass a property list with the names and values of all of the read/write common properties that you want to validate. A common property is a property that applies to all network interfaces regardless of their type.

For an overall description of the common network interface properties, see Common Network Interface Properties.

To build a property list to pass to ClusterNetInterfaceControl, use the property list utility functions.


CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES control code is used to check whether or not specific properties and property values are valid as private properties for a network interface.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNetInterfaceControl with the CLUSCTL_NETINTERFACE_VALIDATE_PRIVATE_PROPERTIES control code, pass a property list with the names and values for the read/write private properties to validate. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list to pass to ClusterNetInterfaceControl, use the property list utility functions.

Note There are currently no private properties defined for network interfaces.


Control Codes for Resources

All of the control codes relating to resources are included in the following two lists. The first list contains external control codes, or control codes that applications can pass to the control functions of the Cluster API to initiate operations. The operations include retrieving properties and other data, updating properties and other data, and data enumeration and validation.

CLUSCTL_RESOURCE_ADD_REGISTRY_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_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_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

The second list contains internal control codes, or control codes that only the Cluster Service can pass to a control function. The Cluster Service uses these codes to notify a resource DLL of an event. Resource DLLs may want to add code to their ResourceControl entry point functions to handle these codes and respond to the associated event.

CLUSCTL_RESOURCE_ADD_DEPENDENCY

CLUSCTL_RESOURCE_ADD_OWNER

CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED

CLUSCTL_RESOURCE_DELETE

CLUSCTL_RESOURCE_EVICT_NODE

CLUSCTL_RESOURCE_INSTALL_NODE

CLUSCTL_RESOURCE_REMOVE_DEPENDENCY

CLUSCTL_RESOURCE_REMOVE_OWNER

CLUSCTL_RESOURCE_SET_NAME

Typically, applications and the Cluster Service make calls to the control functions of the Cluster API and resource DLLs respond to those calls as appropriate. Resource DLLs do not typically call the control code functions. However, there are five control codes that are the exception to the rule. These control codes are processed by the Cluster Service rather than by a Resource Monitor or resource DLL. Therefore, a resource DLL can safely call ClusterResourceControl with the following control codes:

  • CLUSCTL_RESOURCE_GET_NAME
  • CLUSCTL_RESOURCE_GET_RESOURCE_TYPE
  • CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT
  • CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS
  • CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT


CLUSCTL_RESOURCE_ADD_DEPENDENCY

The CLUSCTL_RESOURCE_ADD_DEPENDENCY control code is used by the Cluster Service to notify a resource DLL that a dependency for the resource was added.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_ADD_DEPENDENCY

Notes to Resource DLL Writers

The Cluster Service calls your ResourceControl entry point function with the CLUSCTL_RESOURCE_ADD_DEPENDENCY control code when it adds a dependency for the resource. For example, if the resource is a Generic Application resource, this notification would occur when a Physical Disk resource upon which the application depends is added to the group to which the application belongs.

The InBuffer parameter always points to a Unicode string that contains the name of the resource being added as a dependency.


CLUSCTL_RESOURCE_ADD_OWNER

The CLUSCTL_RESOURCE_ADD_OWNER control code is used by the Cluster Service to notify a resource DLL that a node is being added as a possible owner of the resource.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_ADD_OWNER

Notes to Resource DLL Writers

The Cluster Service calls your ResourceControl entry point function with the CLUSCTL_RESOURCE_ADD_OWNER_NODE control code when a node is being added as a possible owner. The InBuffer parameter contains the name of the node being added.


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 will be replicated for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_ADD_REGISTRY_CHECKPOINT

Notes to Callers

Set the lpInBuffer parameter to point to a string that specifies the registry key name at the root of the subtree that should be replicated for this resource. This is a key name that is relative to HKEY_LOCAL_MACHINE, such as "Software\Microsoft\My Application". A leading backslash character ("\") should not be used with relative paths. If a leading backslash is used in the string passed to ClusterResourceControl in the lpInBuffer parameter, the call will fail.

To delete a registry checkpoint, use the CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT control code in your call to ClusterResourceControl.

Notes to Resource DLL Writers

Do not support the CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code in your ResourceControl entry point function. Return ERROR_INVALID_FUNCTION to indicate to the Resource Monitor that it should take over the processing.


CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED

The CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED control code is used by the Cluster Service to notify the resource DLL for the core Network Name resource that the name of the cluster is about to be changed.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_CLUSTER_NAME_CHANGED

Notes to Resource DLL Writers

Because the CLUSCTL_RESOURCE_CLUSTER_NAME_CHANGED control code is sent only to the core Network Name resource, resource DLLs that handle other resources should never handle it.


CLUSCTL_RESOURCE_DELETE

The CLUSCTL_RESOURCE_DELETE control code is used by the Cluster Service to notify a resource DLL that a resource is about to be deleted.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_DELETE

Notes to Resource DLL Writers

The Cluster Service calls your ResourceControl entry point function with the CLUSCTL_RESOURCE_DELETE control code when a resource is being deleted from the cluster. Handling this control code allows you to perform any cleanup tasks that may be necessary before the deletion occurs, such as removing temporary files. However, be careful of doing cleanup tasks for a resource if all of the nodes are not online.

Realize that when you receive this notification, the deletion is inevitable. You cannot prevent any of your resources from being deleted.


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.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_DELETE_REGISTRY_CHECKPOINT

Notes to Callers

Set the lpInBuffer parameter to point to a string that specifies the name of a registry key that was previously registered with the CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code. This is the key identifying the registry tree that will no longer be replicated by Cluster Service.

Notes to Resource DLL Writers

Avoid supporting the CLUSCTL_RESOURCE_DELETE_REGISTRY_CHECKPOINT control code. Allow the Resource Monitor to handle it by returning ERROR_INVALID_FUNCTION from your ResourceControl entry point function.


CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES control code is used to retrieve a list of the common resource properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_COMMON_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve the values for the read/write properties, call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code. To update them, use the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code. To validate them, use CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES.

The CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code enables you to retrieve values for the read-only properties.

Notes to Resource DLL Writers

Avoid supporting the CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES control code. Allow the Resource Monitor to handle it by returning ERROR_INVALID_FUNCTION from your ResourceControl entry point function. The Resource Monitor should handle all of the control codes for common properties.


CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES control code is used to retrieve a list of private resource properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_PRIVATE_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve the values for the read/write properties, call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code. To update them, use the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code. To validate them, use CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES.

The CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code enables you to retrieve values for the read-only properties.

Notes to Resource DLL Writers

Always support the CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES control code in your ResourceControl entry point function by returning the names of your private properties in the string array. However, if you do not provide support, the Resource Monitor returns what has been set for the resource.


CLUSCTL_RESOURCE_EVICT_NODE

The CLUSCTL_RESOURCE_EVICT_NODE control code is used by the Cluster Service to notify a resource DLL that a node is being permanently removed from the cluster.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_EVICT_NODE

Notes to Resource DLL Writers

The Cluster Service calls your ResourceControl entry point function with the CLUSCTL_RESOURCE_EVICT_NODE control code when a node is being permanently deleted from the cluster. You should support this control code if you need to store data that is node-specific. In your handling of this code, you can remove this data and perform any other necessary cleanup tasks.


CLUSCTL_RESOURCE_GET_CHARACTERISTICS

The CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code is used to request the intrinsic characteristics of a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CHARACTERISTICS

Notes to Callers

The lpOutBuffer parameter of ClusterResourceControl points to a bitmask that describes the resource's characteristics. The bits can be set to one or more of the following values:

CHARACTERISTICS value | Description
CLUS_CHAR_UNKNOWN | Resource has no known characteristics.
CLUS_CHAR_QUORUM | Resource is capable of being the quorum resource for a cluster.
CLUS_CHAR_DELETE_ REQUIRES_ALL_NODES | Resource requires delete notification on all nodes.

Cluster Server's Physical Disk resources return CLUS_CHAR_QUORUM and CLUS_CHAR_DELETE_REQUIRES_ALL_NODES from a CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code request.

Notes to Resource DLL Writers

If you do not handle the CLUSCTL_RESOURCE_GET_CHARACTERISTICS control code in your ResourceControl entry point function, return ERROR_INVALID_FUNCTION. The Resource Monitor will read the Characteristics value from the resource's key in the cluster database.

If you do support CLUSCTL_RESOURCE_GET_CHARACTERISTICS, return a value that accurately describes your resource. A resource DLL that manages resources incapable of functioning as quorum resources must not, for example, return CLUS_CHAR_QUORUM. Doing so can cause the cluster to become unusable if a resource of the type managed by the resource DLL is chosen as the quorum resource. Likewise, when a resource DLL for quorum resources does not set the CLUS_CHAR_QUORUM bit, its resources will not be able to be selected as quorum resources.

Setting CLUS_CHAR_DELETE_REQUIRES_ALL_NODES indicates that all nodes must be online before a resource handled by your resource DLL can be deleted. The reason for the advance warning is to provide your DLL with the opportunity to remove any information from one or more nodes. For example, if your resource DLL stores data in a portion of the cluster database or in an alternate location, you will probably want to return the CLUS_CHAR_DELETE_REQUIRES_ALL_NODES as a characteristic so that you receive the delete notification. The Cluster Service notifies a resource DLL by calling its ResourceControl function with the CLUSCTL_RESOURCE_DELETEcontrol code. Note that you can get these notifications regardless of whether the CLUS_CHAR_DELETE_REQUIRES_ALL_NODES characteristic bit is set; setting the bit guarantees it.

When a resource DLL returns the CLUS_CHAR_DELETE_REQUIRES_ALL_NODES characteristic, all nodes must be online in order for resources of that type to be deleted. If all nodes are not online, the delete attempt fails and the DeleteClusterResource function returns ERROR_HOST_NODE_NOT_AVAILABLE.


CLUSCTL_RESOURCE_GET_CLASS_INFO

The CLUSCTL_RESOURCE_GET_CLASS_INFO control code is used to request the class and subclass of a resource. A resource class identifies resources of similar capability.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | CLUS_RESOURCE_CLASS_INFO structure
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CLASS_INFO

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_CLASS_INFO, it returns a CLUS_RESOURCE_CLASS_INFO structure that describes the class and subclass of the resource. The subclass is a value that is specific to the class and provides more description, such as CLUS_RESSUBCLASS_SHARED. This subclass is valid for storage class resources such as Physical Disk resources and indicates that the resource is accessible to more than one node in the cluster.

Cluster Service will not recognize a user-defined resource class, as indicated by the rc member of the CLUS_RESOURCE_CLASS_INFO being set to a value greater than CLUS_RESCLASS_USER. CLUS_RESCLASS_USER marks the beginning of the user-defined range for resource classes. However, custom resource classes can be recognized and used by cluster-aware applications and resource DLLs.

Notes to Resource DLL Writers

If you define your own resource class, you 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, send mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

If you do not support the CLUSCTL_RESOURCE_GET_CLASS_INFO control code, return ERROR_INVALID_FUNCTION. The Resource Monitor provides default handling of this control code by returning CLUS_RESCLASS_UNKNOWN as the class and zero as the subclass.


CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code is used to request the read/write common properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to resources of any type and can be modified using the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code. The following properties are returned:

DebugPrefix

Description

IsAlivePollInterval

LooksAlivePollInterval

PendingTimeout

PersistentState

RestartAction

RestartPeriod

RestartThreshold

SeparateMonitor

Type

For an overall description of the common resource properties, see Common Resource Properties.

To parse a property list, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code in your ResourceControl entry point function. Instead, have ResourceControl return ERROR_INVALID_FUNCTION. The Resource Monitor handles CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_GET_FLAGS

The CLUSCTL_RESOURCE_GET_FLAGS control code is used to request the flags that are set for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_FLAGS

Notes to Callers

ClusterResourceControl returns a bitmask that describes the extrinsic attributes of the resource. The following flag is defined by the Cluster Service as valid:

CLUS_FLAG_CORE

When CLUS_FLAG_CORE is set, this indicates that the resource is essential to the cluster and cannot be deleted. Included in this group of essential resources are:

  • IP Address resource of the cluster
  • Network Name resource of the cluster
  • Quorum resource

Because only the lower 16 bits of the bitmask are reserved for Microsoft internal use, flags defined by third-party developers can also be returned.

Notes to Resource DLL Writers

Resource DLLs can define their own resource-specific flags in the upper 16 bits of the bitmask returned with CLUSCTL_RESOURCE_GET_FLAGS. The lower 16 bits of the bitmask are reserved for Microsoft internal use. If your resource DLL needs to define flags, handle the CLUSCTL_RESOURCE_GET_FLAGS control code in your ResourceControl entry point function. Otherwise, return ERROR_INVALID_FUNCTION to let the Resource Monitor handle it. The Resource Monitor will read the Flags value from the resource's key in the cluster database.


CLUSCTL_RESOURCE_GET_NAME

The CLUSCTL_RESOURCE_GET_NAME control code is used to retrieve the name of a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NAME

Notes to Callers

The name of a resource is stored in the resource's Name property. To retrieve the Name property along with the other common read-only resource properties, call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code.

Notes to Resource DLL Writers

Handling CLUSCTL_RESOURCE_GET_NAME is optional. Default functionality is provided by the Resource Monitor.


CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code is used to request the read/write private properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply only to the specific resource and to all others of its type and can be modified using the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To parse the property list returned by ClusterResourceControl, use the property list utility functions.

For an overall description of the private properties for resources belonging to the Cluster Server resource types, see Private Resource Properties.

Notes to Resource DLL Writers

Resource DLLs should always support the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code in their ResourceControl entry point functions. If you do not support this control code, the command tool CLUSTER.EXE cannot set any non string properties that have not already been set. The output should be a property list that includes the names and data values for all of the read/write properties specific to your resource. It is important to remember to terminate the list with a final entry that contains only the CLUSPROP_SYNTAX_ENDMARK value.

The Resource Monitor does not provide any default handling of this control code.


CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS

The CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS control code is used to request a list of all set checkpoints for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_REGISTRY_CHECKPOINTS

Notes to Callers

ClusterResourceControl returns in the lpOutBuffer parameter a pointer to a list of registry keys. Each key is one of the REG_MULTI_SZ registry keys that has previously been added to the resource's list of checkpoints with the CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code.

Notes to Resource DLL Writers

If your resource DLL needs to replicate a portion of the system registry, you must support the CLUSCTL_RESOURCE_GET_REGISTRY_CHECKPOINTS control code. Otherwise, allow the Resource Monitor to handle it by returning ERROR_INVALID_FUNCTION from your ResourceControl entry point function.


CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES

The CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code is used to request a list of all required dependencies for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Value list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_REQUIRED_DEPENDENCIES

Notes to Callers

ClusterResourceControl returns a value list when you pass CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES that indicates the resources upon which the specific resource depends. For example, if you request the required dependencies for a Print Spooler resource, it will typically return two entries in its value list: an entry for a storage device resource such as a Physical Disk and a Network Name resource.

All of the entries in the value list except the final one are CLUSPROP_REQUIRED_DEPENDENCY structures. This structure describes dependencies using either a resource class or a resource type. When you are parsing the value list, use the Value member of each entry to determine whether the dependency is being described as a resource class or type. The final entry contains only the CLUSPROP_SYNTAX_ENDMARK value.

Notes to Resource DLL Writers

If your resource has required dependencies, you must support the CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES control code in your ResourceControl entry point function. Return a value list that is terminated with the CLUSPROP_SYNTAX value CLUSPROP_SYNTAX_ENDMARK. The other entries should include a CLUSPROP_REQUIRED_DEPENDENCY union. This union describes a dependency in one of three ways:

  • By its format, type, and length using the standard CLUSPROP_VALUE header structure.
  • By its resource class.
  • By its resource type.

Resource class is a numeric value that identifies resources of similar capability. For example, CLUS_RESCLASS_STORAGE identifies resources that are capable of storing data. Third-party developers can create their own resource classes; user-defined classes are identified with the CLUS_RESCLASS_USER storage class.

In the example described in the Notes to Callers section, a Print Spooler resource has required dependencies on a storage class device and a Network Name resource. You would return a value list with two entries preceding the final one: one entry with the ResClass member of the CLUSPROP_REQUIRED_DEPENDENCY structure set to CLUS_RESCLASS_STORAGE and a second entry with the ResTypeName member set to "Network Name."


CLUSCTL_RESOURCE_GET_RESOURCE_TYPE

The CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code is used to request the type name for a resource.

Quick Info

Type: | External
Input: | None
Output: | Null-terminated Unicode string
Access: | CLUS_ACCESS_READ
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RESOURCE_TYPE

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code, realize that what is returned is not the display name for the resource type. It is the name that can be:

  • Used to determine if required dependencies have been met.
  • Passed to ClusterResourceTypeControl in the contents of the ResourceTypeName parameter to invoke resource type operations.
  • Passed to GetClusterResourceKey in the contents of the lpszTypeName parameter.
  • Returned by ClusterOpenEnum when you specify CLUSTER_ENUM_RESTYPE in the dwType parameter.

The display name for a resource type is its Name property and is one of the common resource type properties.

Notes to Resource DLL Writers

Resource DLLs need not support the CLUSCTL_RESOURCE_GET_RESOURCE_TYPE control code; the Resource Monitor always provides default handling.


CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code is used to request the read-only common properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to resources of any type and cannot be modified using the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code.

The Name property is the only read-only common property for resources.

For an overall description of the common resource properties, see Common Resource Properties.

To parse the property list returned by ClusterResourceControl, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES control code in your ResourceControl entry point function. Instead, have ResourceControl return ERROR_INVALID_FUNCTION. CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES should be handled by the Resource Monitor because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code is used to request the read-only private properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_PRIVATE_PROPERTIES

Remarks

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to the specific resource and cannot be modified using the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To parse the property list returned by ClusterResourceControl, use the property list utility functions.

For an overall description of the private properties for resources belonging to the Cluster Server resource types, see Private Resource Properties.

Notes to Resource DLL Writers

Resource DLLs must always support the CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code in their ResourceControl entry point functions. If you do not support this control code, the command tool CLUSTER.EXE cannot set any non string properties that have not already been set. The output should be a property list that includes the names and data values for all of the read-only properties specific to their resource, if there are any. It is important to remember to terminate the list with a final entry that contains only the CLUSPROP_SYNTAX_ENDMARK value.

The Resource Monitor does not provide any default handling of this control code.


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.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_INSTALL_NODE

Notes to Resource DLL Writers

The Cluster Service calls your ResourceControl entry point function with the CLUSCTL_RESOURCE_INSTALL_NODE control code when a node is being added to the cluster. The contents of InBuffer is set to the name of the newly added node. You may choose to support this code if you have any tasks that must be performed when a new node is added to a cluster.


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 for the resource was removed.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_REMOVE_DEPENDENCY

Notes to Resource DLL Writers

The Cluster Service calls a resource DLL's ResourceControl entry point function with the CLUSCTL_RESOURCE_REMOVE_DEPENDENCY control code when it removes a dependency for the resource. The InBuffer parameter always points to a Unicode string that contains the name of the resource being removed as a dependency. Support this control code if you need to perform any tasks as a result of a dependency being removed.


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 as a possible owner of the resource.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_REMOVE_OWNER

Notes to Resource DLL Writers

The Cluster Service calls a resource DLL's ResourceControl entry point function with the CLUSCTL_RESOURCE_REMOVE_OWNER control code when a node is being removed as a possible owner of the resource. The InBuffer parameter points to the name of the node being removed. Support this control code only if you need to perform any tasks when your possible owner list is altered.


CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code is used to update the common properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code, pass a property list with the names and new values for the properties to update. The following properties may be modified with CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES:

DebugPrefix

Description

IsAlivePollInterval

LooksAlivePollInterval

PendingTimeout

PersistentState

RestartAction

RestartPeriod

RestartThreshold

SeparateMonitor

Type

To retrieve the names and current values of the common resource properties, use the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code.

For an overall description of the common resource properties, see Common Resource Properties.

To construct a property list, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code. Instead, return ERROR_INVALID_FUNCTION from your ResourceControl entry point function. CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES is handled by the Resource Monitor because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_SET_NAME

The CLUSCTL_RESOURCE_SET_NAME control code is used by the Cluster Service to notify the resource DLL that the name of a resource is being changed.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_NAME

Notes to Resource DLL Writers

Handle the CLUSCTL_RESOURCE_SET_NAME control code if you need to perform any tasks when the name of your resource changes.


CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code is used to update the private properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code, pass a property list with the names and new values for the properties to update. This control code updates only those properties that are read/write and apply to a specific resource type. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To build a property list, use the property list utility functions.

For an overall description of the private properties for resources belonging to the Cluster Server resource types, see Private Resource Properties.

Notes to Resource DLL Writers

Resource DLLs should always support the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code in their ResourceControl entry point functions. By providing support for this code, you can insure that only properties and property values known to the resource can be specified.

The output should be a property list that includes the names and data values for all of the read/write properties specific to your resource. It is important to remember to terminate the list with a final entry that contains only the CLUSPROP_SYNTAX_ENDMARK value.

If you do not support the CLUSTCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code in your ResourceControl entry point function, then the Resource Monitor uses the information in the input buffer to update the cluster database.


CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO

The CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO control code is used to request information about a particular disk resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Value list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_STORAGE_GET_DISK_INFO

Notes to Callers

ClusterResourceControl returns a value list, a collection of one or more values consisting of a CLUSPROP_VALUE structure and data. The CLUSPROP_SYNTAX portion of the CLUSPROP_VALUE structure can be set to one of the following values:

CLUSPROP_SYNTAX_DISK_INFO

CLUSPROP_SYNTAX_PARTITION_INFO

CLUSPROP_SYNTAX_SCSI_ADDRESS

CLUSPROP_SYNTAX_SIGNATURE

For each assigned drive letter, there is one entry in the value list with the Syntax member of the CLUSPROP_VALUE structure set to CLUSPROP_SYNTAX_PARTITION_INFO.

Notes to Resource DLL Writers

Support the CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO control code in your resource DLL if it handles storage class resources such as quorum-capable resources.


CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID

The CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID control code is used to verify a path to a storage class resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_STORAGE_IS_PATH_VALID

Notes to Callers

Pass in the contents of the lpInBuffer parameter to ClusterResourceControl a directory path that excludes the file name.

Notes to Resource DLL Writers

Support the CLUSCTL_RESOURCE_STORAGE_IS_PATH_VALID control code if your resources are storage class resources by returning ERROR_SUCCESS if the path specified as input is valid.


CLUSCTL_RESOURCE_UNKNOWN

The CLUSCTL_RESOURCE_UNKNOWN control code is used to test whether or not a resource DLL supports control code processing for resources.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Control Code: | CLCTL_UNKNOWN

Notes to Callers

A return value of ERROR_SUCCESS from ClusterResourceControl when you pass the CLUSCTL_RESOURCE_UNKNOWN control code indicates that your application is communicating directly with a resource DLL that supports control code processing rather than through a Resource Monitor. A return value of ERROR_INVALID_FUNCTION indicates that your application is not communicating directly with a resource DLL.

Notes to Resource DLL Writers

If you support any other control codes for resources, return ERROR_SUCCESS from ResourceControl when CLUSCTL_RESOURCE_UNKNOWN is passed in. If you do not support any other resource control codes, return ERROR_INVALID_FUNCTION.


CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES control code is used to check whether or not specific properties and property values are valid as common resource properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES control code, pass a property list with the names and values of all of the common read/write properties that you want to validate. A common property is a property that applies to all resources regardless of their type.

For an overall description of the common resource properties, see Common Resource Properties.

To build a property list, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES control code. Instead, return ERROR_INVALID_FUNCTION from your ResourceControl entry point function. CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES is handled by the Resource Monitor because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES control code is used to check whether or not specific properties and property values are valid as private properties for a resource.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceControl with the CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES control code, pass a property list with the names and values for the private read/write properties to validate. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To build a property list, use the property list utility functions.

For an overall description of the private properties for resources belonging to the Cluster Server resource types, see Private Resource Properties.

Notes to Resource DLL Writers

Resource DLLs should handle the CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES control code in their ResourceControl entry point functions. They should check that the properties specified in the contents of the InBuffer parameter are valid for the resource.

If you cannot support this control code, the Resource Monitor validates that the property list is formatted correctly. It does not actually validate the data.


Control Codes for Resource Types

All of the control codes relating to resource types are included in the following two lists. The first list contains external control codes, or control codes that applications can pass to the control functions of the Cluster API to initiate operations. The operations include retrieving properties and other data, updating properties and other data, and data enumeration and validation.

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_FLAGS

CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES

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_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

The second list contains internal control codes, or control codes that only the Cluster Service can pass to a control function. The Cluster Service uses these codes to notify a resource DLL of an event. Resource DLLs may want to add code to their ResourceTypeControl entry point functions to handle these codes and respond to the associated event.

CLUSCTL_RESOURCE_TYPE_INSTALL_NODE

CLUSCTL_RESOURCE_TYPE_EVICT_NODE


CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES control code is used to retrieve a list of the common resource type properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_COMMON_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve values for the read/write properties, call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code. To update them, use the CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code. To validate them, use CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES.

The CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES control code enables you to retrieve values for the read-only properties.

Notes to Resource DLL Writers

Avoid supporting the CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES control code. Allow the Resource Monitor to handle it by returning ERROR_INVALID_FUNCTION from your ResourceTypeControl entry point function. The Resource Monitor should handle all of the control codes for common properties.


CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES control code is used to retrieve a list of private resource type properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_PRIVATE_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve values for the read/write properties, call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES control code. To update them, use the CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code. To validate them, use CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES.

The CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES control code enables you to retrieve values for the read-only properties.

Notes to Resource DLL Writers

Always support the CLUSCTL_RESOURCE_TYPE_ENUM_PRIVATE_PROPERTIES control code in your ResourceTypeControl entry point function by returning the names of your private properties in the string array. However, if you do not support this control code, the Resource Monitor returns what has been set for the resource type.


CLUSCTL_RESOURCE_TYPE_EVICT_NODE

The CLUSCTL_RESOURCE_TYPE_EVICT_NODE control code is used by the Cluster Service to notify a resource DLL that a node is being permanently removed from the cluster.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_EVICT_NODE

Notes to Resource DLL Writers

The Cluster Service calls your ResourceTypeControl entry point function with the CLUSCTL_RESOURCE_TYPE_EVICT_NODE control code when a node is being permanently deleted from the cluster. This can occur when an application calls the Cluster API function EvictClusterNode.

You should support this control code if you need to store data that is node-specific. In your handling of this code, you can remove this data and perform any other necessary cleanup tasks.


CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS

The CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS control code is used to request the intrinsic characteristics of a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CHARACTERISTICS

Notes to Callers

The lpOutBuffer parameter of ClusterResourceTypeControl points to a bitmask that describes the resource type's characteristics. The bits can be set to one or more of the following values:

CHARACTERISTICS value | Description
CLUS_CHAR_UNKNOWN | Resource type has no known characteristics.
CLUS_CHAR_QUORUM | Resources of this type are capable of being the quorum resources for a cluster.
CLUS_CHAR_DELETE_ REQUIRES_ALL_NODES | Resources of this type require delete notification on all nodes.

Cluster Server's Physical Disk resources return CLUS_CHAR_QUORUM and CLUS_CHAR_DELETE_REQUIRES_ALL_NODES from a CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS control code request.

Notes to Resource DLL Writers

If you do not support the CLUSCTL_RESOURCE_TYPE_GET_CHARACTERISTICS control code, return ERROR_INVALID_FUNCTION. The Resource Monitor provides default functionality by setting the CLUS_CHAR_QUORUM bit if your resource DLL provides the Arbitrate and Release entry points in the function table that Startup returns.


CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO

The CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO control code is used to request the class and subclass of a resource type. A resource class identifies resources of similar capability.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | CLUS_RESOURCE_CLASS_INFO structure
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CLASS_INFO

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO, it returns a CLUS_RESOURCE_CLASS_INFO structure that describes the class and subclass of the resource type. The subclass is a value that is specific to the class and provides more description, such as CLUS_RESSUBCLASS_SHARED. This subclass is valid for storage class resources such as Physical Disk resources and indicates that the resource is accessible to more than one node in the cluster.

Cluster Service will not recognize a user-defined resource class, as indicated by the rc member of the CLUS_RESOURCE_CLASS_INFO being set to a value greater than CLUS_RESCLASS_USER. CLUS_RESCLASS_USER marks the beginning of the user-defined range for resource classes. However, custom resource classes can be recognized and used by cluster-aware applications and resource DLLs.

Notes to Resource DLL Writers

If you define your own resource class, you 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, send mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

If you do not support the CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO control code, return ERROR_INVALID_FUNCTION. The Resource Monitor provides default handling of this control code.


CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code is used to request the read/write common properties of a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply to resources of any type and can be modified using the CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code. The following properties are returned:

AdminExtensions

DebugControlFunctions

DebugPrefix

Description

DllName

IsAlivePollInterval

LooksAlivePollInterval

Name

For an overall description of the common resource type properties, see Common Resource Type Properties.

To parse a property list, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code in your ResourceTypeControl entry point function. Instead, have ResourceTypeControl return ERROR_INVALID_FUNCTION. The Resource Monitor handles CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_TYPE_GET_FLAGS

The CLUSCTL_RESOURCE_TYPE_GET_FLAGS control code is used to request the flags that are set for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_FLAGS

Notes to Callers

ClusterResourceTypeControl returns a bitmask that describes the extrinsic attributes of the resource type. Currently, Cluster Server does not define any flags for resource types. However, because only the lower 16 bits of the bitmask are reserved for Microsoft's internal use, third-party developers can define and return their own flags.

Notes to Resource DLL Writers

Resource DLLs can define their own resource type-specific flags in the upper 16 bits of the bitmask returned with CLUSCTL_RESOURCE_TYPE_GET_FLAGS. The lower 16 bits of the bitmask are reserved for Microsoft's internal use. If your resource DLL needs to define a flag, handle the CLUSCTL_RESOURCE_TYPE_GET_FLAGS control code in your ResourceTypeControl entry point function. Otherwise, return ERROR_INVALID_FUNCTION to let the Resource Monitor handle it.


CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES control code is used to request the read/write private properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply only to the specific resource type and can be modified using the CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To parse the property list returned by ClusterResourceTypeControl, use the property list utility functions.

Notes to Resource DLL Writers

Resource DLLs should support the CLUSCTL_RESOURCE_TYPE_GET_PRIVATE_PROPERTIES control code in their ResourceTypeControl entry point functions by returning a property list with all properties specific to the resource type. If you do not support this control code, the command tool CLUSTER.EXE cannot set any non-string properties that have not already been set.


CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS

The CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS control code is used to request a list of all of the checkpoints that the resource type requires or sets.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_REGISTRY_CHECKPOINTS

Notes to Callers

ClusterResourceTypeControl returns in the lpOutBuffer parameter a pointer to a list of registry keys. Each key is one of the REG_MULTI_SZ registry keys that have previously been added to the list of checkpoints for a resource belonging to the resource type with the CLUSCTL_RESOURCE_ADD_REGISTRY_CHECKPOINT control code.

Notes to Resource DLL Writers

If your resource type needs to replicate a portion of the system registry, you must support the CLUSCTL_RESOURCE_TYPE_GET_REGISTRY_CHECKPOINTS control code. Otherwise, allow the Resource Monitor to handle it by returning ERROR_INVALID_FUNCTION from your ResourceTypeControl entry point function.


CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES

The CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES control code is used to request a list of all required dependencies for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Value list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_REQUIRED_DEPENDENCIES

Notes to Callers

ClusterResourceTypeControl returns a value list when you pass CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES that indicates the resources upon which the specific resource type depends. For example, if you request the required dependencies for a Print Spooler resource, it will typically return two entries in its value list: an entry for a storage device resource such as a Physical Disk and a Network Name resource.

All of the entries in the value list except the final one are CLUSPROP_REQUIRED_DEPENDENCY structures. This structure describes dependencies using either a resource class or a resource type. When you are parsing the value list, use the Value member of each entry to determine whether the dependency is being described as a resource class or type. The final entry contains only the CLUSPROP_SYNTAX_ENDMARK value.

Notes to Resource DLL Writers

If your resources have required dependencies, you must support the CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES control code in your ResourceTypeControl entry point function. Return a value list that is terminated with the CLUSPROP_SYNTAX value CLUSPROP_SYNTAX_ENDMARK. The other entries should include a CLUSPROP_REQUIRED_DEPENDENCY union. This union describes a dependency in one of three ways:

  • By its format, type, and length using the standard CLUSPROP_VALUE header structure
  • By its resource class
  • By its resource type

Resource class is a numeric value that identifies resources of similar capability. For example, CLUS_RESCLASS_STORAGE identifies resources that are capable of storing data. Third-party developers can create their own resource classes; user-defined classes are identified with the CLUS_RESCLASS_USER storage class.

In the example described in the Notes to Callers section, a Print Spooler resource has required dependencies on a storage class device and a Network Name resource. You would return a value list with two entries preceding the final one: one entry with the ResClass member of the CLUSPROP_REQUIRED_DEPENDENCY structure set to CLUS_RESCLASS_STORAGE and a second entry with the ResTypeName member set to "Network Name."


CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES control code is used to request the read-only common properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to all resource types and cannot be modified using the CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code.

The DllName property is the only read-only common property for resource types.

For an overall description of the common resource type properties, see Common Resource Type Properties.

To parse the property list returned by ClusterResourceTypeControl, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_GET_TYPE_RO_COMMON_PROPERTIES control code in your ResourceTypeControl entry point function. Instead, have ResourceTypeControl return ERROR_INVALID_FUNCTION. CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES should be handled by the Resource Monitor because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES control code is used to request the read-only private properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply only to the specific resource type and cannot be modified using the CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To parse the property list returned by ClusterResourceTypeControl, use the property list utility functions.

Notes to Resource DLL Writers

Resource DLLs must always support the CLUSCTL_RESOURCE_TYPE_GET_RO_PRIVATE_PROPERTIES control code in their ResourceTypeControl entry point function. The output should be a property list that includes the names and data values for all of the read-only properties specific to their resource type, if there are any. It is important to remember to terminate the list with a final entry that contains only the CLUSPROP_SYNTAX_ENDMARK value.

The Resource Monitor does not provide any default handling of this control code.


CLUSCTL_RESOURCE_TYPE_INSTALL_NODE

The CLUSCTL_RESOURCE_TYPE_INSTALL_NODE control code is used by the Cluster Service to notify a resource DLL that a node is being added to the cluster.

Quick Info

Type: | Internal
Access: | CLUS_ACCESS_WRITE
Input: | Null-terminated Unicode string
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_INSTALL_NODE

Notes to Resource DLL Writers

The Cluster Service calls your ResourceTypeControl entry point function with the CLUSCTL_RESOURCE_TYPE_INSTALL_NODE control code when a node is being added to the cluster. The contents of InBuffer are set to the name of the newly added node. You may choose to support this code if you have any tasks that must be performed when a new node is added to a cluster.


CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code is used to update the common properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code, pass a property list with the names and new values for the properties to update. The following properties may be included in the property list:

AdminExtensions

DebugControlFunctions

DebugPrefix

Description

DllName

IsAlivePollInterval

LooksAlivePollInterval

Name

To retrieve the names and current values of the common resource type properties, use the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code.

For an overall description of the common resource type properties, see Common Resource Type Properties.

To construct a property list, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES control code. Instead, return ERROR_INVALID_FUNCTION from your ResourceTypeControl entry point function. CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES is handled by the Resource Monitor because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code is used to update the private properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code, pass a property list with the names and new values for the properties to update. This control code updates only those properties that are read/write and apply to a specific resource type. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To build a property list, use the property list utility functions.

Notes to Resource DLL Writers

Resource DLLs should support the CLUSCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code rather than depending on the Resource Monitor. By providing support for this code, you can insure that only properties and property values known to the resource can be specified.

If you do not support the CLUSTCTL_RESOURCE_TYPE_SET_PRIVATE_PROPERTIES control code in your ResourceTypeControl entry point function, then the Resource Monitor uses the information in the input buffer to update the cluster database.


CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS

The CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code is used to request information about available disk resources.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Value list
Global: | CLUS_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_STORAGE_GET_AVAILABLE_DISKS

Notes to Callers

ClusterResourceTypeControl returns a value list, a collection of one or more values consisting of a CLUSPROP_VALUE structure and data. The value list contains entries for all available disks on all nodes in the cluster. No filtering is done, so there can be duplicate entries.

Notes to Resource DLL Writers

Support the CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code in your resource DLL if it handles a storage class resource type.


CLUSCTL_RESOURCE_TYPE_UNKNOWN

The CLUSCTL_RESOURCE_TYPE_UNKNOWN control code is used to test whether or not a resource DLL supports control code processing for resource types.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Control Code: | CLCTL_UNKNOWN

Notes to Callers

A return value of ERROR_SUCCESS from ClusterResourceTypeControl when you pass the CLUSCTL_RESOURCE_TYPE_UNKNOWN control code indicates that your application is communicating directly with a resource DLL that supports control code processing rather than through a Resource Monitor. A return value of ERROR_INVALID_FUNCTION indicates that your application is not communicating directly with a resource DLL.

Notes to Resource DLL Writers

If you support any other control codes for resource types, return ERROR_SUCCESS from ResourceTypeControl. If you do not support any other resource type control codes, return ERROR_INVALID_FUNCTION.


CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES control code is used to check whether or not specific properties are valid common properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_COMMON_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES control code, pass a property list with the names and values of all the common read/write properties that you want to validate. A common property is a property that applies to all resource types.

For an overall description of the common resource type properties, see Common Resource Type Properties.

To build a property list, use the property list utility functions.

Notes to Resource DLL Writers

Do not handle the CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES control code. Instead, return ERROR_INVALID_FUNCTION from your ResourceTypeControl entry point function. CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES is handled by the Resource Monitor because it is aware of the valid formats and values for these properties.


CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES control code is used to check whether or not specific properties are valid private properties for a resource type.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterResourceTypeControl with the CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES control code, pass a property list with the names and values for the private read/write properties to validate. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.
  • Static values not stored in the cluster database.

To build a property list, use the property list utility functions.

Notes to Resource DLL Writers

Resource DLLs should handle the CLUSCTL_RESOURCE_TYPE_VALIDATE_PRIVATE_PROPERTIES control code in their ResourceTypeControl entry point functions. They should check that the properties specified in the InBuffer parameter are valid for the resource.

If you cannot support this control code, the Resource Monitor validates that the property list is formatted correctly. It does not actually validate the data.


Control Codes for Groups

All of the control codes relating to groups are included in the following list. In the list are external control codes, or control codes that applications can pass to the control functions of the Cluster API to initiate operations. The operations include retrieving properties and other data, updating properties and other data, and data enumeration and validation. There are no internal control codes for group operations.

CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES

CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES

CLUSCTL_GROUP_GET_CHARACTERISTICS

CLUSCTL_GROUP_GET_COMMON_PROPERTIES

CLUSCTL_GROUP_GET_FLAGS

CLUSCTL_GROUP_GET_NAME

CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES

CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES

CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES

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 is used to retrieve a list of the common group properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_COMMON_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve values for the read/write properties, call ClusterGroupControl with the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code. To update them, use the CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code. To validate them, use CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES.

The CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code enables you to retrieve values for the read-only properties.


CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_ENUM_PRIVATE_PROPERTIES control code is used to retrieve a list of the private group properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_PRIVATE_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve values for the read/write properties, call ClusterGroupControl with the CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES control code. To update them, use the CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code. To validate them, use CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES.

The CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES control code enables you to retrieve values for the read-only properties.


CLUSCTL_GROUP_GET_CHARACTERISTICS

The CLUSCTL_GROUP_GET_CHARACTERISTICS control code is used to request a mask that describes the intrinsic characteristics of a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CHARACTERISTICS

Notes to Callers

The lpOutBuffer parameter of ClusterGroupControl points to a bitmask that describes the group's characteristics. The bits can be set to the following value:

CHARACTERISTICS value | Description
CLUS_CHAR_UNKNOWN | Group has no known characteristics.


CLUSCTL_GROUP_GET_COMMON_PROPERTIES

The CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code is used to request the read/write common properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to all groups and can be modified using the CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code. The following properties are returned:

AutoFailbackType

Description

FailbackWindowStart

FailbackWindowEnd

FailoverThreshold

FailoverPeriod

PersistentState

For an overall description of the common group properties, see Common Group Properties.

To parse a property list, use the property list utility functions.


CLUSCTL_GROUP_GET_FLAGS

The CLUSCTL_GROUP_GET_FLAGS control code is used to request a bitmask describing the flags that are currently set for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_FLAGS

Notes to Callers

ClusterGroupControl returns a bitmask that describes the extrinsic attributes of the group. There are currently no flags defined for groups.


CLUSCTL_GROUP_GET_NAME

The CLUSCTL_GROUP_GET_NAME control code is used to request the name of a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NAME

Notes to Callers

The name of a group is stored in the group's Name property. To retrieve the Name property along with the other common read-only group properties, call ClusterGroupControl with the CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES control code is used to request the read/write private properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_GET_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply only to a specific group and can be modified using the CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To parse the property list returned by ClusterGroupControl, use the property list utility functions.

Note There are currently no private properties defined for groups.


CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES

The CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code is used to request the read-only common properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_COMMON_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to all groups and cannot be modified using the CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code.

The Name property is the only read-only common property for groups.

To parse the property list returned by ClusterGroupControl, use the property list utility functions.


CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES control code is used to request the read-only private properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply only to the specific group and cannot be modified using the CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To parse the property list returned by ClusterGroupControl, use the property list utility functions.

Note There are currently no private properties defined for groups.


CLUSCTL_GROUP_SET_COMMON_PROPERTIES

The CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code is used to update the common properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_SET_COMMON_PROPERTIES control code, pass a property list with the names and new values for the properties to update. The following properties may be included in the property list:

AutoFailbackType

Description

FailbackWindowStart

FailbackWindowEnd

FailoverThreshold

FailoverPeriod

PersistentState

To retrieve the names and current values of the common group properties, use the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code.

For an overall description of the common group properties, see Common Group Properties.

To construct a property list, use the property list utility functions.


CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code is used to update the private properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_SET_PRIVATE_PROPERTIES control code, pass a property list with the names and new values for the properties to update. This control code updates only those properties that are read/write and apply to a specific group. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list, use the property list utility functions.

Note There are currently no private properties defined for groups.


CLUSCTL_GROUP_UNKNOWN

The CLUSCTL_GROUP_UNKNOWN control code indicates a request for an unknown operation. ClusterGroupControl always returns ERROR_SUCCESS when the dwControlCode parameter is set to this code.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Control Code: | CLCTL_UNKNOWN


CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES control code is used to check whether or not specific properties are valid common properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_COMMON_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES control code, pass a property list with the names and values of all of the common read/write properties that you want to validate. A common property is a property that applies to all groups.

For an overall description of the common group properties, see Common Group Properties.

To build a property list, use the property list utility functions.


CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES control code is used to check whether or not specific properties are valid private properties for a group.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterGroupControl with the CLUSCTL_GROUP_VALIDATE_PRIVATE_PROPERTIES control code, pass a property list with the names and values for the private properties to validate. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list, use the property list utility functions.

Note There are currently no private properties defined for groups.


Control Codes for Nodes

All of the control codes relating to nodes are included in the following list. In the list are external control codes, or control codes that applications can pass to the control functions of the Cluster API to initiate operations. The operations include retrieving properties and other data, updating properties and other data, and data enumeration and validation. There are no internal control codes for node operations.

CLUSCTL_NODE_ENUM_COMMON_PROPERTIES

CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES

CLUSCTL_NODE_GET_CHARACTERISTICS

CLUSCTL_NODE_GET_COMMON_PROPERTIES

CLUSCTL_NODE_GET_FLAGS

CLUSCTL_NODE_GET_PRIVATE_PROPERTIES

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 is used to retrieve a list of the common node properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_COMMON_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve values for the read/write properties, call ClusterNodeControl with the CLUSCTL_NODE_GET_COMMON_PROPERTIES control code. To update them, use the CLUSCTL_NODE_SET_COMMON_PROPERTIES control code. To validate them, use CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES.

The CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code enables you to retrieve values for the read-only properties.


CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES

The CLUSCTL_NODE_ENUM_PRIVATE_PROPERTIES control code is used to retrieve a list of the private node properties.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Array of null-terminated Unicode strings with an additional null terminator appended to the last string.
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_ENUM_PRIVATE_PROPERTIES

Notes to Callers

The properties that are returned in the contents of the lpOutBuffer parameter are of two types: read/write and read-only.

To retrieve values for the read/write properties, call ClusterNodeControl with the CLUSCTL_NODE_GET_PRIVATE_PROPERTIES control code. To update them, use the CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code. To validate them, use CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES.

The CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES control code enables you to retrieve values for the read-only properties.


CLUSCTL_NODE_GET_CHARACTERISTICS

The CLUSCTL_NODE_GET_CHARACTERISTICS control code is a request for a mask that describes the intrinsic characteristics of a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_CHARACTERISTICS

Notes to Callers

The lpOutBuffer parameter of ClusterNodeControl points to a bitmask that describes the node's characteristics. The bits can be set to the following value:

CHARACTERISTICS value | Description
CLUS_CHAR_UNKNOWN | Node has no known characteristics.


CLUSCTL_NODE_GET_COMMON_PROPERTIES

The CLUSCTL_NODE_GET_COMMON_PROPERTIES control code is a request for the read/write common properties of a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_GET_COMMON_PROPERTIES control code, it returns a property list with the names and values of properties that apply to all nodes and can be modified using the CLUSCTL_NODE_SET_COMMON_PROPERTIES control code.

The Description property is the only read/write common property for nodes.

For an overall description of the common node properties, see Common Node Properties.

To parse a property list, use the property list utility functions.


CLUSCTL_NODE_GET_FLAGS

The CLUSCTL_NODE_GET_FLAGS control code is used to request a mask that describes the flags that are currently set for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | DWORD bitmask
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_FLAGS

Notes to Callers

ClusterNodeControl returns a bitmask that describes the extrinsic attributes of the node. There are currently no flags defined for nodes.


CLUSCTL_NODE_GET_NAME

The CLUSCTL_NODE_GET_NAME control code is used to request the name of a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Null-terminated Unicode string
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_NAME

Notes to Callers

The name of a node is stored in the node's NodeName property. To retrieve the NodeName property along with the other common read-only node properties, call ClusterNodeControl with the CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code.


CLUSCTL_NODE_GET_PRIVATE_PROPERTIES

The CLUSCTL_NODE_GET_PRIVATE_PROPERTIES control code is used to request the read/write private properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_GET_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of all of the properties that apply only to the specific node and can be modified using the CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To parse the property list returned by ClusterNodeControl, use the property list utility functions.

Note There are currently no private properties defined for nodes.


CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES

The CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code is used to request the read-only common properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code, it returns a property list with the names and values of the properties that apply to all groups and cannot be modified using the CLUSCTL_NODE_SET_COMMON_PROPERTIES control code.

The NodeName property is the only read-only common property for nodes.

To parse the property list returned by ClusterNodeControl, use the property list utility functions.


CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES

The CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES control code is used to request the read-only private properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | Property list
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_GET_RO_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list with the names and values of the properties that apply only to the specific node and cannot be modified using the CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To parse the property list returned by ClusterNodeControl, use the property list utility functions.

Note There are currently no private properties defined for nodes.


CLUSCTL_NODE_SET_COMMON_PROPERTIES

The CLUSCTL_NODE_SET_COMMON_PROPERTIES control code is used to update the common properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_SET_COMMON_PROPERTIES control code, pass a property list with the names and new values for the properties to update. Included in the property list can be any read/write properties that apply to all nodes, such as the Description property.

To retrieve the current value of the common node property, use the CLUSCTL_NODE_GET_COMMON_PROPERTIES control code.

For an overall description of the common node properties, see Common Node Properties.

To construct a property list, use the property list utility functions.


CLUSCTL_NODE_SET_PRIVATE_PROPERTIES

The CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code is used to update the private properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_WRITE
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_MODIFY
Code: | CLCTL_SET_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_SET_PRIVATE_PROPERTIES control code, pass a property list with the names and new values for the properties to update. This control code updates only those properties that are read/write and apply to a specific node. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list, use the property list utility functions.

Note There are currently no private properties defined for nodes.


CLUSCTL_NODE_UNKNOWN

The CLUSCTL_NODE_UNKNOWN control code indicates a request for an unknown operation. ClusterNodeControl always returns ERROR_SUCCESS when the dwControlCode parameter is set to this code.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | None
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Control Code: | CLCTL_UNKNOWN


CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES

The CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES control code is used to check whether or not specific properties are valid common properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_COMMON_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES control code, pass a property list with the names and values of all of the common read/write properties that you want to validate. A common property is a property that applies to all nodes.

For an overall description of the common node properties, see Common Node Properties.

To build a property list, use the property list utility functions.


CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES

The CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES control code is used to check whether or not specific properties are valid private properties for a node.

Quick Info

Type: | External
Access: | CLUS_ACCESS_READ
Input: | Property list
Output: | None
Global: | CLUS_NOT_GLOBAL
Modify: | CLUS_NO_MODIFY
Code: | CLCTL_VALIDATE_PRIVATE_PROPERTIES

Notes to Callers

When you call ClusterNodeControl with the CLUSCTL_NODE_VALIDATE_PRIVATE_PROPERTIES control code, pass a property list with the names and values for the private read/write properties to validate. Private properties can include:

  • Dynamic values generated as needed.
  • Static values stored in the cluster database.

To build a property list, use the property list utility functions.

Note There are currently no private properties defined for nodes.


Cluster Structures

Cluster structures are used to describe data relating to an object in a cluster. The most common use of the majority of cluster structures is in a value list. A value list is returned by ClusterResourceControl and ClusterResourceTypeControl and is included in the property value of a property list.

Microsoft® Cluster Server defines a special structure, CLUSPROP_VALUE, that is used as a generic header in many cluster structures. CLUSPROP_VALUE has two members: a CLUSPROP_SYNTAX structure that describes a data value's format and type and a numeric value that describes a data value's length.

Most of the other cluster structures describe data of a particular type that is used in a value list. All of these structures include as their first member a CLUSPROP_VALUE structure. The following table lists the structures that are available for describing data values:

Cluster structure | Purpose
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_MULTI_SZ | Describes multiple strings.
CLUSPROP_PARTITION_INFO | Describes information relevant to storage class resources.
CLUSPROP_PROPERTY_NAME | Describes the name of a property.
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_SZ | Describes a null-terminated Unicode string.
CLUSPROP_ULARGE_INTEGER | Describes an unsigned large integer.

The data portion of these structures can be a single value or can itself be a structure. For example, the CLUSPROP_DISK_NUMBER structure includes a single DWORD to hold the data for the disk number. The CLUSPROP_VALUE portion of this structure is set as follows:

CLUSPROP_VALUE Value;
Value.Syntax = CLUSPROP_SYNTAX_DISK_NUMBER;
Value.cbLength = cbDiskNum;

Because the data for a SCSI device address requires more than a single value, the CLUSPROP_SCSI_ADDRESS structure uses a CLUS_SCSI_ADDRESS structure to hold it. The CLUSPROP_VALUE member of a CLUSPROP_SCSI_ADDRESS structure is set as follows:

CLUSPROP_VALUE Value;
Value.Syntax = CLUSPROP_SYNTAX_SCSI_ADDRESS;
Value.cbLength = cbSCSIAddress;

The CLUS_SCSI_ADDRESS structure is a union comprised of four unsigned characters or a single DWORD.

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. On the left is the header structure, CLUSPROP_VALUE. The structures shown in the middle column are the data value structures. Structures that have data of the same type are grouped together in the diagram. On the right are the data structures.

One CLUSPROP structure, CLUSPROP_REQUIRED_DEPENDENCY, is missing from the diagram because it has a slightly different format. CLUSPROP_REQUIRED_DEPENDENCY is a union with three members: a CLUSPROP_VALUE structure, a CLUSPROP_RESOURCE_CLASS structure, and a CLUSPROP_SZ structure.

In addition to the structures dedicated to describing data values, there are the following structures:

Cluster structure | Purpose
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.
RESUTIL_PROPERTY_ITEM | Contains information about a property and an offset to the property's data.

Note To improve clarity, some of the definitions of the data value structures are not documented exactly as they appear in the CLUSAPI.H header file. Specifically, the documentation eliminates the extra level of indirection for structures that include another structure as a member.

For example, in the CLUSAPI.H header file, the CLUSPROP_PARTITION_INFO structure includes as a member a CLUS_PARTITION_INFO structure. The documentation, however, eliminates this extra level of indirection by listing all of the members of the CLUS_PARTITION_INFO as if they were members of the CLUSPROP_PARTITION_INFO structure directly.


CLUS_PARTITION_INFO

The CLUS_PARTITION_INFO structure contains data describing a disk volume and file system. The CLUS_PARTITION_INFO structure is defined in CLUSAPI.H.

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 disk. One of the following flags is valid:
Partition flag value | Description
CLUSPROP_PIFLAG_STICKY | The drive letter is sticky.
CLUSPROP_PIFLAG_REMOVABLE | The disk is removable.
CLUSPROP_PIFLAG_USABLE | The disk is formatted with a file system that is usable by the Cluster Service.
szDeviceName
Device name for the disk, such as C:. No backslash is included.
szVolumeLabel
Volume label for the disk.
dwSerialNumber
Serial number of the disk 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 disk.
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 disk.
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 by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS.

The CLUS_PARTITION_INFO structure is one of the members of the CLUSPROP_PARTITION_INFO structure. The CLUS_PARTITION_INFO structure provides the data portion for CLUSPROP_PARTITION_INFO.

Because the CLUS_PARTITION_INFO structure describes data, it does not include a value header.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUS_RESOURCE_CLASS_INFO

The CLUS_RESOURCE_CLASS_INFO structure contains resource class data. The CLUS_RESOURCE_CLASS_INFO structure is defined in CLUSAPI.H.

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
Resource class described as numeric 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
Value that is specific to the class of resource and 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 mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

A CLUS_RESOURCE_CLASS_INFO structure is the data member of a CLUSPROP_RESOURCE_CLASS_INFO structure.

A CLUS_RESOURCE_CLASS_INFO structure can be returned by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_GET_CLASS_INFO and by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_GET_CLASS_INFO.

Because the CLUS_RESOURCE_CLASS_INFO structure describes data rather than a value, it does not include a value header.


CLUS_SCSI_ADDRESS

The CLUS_SCSI_ADDRESS structure contains address data. The CLUS_SCSI_ADDRESS structure is defined in CLUSAPI.H.

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 describing the SCSI address.

Remarks

A CLUS_SCSI_ADDRESS structure is the data member of a CLUSPROP_SCSI_ADDRESS structure.

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 by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS.

Because the CLUS_SCSI_ADDRESS structure describes data rather than a value, it does not include a value header.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUS_WORKER

The CLUS_WORKER structure contains information about a worker thread. The CLUS_WORKER structure is defined in RESAPI.H.

typedef struct _CLUS_WORKER {
    HANDLE hThread;
    BOOL Terminate;
} CLUS_WORKER, *PCLUS_WORKER;

Members

hThread
Handle to the worker thread.
Terminate
Flag that indicates whether or not 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.

Applications and resource DLLs work with the CLUS_WORKER structure through the following utility functions:

  • ClusWorkerCreate
  • ClusWorkerCheckTerminate
  • ClusWorkerTerminate

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 if it were 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 will set Terminate to TRUE. The second call will return immediately after checking the value of Terminate without waiting for the thread to exit.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_BINARY

The CLUSPROP_BINARY structure describes a binary data value used in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A byte array.

The CLUSPROP_BINARY structure is defined in CLUSAPI.H

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 structure.
rgb
Array of bytes containing the data.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_BUFFER_HELPER

The CLUSPROP_BUFFER_HELPER union is used to build or parse a property list or a value list. The CLUSPROP_BUFFER_HELPER structure is defined in CLUSAPI.H

typedef union _CLUSPROP_BUFFER_HELPER {
    BYTE *                          pb;
    WORD *                          pw;
    DWORD *                         pdw;
    LPWSTR                          psz;
    PCLUSPROP_LIST                  pList;
    PCLUSPROP_SYNTAX                pSyntax;
    PCLUSPROP_PROPERTY_NAME         pName;
    PCLUSPROP_VALUE                 pValue;
    PCLUSPROP_BINARY                pBinaryValue;
    PCLUSPROP_DWORD                 pDwordValue;
    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.
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.
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 a 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.

Remarks

The CLUSPROP_BUFFER_HELPER structure is useful in working with property and value lists because it eliminates the need to cast to the appropriate data type.

An alternate structure, RESUTIL_PROPERTY_ITEM, can also be used to work with multiple properties.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_DISK_NUMBER

The CLUSPROP_DISK_NUMBER structure describes the number of a disk used in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A DWORD value.

The CLUSPROP_DISK_NUMBER structure is defined in CLUSAPI.H.

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 structure.
dw
Numeric value identifying the physical drive of the disk. Valid values begin at zero.

Remarks

A CLUSPROP_DISK_NUMBER structure can be returned by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO, and by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS.


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 is used in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A DWORD value.

The CLUSPROP_DISK_SIGNATURE structure is defined in CLUSAPI.H.

typedef struct _CLUSPROP_DISK_SIGNATURE {
    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 structure.
dw
Numeric value that describes the disk signature.

Remarks

The CLUSPROP_DISK_SIGNATURE structure is defined as a CLUSPROP_DWORD structure, which combines numeric data with the standard value header containing format, type, and length information.

A CLUSPROP_DISK_SIGNATURE structure can be returned by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO, and by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_DWORD

The CLUSPROP_DWORD structure describes numeric data used in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the numeric data.
  • A DWORD value.

The CLUSPROP_DWORD structure is defined in CLUSAPI.H.

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 structure.
dw
Numeric value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_LIST

The CLUSPROP_LIST structure is used to access the beginning of a property list. The CLUSPROP_LIST structure is defined in CLUSAPI.H.

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 About Property Lists.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_MULTI_SZ

The CLUSPROP_MULTI_SZ structure describes multiple null-terminated Unicode strings used in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the partition information.
  • A string array.

The CLUSPROP_MULTI_SZ structure is defined in CLUSAPI.H.

typedef struct _CLUSPROP_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 terminating NULL character.

Remarks

The CLUSPROP_MULTI_SZ structure is defined as a CLUSPROP_SZ structure.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_PARTITION_INFO

The CLUSPROP_PARTITION_INFO structure contains information relevant to storage class resources that is used 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. To promote clarity, the individual members of these two structures are included in the CLUSPROP_PARTITION_INFO definition.

The CLUSPROP_PARTITION_INFO structure is defined in CLUSAPI.H.

typedef struct _CLUSPROP_PARTITION_INFO {
    CLUSPROP_SYNTAX           Syntax;
    DWORD                     cbLength;
    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

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 partition information data. The count does not include the data in the Syntax or cbLength members.
dwFlags
Member of the CLUS_PARTITION_INFO structure that describes the disk. One of the following flags is valid:
Partition flag value | Description
CLUSPROP_PIFLAG_STICKY | The drive letter is sticky.
CLUSPROP_PIFLAG_REMOVABLE | The disk is removable.
CLUSPROP_PIFLAG_USABLE | The disk 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 disk, such as C:. No backslashes are included.
szVolumeLabel
Member of the CLUS_PARTITION_INFO structure that describes the volume label for the disk.
dwSerialNumber
Member of the CLUS_PARTITION_INFO structure that describes the serial number of the disk 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 disk.
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 disk.
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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_PROPERTY_NAME

The CLUSPROP_PROPERTY_NAME structure describes the name of a property used in a value list and consists of:

  • A CLUSPROP_VALUE structure describing the format, type, and length of the property name.
  • A null-terminated character string.

The CLUSPROP_PROPERTY_NAME structure is defined in CLUSAPI.H.

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

The CLUSPROP_PROPERTY_NAME structure is defined as a CLUSPROP_SZ structure, which combines string data with the standard value header containing format, type, and length information.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_REQUIRED_DEPENDENCY

The CLUSPROP_REQUIRED_DEPENDENCY union describes a resource upon which another resource is required to have a dependency. 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.

The CLUSPROP_REQUIRED_DEPENDENCY structure is defined in CLUSAPI.H.

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.
ResClass
Resource class upon which a resource must depend. A resource class is a numeric value used to identify resources of similar capability. 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

A CLUSPROP_REQUIRED_DEPENDENCY structure is returned in the value list by ClusterResourceControl when the dwControlCode parameter is set to CLUSCTL_RESOURCE_GET_REQUIRED_DEPENDENCIES, and by ClusterResourceTypeControl when dwControlCode is set to CLUSCTL_RESOURCE_TYPE_GET_REQUIRED_DEPENDENCIES.

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, 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.'

The Value member is used to determine if the dependency is described with resource class or resource type information.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_RESOURCE_CLASS

The CLUSPROP_RESOURCE_CLASS structure describes a resource class value used in a value list. The CLUSPROP_RESOURCE_CLASS structure is defined in CLUSAPI.H.

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 resource class.
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.
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 mail to resclass@microsoft.com with the following information:

  • Company name
  • Contact name
  • Contact phone number
  • Contact e-mail

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_RESOURCE_CLASS_INFO

The CLUSPROP_RESOURCE_CLASS_INFO structure describes a resource class information value used 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.

To promote clarity, the individual members of these two structures are shown in the CLUSPROP_RESOURCE_CLASS_INFO definition.

The CLUSPROP_RESOURCE_CLASS_INFO structure is defined in CLUSAPI.H.

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

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_SCSI_ADDRESS

The CLUSPROP_SCSI_ADDRESS structure describes an address value for a SCSI device used 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.

To promote clarity, the individual members of these two structures are shown in the CLUSPROP_SCSI_ADDRESS definition.

The CLUSPROP_SCSI_ADDRESS structure is defined in CLUSAPI.H.

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_SYNTAX

The CLUSPROP_SYNTAX union describes the format and type of a data value. The CLUSPROP_SYNTAX structure is defined in CLUSAPI.H.

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. The following values are valid:
CLUSPROP_SYNTAX_LIST_VALUE_BINARY
Describes a binary value to be included in a property list.
CLUSPROP_SYNTAX_LIST_VALUE_DWORD
Describes a DWORD value to be included in a property list.
CLUSPROP_SYNTAX_LIST_VALUE_EXPAND_SZ
Describes a string value with unexpanded references to environment variables to be included in a property list.
CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ
Describes an array of string values to be included in a property list.
CLUSPROP_SYNTAX_LIST_VALUE_SZ
Describes a string value to be included in a property list.
CLUSPROP_SYNTAX_DISK_NUMBER
Describes the number value of a Physical Disk resource. This value is represented by a CLUSPROP_DISK_NUMBER structure.
CLUSPROP_SYNTAX_DISK_SIGNATURE
Describes a Signature property value for a Physical Disk resource. A signature value is represented by a CLUSPROP_DISK_SIGNATURE structure.
CLUSPROP_SYNTAX_ENDMARK
Designates the data value as the last entry in a property or value list.
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. The following values are valid:
Format value | Description
CLUSPROP_FORMAT_UNKNOWN | Data is in an unknown format.
CLUSPROP_FORMAT_BINARY | Data is a binary value.
CLUSPROP_FORMAT_DWORD | Data is a DWORD value.
CLUSPROP_FORMAT_EXPAND_SZ | Data is a character string with unexpanded references to environment variables.
CLUSPROP_FORMAT_MULTI_SZ | Data is an array of character strings.
CLUSPROP_FORMAT_SZ | Data is a character string.
CLUSPROP_FORMAT_ULARGE_
INTEGER 		Data is an unsigned large integer.
CLUSPROP_FORMAT_USER | Data is in a user-defined format.
wType
Numeric value that describes only the type of the data value. The following types are valid:
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_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

The wType member of the CLUSPROP_SYNTAX structure is set to one of the following values when ClusterResourceControl is handling the CLUSCTL_RESOURCE_STORAGE_GET_DISK_INFO control code and when ClusterResourceTypeControl is handling the CLUSCTL_RESOURCE_TYPE_STORAGE_GET_AVAILABLE_DISKS control code:

  • CLUSPROP_TYPE_DISK_NUMBER
  • CLUSPROP_TYPE_PARTITION_INFO
  • CLUSPROP_TYPE_SCSI_ADDRESS
  • CLUSPROP_TYPE_SIGNATURE

To parse data that is returned from a control code function such as ClusterResourceControl, use the wFormat member of this structure if the wType member defines a type that the application cannot understand.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_SZ

The CLUSPROP_SZ structure describes a null-terminated Unicode string value used in a value list and consists of:

  • A CLUSPROP_VALUE structure indicating the format and type of string.
  • A null-terminated Unicode string.

The CLUSPROP_SZ structure is defined in CLUSAPI.H.

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSPROP_ULARGE_INTEGER

The CLUSPROP_ULARGE_INTEGER structure describes an unsigned large integer value used 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.

The CLUSPROP_ULARGE_INTEGER structure is defined in CLUSAPI.H.

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


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. The CLUSPROP_VALUE structure is defined in CLUSAPI.H.

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. The count does not include the value header. It is an actual byte count, meaning that if there is padding to fulfill the DWORD boundary requirement, the padding characters are not included in cbLength. To move past the data in a single entry in the property list, use the ALIGN_CLUSPROP macro. ALIGN_CLUSPROP rounds up to the next DWORD value in the list.

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

To ensure that entries in a property list are properly aligned, do not use the malloc function to allocate the memory for these entries. Instead, use the Win32® function LocalAlloc.

The following code sample illustrates how to access an entry in a property list:

CLUSPROP_BUFFER_HELPER buf;
buf.pb += sizeof(*(buf.pValue)) + ALIGN_CLUSPROP
(buf.pValue->cbLength);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CLUSTERVERSIONINFO

The CLUSTERVERSIONINFO structure describes information about the version of the Cluster Service. The CLUSTERVERSIONINFO structure is defined in CLUSAPI.H.

typedef struct _CLUSTERVERSIONINFO{
    DWORD dwVersionInfoSize;
    WORD  MajorVersion;
    WORD  MinorVersion;
    WORD  BuildNumber;
    WCHAR szVendorId[ 64 ];
    WCHAR szCSDVersion[ 64 ];
} CLUSTERVERSIONINFO, *LPCLUSTERVERSIONINFO;

Members

dwVersionInfoSize

Size, in bytes, of the data structure.

MajorVersion
Identifies the major version number of the Cluster Service. For example, for version 1.0, the major version number is 1.
MinorVersion
Identifies the minor version number of the Cluster Service. For example, for version 1.0, the minor version number is 0.
BuildNumber
Identifies the build number of the Cluster Service, such as 1.20.
szVendorID
Contains the vendor identifier information for the Cluster Service.
szCSDVersion
Contains the latest Microsoft® Windows NT® Service Pack installed on the node. If a Service Pack has not been installed, the szCSDVersion member is empty.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


RESUTIL_PROPERTY_ITEM

The RESUTIL_PROPERTY_ITEM structure contains information about a property. The RESUTIL_PROPERTY_ITEM structure is defined in RESAPI.H.

typedef struct _RESUTIL_PROPERTY_ITEM {
    LPWSTR  Name;
    LPWSTR  KeyName;
    DWORD   Format;
    DWORD   Default;
    DWORD   Minimum;
    DWORD   Maximum;
    DWORD   Flags;
    DWORD   Offset;
} RESUTIL_PROPERTY_ITEM, *PRESUTIL_PROPERTY_ITEM;

Members

Name
Name of the property described in the structure.
KeyName
Name of the cluster database subkey for the property.
Format
Format of the property such as CLUSPROP_FORMAT_BINARY or CLUSPROP_FORMAT_DWORD. See CLUSPROP_SYNTAX for a list of valid format values.
Default
Default data value for the property. The value of the Default member depends on the data value of the Format member. For example, if the Format member is set to CLUSPROP_FORMAT_DWORD, the Default member contains a DWORD value.
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 size in bytes of the default data value specified by Default.
Maximum
Maximum data value for the property.
Flags
Bitmask that describes the property. Valid values are:

RESUTIL_PROPITEM_READ_ONLY

RESUTIL_PROPITEM_REQUIRED

Offset
Byte offset to the property's data in a buffer known as a parameter block. The type of data in the parameter block differs depending on its format, as indicated by the Format member. For example, if the Format member is set to CLUSPROP_FORMAT_DWORD, the data in the parameter block referenced by Offset is a DWORD value.

Remarks

The RESUTIL_PROPERTY_ITEM structure can be used to build or parse a property list, to read or update properties, and as an entry in a property table. A property table is defined as an array of RESUTIL_PROPERTY_ITEM structures. Many of the Cluster Resource Utility Functions use property tables as input or output parameters.

For more information about property tables and their relationship to parameter blocks, see About Property Tables.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Cluster Properties

Cluster properties are attributes that describe a cluster object such as a resource, resource type, group, or node. Most cluster properties are stored in the cluster database to provide easy access.

There are two types of properties: common and private. When a property is common, it exists for every instance of the type of cluster object for which it is defined. A common resource property exists for every resource, a common resource type property exists for every resource type, a common group property exists for every group, and a common node property exists for every node. For example, the RestartAction property is a common resource property because it applies to all resources regardless of their type. The FailoverThreshold property is a common group property because it is used to describe all groups.

Private properties are attributes that are narrower in scope than common properties. When a property is private, it exists only for particular instances of the type of object for which it is defined. Private properties are most prevalent for resources. There are many kinds of resources and each kind can have its own set of private properties. For example, the set of private properties for Physical Disk resources includes the Signature property and the set of private properties for File Share resources includes the ShareName property. Like common properties, private properties can be stored in the cluster database. Unlike common properties, they can also be dynamic or computed values, generated on demand.

Resources belonging to most of the resource types defined by Cluster Server have at least one private property. The sole exception is the Time Service resource; it has zero private properties. As a developer of a new resource type, you can choose whether or not to associate private properties with your type. If you use the Resource Type AppWizard to begin development, you can define private properties in the Parameters screen.

For more information about specifying private property information in the AppWizard, see Using the Resource Type AppWizard.

For more information about the private properties defined for the Cluster Server resource types, see Private Resource Properties.

Cluster Server defines a few Cluster API functions for working with specific common properties. To work either with multiple properties simultaneously or with properties that lack a corresponding Cluster API function, Cluster Server provides the control code functions. The control code functions are also part of the Cluster API; they are general functions that perform a variety of operations on an object. The property-related operations include:

  • Getting all of the read/write properties
  • Getting all of the read-only properties
  • Setting read/write properties
  • Enumerating properties
  • Validating properties

A control code is passed to each of the control code functions to identify the operation to perform. Control codes are constants that begin with the CLUSCTL prefix and end with a description of the operation. Between the prefix and description is the type of object. For example, the CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES control code sets the private properties of a resource and the CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code gets the common read-only properties for a group.

There is a different control code function for each type of cluster object. The following table briefly describes each of the control code functions:

Control code function | Description
ClusterGroupControl | Performs property and other operations on a group.
ClusterNetworkControl | Performs property and other operations on a network.
ClusterNetInterfaceControl | Performs property and other operations on a network interface.
ClusterNodeControl | Performs property and other operations on a node.
ClusterResourceControl | Performs property and other operations on a resource.
ClusterResourceTypeControl | Performs property and other operations on a resource type.

For more information about control codes and control code operations, see the following topics:

Cluster Control Codes for a general overview.

Using the Control Code Functions for a description of how the Cluster API control code functions operate.


Common Network Properties

Common network properties are data values that describe all networks and are values stored in the cluster database. Common properties can be read-only or read/write. To access common network properties, applications call ClusterNetworkControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_NETWORK_ENUM_COMMON_PROPERTIES to retrieve the names of the common network properties.
  • CLUSCTL_NETWORK_GET_COMMON_PROPERTIES to retrieve the names and values of common network properties that can be modified.
  • CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES to retrieve the names and values of common network properties that cannot be modified.
  • CLUSCTL_NETWORK_SET_COMMON_PROPERTIES to update the values of common network properties.
  • CLUSCTL_NETWORK_VALIDATE_COMMON_PROPERTIES to validate common network properties.

For the get, set, and validate operations, ClusterNetworkControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterNetworkControl.
  • Structures that are used as input to or output from a property operation.
  • Control codes that can be passed to ClusterNetworkControl to retrieve the property.


Name Property for Networks

The Name property provides the name of the network.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetworkControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Name property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NameValue;
LPCWSTR NameData = L "NetworkName";
NameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof(NameData);
lstrcpyW(NameValue.sz, NameData);

Applications can change a network's name only by calling SetClusterNetworkName. Because the Name property is read-only, it cannot be changed using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Address Property for Networks

The Address property provides the address for the network or subnet as a whole.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetworkControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES

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.

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Address property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ AddressValue;
LPCWSTR AddressData = L "10.1.0.0";
AddressValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AddressValue.cbLength = sizeof(AddressData);
lstrcpyW(AddressValue.sz, AddressData);

Because the Address property is read-only, it cannot be changed using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


AddressMask Property for Networks

The AddressMask property provides the mask which distinguishes the network and host portions of an address.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetworkControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES

Remarks

The data in the AddressMask property is formatted as xxx.xxx.xxx.xxx where xxx represents a decimal number between 0 and 255.

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the AddressMask property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ AddressMaskValue;
LPCWSTR AddressMaskData = L "255.255.0.0";
AddressMaskValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AddressMaskValue.cbLength = sizeof(AddressMaskData);
lstrcpyW(AddressMaskValue.sz, AddressMaskData);

Because the AddressMask property is read-only, it cannot be changed using the CLUSCTL_NETWORK_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Description Property for Networks

The Description property provides remarks or comments about the network.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterNetworkControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Description property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DescriptionValue;
LPCWSTR DescriptionData = L "External network";
DescriptionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof(DescriptionData);
lstrcpyW(DescriptionValue.sz, DescriptionData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Role Property for Networks

The Role property provides the role of the network in the cluster.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterNetworkControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_NETWORK_GET_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Role property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD RoleData = ClusterNetworkRoleClientAccess;
CLUSPROP_DWORD RoleValue;
RoleValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RoleValue.cbLength = sizeof(DWORD);
RoleValue.dw = RoleData;

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 that is used for internal cluster communication, the Role property may not be changed to ClusterNetworkRoleNone or ClusterNetworkRoleClientAccess.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Common Network Interface Properties

Common network interface properties are data values that describe all network interfaces regardless of their type and are static values stored in the cluster database. Common properties can be read-only or read/write. To access common resource properties, applications typically call ClusterNetInterfaceControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_NETINTERFACE_ENUM_COMMON_PROPERTIES to retrieve the names of the common network interface properties.
  • CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES to retrieve the names and values of common network interface properties that can be modified.
  • CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES to retrieve the names and values of common network interface properties that cannot be modified.
  • CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES to update the values of common network interface properties.
  • CLUSCTL_NETINTERFACE_VALIDATE_COMMON_PROPERTIES to validate common network interface properties.

For the get, set, and validate operations, ClusterNetInterfaceControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterNetInterfaceControl.
  • Structures that are used as input to or output from a property operation.
  • Control codes that can be passed to ClusterNetInterfaceControl to retrieve the property.


Adapter Property for Network Interfaces

The Adapter property provides the name that is used to uniquely identify the network interface in the system.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetInterfaceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Adapter property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ AdapterValue;
LPCWSTR AdapterData = L "E100B1";
AdapterValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AdapterValue.cbLength = sizeof(AdapterData);
lstrcpyW(AdapterValue.sz, AdapterData);

The Adapter property is stored in the system registry.

Because the Adapter property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Address Property for Network Interfaces

The Address property provides the primary network address that the node uses for the network interface.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetInterfaceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

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.

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Address property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ AddressValue;
LPCWSTR AddressData = L "10.1.0.2";
AddressValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AddressValue.cbLength = sizeof(AddressData);
lstrcpyW(AddressValue.sz, AddressData);

Because the Address property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Description Property for Network Interfaces

The Description property provides remarks or comments about the network interface.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterNetInterfaceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETINTERFACE_GET_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Description property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DescriptionValue;
LPCWSTR DescriptionData = L "Network Interface Description";
DescriptionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof(DescriptionData);
lstrcpyW(DescriptionValue.sz, DescriptionData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Name Property for Network Interfaces

The Name property provides the generated name for the network interface. This name only appears on the General page of the property sheet for the network interface and is the name that is passed to the OpenClusterNetInterface function.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetInterfaceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Name property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NameValue;
LPCWSTR NameData = L "E100B1 - NODE1";
NameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof(NameData);
lstrcpyW(NameValue.sz, NameData);

Because the Name property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Network Property for Network Interfaces

The Network property provides the name of the network to which the network interface is connected.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetInterfaceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Network property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NetworkValue;
LPCWSTR NetworkData = L "External Network";
NetworkValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NetworkValue.cbLength = sizeof(NetworkData);
lstrcpyW(NetworkValue.sz, NetworkData);

Because the Network property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Node Property for Network Interfaces

The Node property provides the name of the node in which the network interface is installed.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNetInterfaceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NETINTERFACE_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNetworkControl processes the CLUSCTL_NETWORK_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Node property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NodeValue;
LPCWSTR NodeData = L "NODE1";
NodeValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NodeValue.cbLength = sizeof(NodeData);
lstrcpyW(NodeValue.sz, NodeData);

Because the Node property is read-only, it cannot be changed using the CLUSCTL_NETINTERFACE_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Common Resource Properties

Common resource properties are data values that describe all resources regardless of their type and are static values stored in the cluster database. Common properties can be read-only or read/write. To access common resource properties, applications typically call ClusterResourceControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_RESOURCE_ENUM_COMMON_PROPERTIES to retrieve the names of the common resource properties.
  • CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES to retrieve the names and values of common resource properties that can be modified.
  • CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES to retrieve the names and values of common resource properties that cannot be modified.
  • CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES to update the values of common resource properties.
  • CLUSCTL_RESOURCE_VALIDATE_COMMON_PROPERTIES to validate common resource properties.

For the get, set, and validate operations, ClusterResourceControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterResourceControl.
  • Structures that are used as input to or output from a property operation.
  • Control codes that can be passed to ClusterResourceControl to retrieve the property.


DebugPrefix Property for Resources

The DebugPrefix property provides the path to the debugger to be attached to the Resource Monitor for the resource.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the DebugPrefix property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DebugPrefixValue;
LPCWSTR DebugPrefixData = L "C:\bin\debug.exe";
DebugPrefixValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DebugPrefixValue.cbLength = sizeof(DebugPrefixData);
lstrcpyW(DebugPrefixValue.sz, DebugPrefixData);

A debugger can be used only if the resource is running with a separate 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 Resource Monitors, see Resource Monitor.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Description Property for Resources

The Description property provides remarks or comments about the resource.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Description property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DescriptionValue;
LPCWSTR DescriptionData = L "Word processing resource";
DescriptionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof(DescriptionData);
lstrcpyW(DescriptionValue.sz, DescriptionData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


IsAlivePollInterval Property for Resources

The IsAlivePollInterval property provides the recommended interval in milliseconds that 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.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the IsAlivePollInterval property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD IsAlivePollIntervalData = 300;
CLUSPROP_DWORD IsAlivePollIntervalValue;
IsAlivePollIntervalValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
IsAlivePollIntervalValue.cbLength = sizeof(DWORD);
IsAlivePollIntervalValue.dw = IsAlivePollIntervalData;

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


LooksAlivePollInterval Property for Resources

The LooksAlivePollInterval property provides the recommended interval in milliseconds that 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.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the LooksAlivePollInterval property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD LooksAlivePollIntervalData = 300;
CLUSPROP_DWORD LooksAlivePollIntervalValue;
LooksAlivePollIntervalValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
LooksAlivePollIntervalValue.cbLength = sizeof(DWORD);
LooksAlivePollIntervalValue.dw = LooksAlivePollIntervalData;

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Name Property for Resources

The Name property provides the name of the resource.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Functions: | ClusterResourceControl SetClusterResourceName
Structure: | CLUSPROP_SZ
Control Codes: | CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES CLUSCTL_RESOURCE_GET_NAME

Remarks

An application can retrieve the Name property of a resource by calling ClusterResourceControl with one of the following control codes:

  • CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES
  • CLUSCTL_RESOURCE_GET_NAME

With CLUSCTL_RESOURCE_GET_RO_COMMON_PROPERTIES, the Name property is an entry in a property list containing all of the read-only common resource properties. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NameValue;
LPCWSTR NameData = L "My Application";
NameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof(NameData);
lstrcpyW(NameValue.sz, NameData);

With CLUSCTL_RESOURCE_GET_NAME, the output is a single null-terminated string. Using this control code eliminates the need to parse through a property list to locate the name. Applications that need only the Name property should use the CLUSCTL_RESOURCE_GET_NAME control code to retrieve it.

Applications can change a resource's name only by calling SetClusterResourceName. Because the Name property is read-only, it cannot be changed using the CLUSCTL_RESOURCE_SET_COMMON_PROPERTIES control code.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


PendingTimeout Property for Resources

The PendingTimeout property provides the number of milliseconds that the Resource Monitor waits after the resource returns a status of ERROR_IO_PENDING from its Online or Offline entry point functions.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the PendingTimeout property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD PendingTimeoutData = 4;
CLUSPROP_DWORD PendingTimeoutValue;
PendingTimeoutValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PendingTimeoutValue.cbLength = sizeof(DWORD);
PendingTimeoutValue.dw = PendingTimeoutData;

When the amount of time specified by the PendingTimeout property has passed, and the resource has not transitioned to the ClusterResourceOnline or ClusterResourceOffline state, the Resource Monitor terminates the resource by calling its Terminate entry point function.

If the PendingTimeout property is not specified, the Resource Monitor uses a default value of 3 minutes.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


PersistentState Property for Resources

The PersistentState property describes the last known persistent state of the resource.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the PersistentState property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD PersistentStateData = FALSE;
CLUSPROP_DWORD PersistentStateValue;
PersistentStateValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PersistentStateValue.cbLength = sizeof(DWORD);
PersistentStateValue.dw = PersistentStateData;

The data value for the PersistentState property describes what should happen to the resource the next time the Cluster Service is started. Valid values are TRUE and FALSE. When PersistentState is set to TRUE, the resource should be brought online. When set to FALSE, it should be left offline. Typically, resources inherit their state from the state of the group to which they belong. When that state differs, as can happen when the group is online and the resource is offline, the PersistentState property of the resource is saved as FALSE.

A resource remains offline until the network administrator manually brings it back online. When it is brought online, the resource's PersistentState property is deleted from the cluster database. Because a resource cannot be online if its group is offline, it makes no sense to save the resource's PersistentState property unless the resource is offline.

To retrieve the current state of a resource, call the GetClusterResourceState function.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


RestartAction Property for Resources

The RestartAction property describes the action to perform if the resource fails.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

The RestartAction property allows a network administrator to control how resource failures affect other resources in the group. If not specified, the default behavior is to have failures to resources affect the group to which they belong, possibly causing group failover to occur.

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the RestartAction property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD RestartActionData = ClusterResourceDontRestart;
CLUSPROP_DWORD RestartActionValue;
RestartActionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RestartActionValue.cbLength = sizeof(DWORD);
RestartActionValue.dw = RestartActionData;

The data value for the RestartAction property can be set to ClusterResourceRestartNoNotify or ClusterResourceRestartNotify in addition to ClusterResourceDontRestart. The following table describes each setting:

RestartAction value | Description
ClusterResourceDontRestart | Do not restart the resource after a failure.
ClusterResourceRestartNoNotify | If the resource exceeds its restart threshold within its restart period, do not attempt to fail the group over to another node in the cluster.
ClusterResourceRestartNotify | If the resource exceeds its restart threshold within its restart period, attempt to fail the group over to another node in the cluster.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


RestartPeriod Property for Resources

The RestartPeriod defines a window of time in milliseconds during which a specified number of restart attempts can occur. The RestartThreshold property specifies the allowable number of restart attempts.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the RestartPeriod property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD RestartPeriodData = 900;
CLUSPROP_DWORD RestartPeriodValue;
RestartPeriodValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RestartPeriodValue.cbLength = sizeof(DWORD);
RestartPeriodValue.dw = RestartPeriodData;

The RestartPeriod and RestartThreshold properties work together as follows. If, for example, the RestartPeriod property is set to 200 milliseconds and RestartThreshold property is set to two retry attempts, then a system can tolerate two failures on the resource within any 200 millisecond window. More than two failures can occur, as long as they occur over an interval that is greater than 200 milliseconds. On the third failure within the window, the Cluster Service will attempt to move the group that contains the failed resource to another node.

After the window 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 900 milliseconds.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


RestartThreshold Property for Resources

The RestartThreshold property describes the limit of local retries for the resource within a window defined by the RestartPeriod property before the Cluster Service initiates the action specified by the RestartAction property.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the RestartThreshold property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD RestartThresholdData = 5;
CLUSPROP_DWORD RestartThresholdValue;
RestartThresholdValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
RestartThresholdValue.cbLength = sizeof(DWORD);
RestartThresholdValue.dw = RestartThresholdData;

The RestartThreshold and RestartPeriod properties work together as follows. If, for example, the RestartThreshold property is set to two retry attempts and the RestartPeriod property is set to 200 milliseconds, then a system can tolerate two failures on the resource within any 200 millisecond interval. On the third failure within the window, the Cluster Service will attempt to move the group that contains the failed resource to another node. More than three failures can occur, as long as they occur over an interval that is greater than 200 milliseconds.

If the RestartThreshold property is not specified, the Cluster Service will initiate the action specified by the RestartAction property after three retry attempts.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


SeparateMonitor Property for Resources

The SeparateMonitor property indicates whether or not the resource requires its own Resource Monitor.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the SeparateMonitor property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD SeparateMonitorData = TRUE;
CLUSPROP_DWORD SeparateMonitorValue;
SeparateMonitorValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
SeparateMonitorValue.cbLength = sizeof(DWORD);
SeparateMonitorValue.dw = SeparateMonitorData;

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 will not take effect immediately unless the resource is offline at the time of the change. If the resource is online, the change will take effect after the resource is taken offline and brought back online.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Type Property for Resources

The Type property specifies the display name for the resource's type, such as Physical Disk or Generic Application.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Type property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ TypeValue;
LPCWSTR TypeData = L "Generic Application";
TypeValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
TypeValue.cbLength = sizeof(TypeData);
lstrcpyW(TypeValue.sz, TypeData);

The Name property for resource types also specifies a resource type display name. To retrieve a resource type's Name property, call ClusterResourceTypeControl and set dwControlCode to CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES.

To access the type name of a resource type, call ClusterResourceControl and pass CLUSCTL_RESOURCE_GET_RESOURCE_TYPE for the dwControlCode parameter.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Common Resource Type Properties

Common resource type properties are data values that describe all resource types. They are static values stored in the cluster database. To access the common resource type properties, applications typically call ClusterResourceTypeControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_RESOURCE_TYPE_ENUM_COMMON_PROPERTIES to retrieve the names of the common resource type properties.
  • CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES to retrieve the names and values of common resource type properties that can be modified.
  • CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES to retrieve the names and values of common resource type properties that cannot be modified.
  • CLUSCTL_RESOURCE_TYPE_SET_COMMON_PROPERTIES to update the values of common resource type properties.
  • CLUSCTL_RESOURCE_TYPE_VALIDATE_COMMON_PROPERTIES to validate common resource type properties.

For the get, set, and validate operations, ClusterResourceTypeControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterResourceTypeControl.
  • Structures that are used as input to or output from a property operation.
  • Control codes that can be passed to ClusterResourceTypeControl to retrieve the property.


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.

Quick Info

Type: | LPCWSTR pointer or a WCHAR array
Access: | Read/write
Function: | ClusterResourceTypeControl
Structures: | CLUSPROP_MULTI_SZ
Control Codes: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the AdminExtensions property as one of the entries. The property value portion of the entry contains a CLUSPROP_MULTI_SZ structure that is set as follows:

CLUSPROP_MULTI_SZ AdminExtsValue;
LPCWSTR AdminExtsData = L "CLSID1\0CLSID2\0CLSID3";
AdminExtsValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_MULTI_SZ;
AdminExtsValue.cbLength = sizeof(AdminExtsData);
lstrcpyW(AdminExtsValue.sz, AdminExtsData);

The data value for the AdminExtensions property should be set to one or more class identifier values. Between each value, there should be a null terminator. The NULL character implicit in the string definition terminates the final value.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


DebugControlFunctions Property for Resource Types

The DebugControlFunctions property indicates whether or not the Cluster Service should create a separate Resource Monitor to use for debugging the control functions of the Cluster API.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceTypeControl
Structures: | CLUSPROP_DWORD
Control Codes: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the DebugControlFunctions property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD DebugControlFunctionsData = TRUE;
CLUSPROP_DWORD DebugControlFunctionsValue;
DebugControlFunctionsValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
DebugControlFunctionsValue.cbLength = sizeof(DWORD);
DebugControlFunctionsValue.dw = DebugControlFunctionsData;

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.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


DebugPrefix Property for Resource Types

The DebugPrefix property provides the path to a debugger that will be used to debug all resources of the type that are running in the Resource Monitor for the resource type.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterResourceTypeControl
Structures: | CLUSPROP_SZ
Control Codes: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the DebugPrefix property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

LPCWSTR DebugPrefixData = L "C:\bin\debug.exe";
CLUSPROP_SZ DebugPrefixValue;
DebugPrefixValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DebugPrefixValue.cbLength = sizeof(DebugPrefixData);
lstrcpyW(DebugPrefixValue.sz, DebugPrefixData);

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, 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 type.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Description Property for Resource Types

The Description property provides remarks or comments about the resource type.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterResourceTypeControl
Structures: | CLUSPROP_SZ
Control Codes: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Description property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

LPCWSTR DescriptionData = L "Description of resource type";
CLUSPROP_SZ DescriptionValue;
DescriptionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof(DescriptionData);
lstrcpyW(DescriptionValue.sz, DescriptionData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


DllName Property for Resource Types

The DllName property provides the name of the dynamic-link library (DLL) for the resource type.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterResourceTypeControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the DllName property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

LPCWSTR DllNameData = L "SpreadsheetApp.DLL";
CLUSPROP_SZ DllNameValue;
DllNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DllNameValue.cbLength = sizeof(DllNameData);
lstrcpyW(DllNameValue.sz, DllNameData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


IsAlivePollInterval Property for Resource Types

The IsAlivePollInterval property is the recommended interval in milliseconds that the Cluster Service 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.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceTypeControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

Remarks

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the IsAlivePollInterval property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD IsAlivePollIntervalData = 300;
CLUSPROP_DWORD IsAlivePollIntervalValue;
IsAlivePollIntervalValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
IsAlivePollIntervalValue.cbLength = sizeof(DWORD);
IsAlivePollIntervalValue.dw = IsAlivePollIntervalData;

The IsAlivePollInterval property cannot be zero. It should be set to a value that is as small as possible so as to cause failovers to occur in a timely manner.

The IsAlivePollInterval property is also a common resource property.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


LooksAlivePollInterval Property for Resource Types

The LooksAlivePollInterval property is the recommended interval in milliseconds that 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.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterResourceTypeControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

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 so as 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.

When ClusterResourceTypeControl processes the CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the LooksAlivePollInterval property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD LooksAlivePollIntervalData = 300;
CLUSPROP_DWORD LooksAlivePollIntervalValue;
LooksAlivePollIntervalValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
LooksAlivePollIntervalValue.cbLength = sizeof(DWORD);
LooksAlivePollIntervalValue.dw = LooksAlivePollIntervalData;

The LooksAlivePollInterval property is also a common resource property.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Name Property for Resource Types

The Name property specifies the display name of the resource type, such as Generic Application or Physical Disk.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterResourceTypeControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_TYPE_GET_COMMON_PROPERTIES

Remarks

The display name of a resource type is the name that appears to administrators in the user interface. It is important to distinguish between the display name of the resource type and the resource type name. The resource type name is returned by ClusterResourceControl when CLUSCTL_RESOURCE_GET_RESOURCE_TYPE is passed as the dwControlCode parameter. This type name is:

  • Used by resource DLLs and cluster management applications to determine required dependencies that have been met.
  • Passed to ClusterResourceTypeControl in the contents of the ResourceTypeName parameter.
  • Passed to GetClusterResourceKey in the contents of the lpszTypeName parameter.
  • Returned by ClusterOpenEnum when you specify CLUSTER_ENUM_RESTYPE in the dwType parameter.

The Type property for resources also specifies a resource type display name. To retrieve a resource's Type property, call ClusterResourceControl and set dwControlCode to CLUSCTL_RESOURCE_GET_COMMON_PROPERTIES.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Common Group Properties

Common group properties are data values that describe all groups. They are static values stored in the cluster database. To access the common group properties, applications typically call ClusterGroupControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_GROUP_ENUM_COMMON_PROPERTIES to retrieve the names of the common group properties.
  • CLUSCTL_GROUP_GET_COMMON_PROPERTIES to retrieve the names and values of common group properties that can be modified.
  • CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES to retrieve the names and values of common group properties that cannot be modified.
  • CLUSCTL_GROUP_SET_COMMON_PROPERTIES to update the values of common group properties.
  • CLUSCTL_GROUP_VALIDATE_COMMON_PROPERTIES to validate common group properties.

For the get, set, and validate operations, ClusterGroupControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterGroupControl.
  • Structures that are used as input to or output from a property operation.
  • Control codes that can be passed to ClusterGroupControl to retrieve the property.


AutoFailbackType Property for Groups

The AutoFailbackType property specifies whether or not the group should automatically be moved to the node identified as its preferred owner when that node comes back online following a failover.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterGroupControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

Failback refers to the process by which a group is moved to its original node after that node has failed and been brought back online.

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the AutoFailbackType property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD AutoFailbackTypeData = ClusterGroupAllowFailback;
CLUSPROP_DWORD AutoFailbackTypeValue;
AutoFailbackTypeValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
AutoFailbackTypeValue.cbLength = sizeof(DWORD);
AutoFailbackTypeValue.dw = AutoFailbackTypeData;

The data for the AutoFailbackType property can be set to one of the following values:

Value | Description
ClusterGroupPreventFailback | Prevents failback.
ClusterGroupAllowFailback | Allows failback.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Description Property for Groups

The Description property provides remarks or comments about the group.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterGroupControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Description property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DescriptionValue;
LPCWSTR DescriptionData = L "Description of group";
DescriptionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof(DescriptionData);
lstrcpyW(DescriptionValue.sz, DescriptionData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


FailbackWindowStart Property for Groups

The FailbackWindowStart property provides the earliest time that the group can be moved back to the node identified as its preferred node.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterGroupControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the FailbackWindowStart property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD FailbackWindowStartData = 10;
CLUSPROP_DWORD FailbackWindowStartValue;
FailbackWindowStartValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailbackWindowStartValue.cbLength = sizeof(DWORD);
FailbackWindowStartValue.dw = FailbackWindowStartData;

The data for the FailbackWindowStart property is a number between 0, which represents midnight, and 23, which represents 11:00 p.m., or – 1. The – 1 indicates that there is no failback window.

The FailbackWindowStart and FailbackWindowEnd properties define an amount of time within a 24-hour period that a group can failback. FailbackWindowStart may be less than or greater than FailbackWindowEnd, depending on the window. For example, if the window is from 10 P.M. until 2 A.M., FailbackWindowStart is set to 10 and FailbackWindowEnd to 2. For a failback window to exist, the group must have a value for both the FailbackWindowStart and FailbackWindowEnd properties if a failback window does not exist because the group is missing one or both of these properties, failback operations occur immediately after the preferred node has restarted.

When a node reboots and determines that it should fail back a group, it checks the current system time. If this time is not within the window defined by the FailbackWindowStart and FailbackWindowEnd properties, the node waits until the current time falls within this window before beginning the failback process.

If the current owner of the group fails before the failback window can be reached, every group hosted by the failed node is moved regardless of the failback windows settings.

Note The time for a failback window represents local cluster time.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


FailbackWindowEnd Property for Groups

The FailbackWindowEnd property provides the latest time that the group can be moved back to the node identified as its preferred node.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterGroupControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the FailbackWindowEnd property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD FailbackWindowEndData = 12;
CLUSPROP_DWORD FailbackWindowEndValue;
FailbackWindowEndValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailbackWindowEndValue.cbLength = sizeof(DWORD);
FailbackWindowEndValue.dw = FailbackWindowEndData;

The data for the FailbackWindowEnd property is a number between 0, which represents midnight, and 23, which represents 11:00 p.m., or – 1. The – 1 indicates that there is no failback window.

The FailbackWindowStart and FailbackWindowEnd properties define an amount of time within a 24-hour period that a group can failback. The time represents local cluster time. For a failback window to exist, the group must have a value for both the FailbackWindowStart and FailbackWindowEnd properties. If a failback window does not exist because the group is missing one or both of these properties, failback operations occur immediately after the preferred node has restarted.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


FailoverThreshold Property for Groups

The FailoverThreshold property specifies the number of attempts at failover that are made before the Cluster Service concludes that the group cannot be brought online anywhere in the cluster.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterGroupControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the FailoverThreshold property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD FailoverThresholdData = 5;
CLUSPROP_DWORD FailoverThresholdValue;
FailoverThresholdValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailoverThresholdValue.cbLength = sizeof(DWORD);
FailoverThresholdValue.dw = FailoverThresholdData;

The FailoverThreshold property specifies the number of attempts within a number of hours defined by the FailoverPeriod property that the Cluster Service can try to failover the group. For example, if FailoverThreshold is set to two and RestartPeriod is set to one, then a node can tolerate two failover attempts of the group within any one hour interval. On the third failover attempt within one hour, the node will not attempt to move the group. More than three failover attempts can occur, as long as they occur over an interval that is greater than one hour.

If a value for FailoverThreshold is not specified, the default value is 10.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


FailoverPeriod Property for Groups

The FailoverPeriod property specifies a number of hours during which the Cluster Service can attempt to failover the group.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterGroupControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the FailoverPeriod property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD FailoverPeriodData = 5;
CLUSPROP_DWORD FailoverPeriodValue;
FailoverPeriodValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
FailoverPeriodValue.cbLength = sizeof(DWORD);
FailoverPeriodValue.dw = FailoverPeriodData;

The FailoverThreshold property specifies the number of attempts within a number of hours defined by the FailoverPeriod property that the Cluster Service can try to failover the group. For example, if FailoverThreshold is set to two and RestartPeriod is set to one, then a node can tolerate two failover attempts of the group within any one hour interval. On the third failover attempt within one hour, the node will not attempt to move the group. More than three failover attempts can occur, as long as they occur over an interval that is greater than one hour.

If a value for FailoverPeriod is not specified, the default value is six hours.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Name Property for Groups

The Name property specifies the name of the group.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterGroupControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the Name property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NameValue;
LPCWSTR NameData = L "Spreadsheet App Group";
NameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof(NameData);
lstrcpyW(NameValue.sz, NameData);

Applications can change a group's name by calling the Cluster API function SetClusterGroupName.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


PersistentState Property for Groups

The PersistentState property describes the last known persistent state of the group.

Quick Info

Type: | DWORD
Access: | Read/write
Function: | ClusterGroupControl
Structures: | CLUSPROP_DWORD
Control Codes: | CLUSCTL_GROUP_GET_COMMON_PROPERTIES

Remarks

When ClusterGroupControl processes the CLUSCTL_GROUP_GET_COMMON_PROPERTIES control code, it returns a property list that includes the PersistentState property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD PersistentStateData = FALSE;
CLUSPROP_DWORD PersistentStateValue;
PersistentStateValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
PersistentStateValue.cbLength = sizeof(DWORD);
PersistentStateValue.dw = PersistentStateData;

The data value for the PersistentState property describes what should happen to the group the next time the Cluster Service is started. Valid values are TRUE and FALSE. When PersistentState is set to TRUE, the group should be brought online. When set to FALSE, it should be left offline.

Resources use their group's PersistentState property when they lack a value for their own PersistentState property.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Common Node Properties

Common node properties are data values that describe all nodes. They are static values stored in the cluster database. To access common node properties, applications typically call ClusterNodeControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_NODE_ENUM_COMMON_PROPERTIES to retrieve the names of the common node properties.
  • CLUSCTL_NODE_GET_COMMON_PROPERTIES to retrieve the names and values of common node properties that can be modified.
  • CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES to retrieve the names and values of common node properties that cannot be modified.
  • CLUSCTL_NODE_SET_COMMON_PROPERTIES to update the values of common node properties.
  • CLUSCTL_NODE_VALIDATE_COMMON_PROPERTIES to validate common node properties.

For the get, set, and validate operations, ClusterNodeControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterNodeControl.
  • Control codes that can be passed to ClusterNodeControl to invoke property operations.
  • Structures that are used as input to or output from a property operation.


Description Property for Nodes

The Description property provides remarks or comments about the node.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Function: | ClusterNodeControl
Structures: | CLUSPROP_SZ
Control Codes: | CLUSCTL_NODE_GET_COMMON_PROPERTIES

Remarks

When ClusterNodeControl processes the CLUSCTL_NODE_GET_COMMON_PROPERTIES control code, it returns a property list that includes the Description property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DescriptionValue;
LPCWSTR DescriptionData = L "Node Description";
DescriptionValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DescriptionValue.cbLength = sizeof(DescriptionData);
lstrcpyW(DescriptionValue.sz, DescriptionData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


NodeName Property for Nodes

The NodeName property provides the node's name.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Function: | ClusterNodeControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES

Remarks

When ClusterNodeControl processes the CLUSCTL_NODE_GET_RO_COMMON_PROPERTIES control code, it returns a property list that includes the NodeName property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NodeNameValue;
LPCWSTR NodeNameData = L "NodeA";
NodeNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NodeNameValue.cbLength = sizeof(NodeNameData);
lstrcpyW(NodeNameValue.sz, NodeNameData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Private Resource Properties

Private resource properties are data values that apply to resources of a particular type. Private resource properties can be static values stored in the cluster database, static values stored elsewhere, or dynamic values generated on demand.

To access private resource properties, applications typically call ClusterResourceControl with one of the following values for the dwControlCode parameter:

  • CLUSCTL_RESOURCE_ENUM_PRIVATE_PROPERTIES to retrieve the names of a resource's private properties.
  • CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES to retrieve the names and values of a resource's private properties that can be modified.
  • CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES to retrieve the names and values of a resource's private properties that cannot be modified.
  • CLUSCTL_RESOURCE_SET_PRIVATE_PROPERTIES to update the values of a resource's private properties.
  • CLUSCTL_RESOURCE_VALIDATE_PRIVATE_PROPERTIES to validate a resource's private properties.

For the get, set, and validate operations, ClusterResourceControl either requires as input or returns as output a property list that contains an entry for every property. Each entry has two parts: a property name and a property value. The property name contains a syntax value, a string describing the name, the length of the string, and padding if necessary to properly align the name. The property value is similar to the name in that it also contains a syntax value and a length. The data portion varies depending on the type of property. For most properties, a cluster structure such as CLUSPROP_SZ or CLUSPROP_DWORD is used to store the property value in the property list.

The Quick Info tables that appear with each property describe the following pieces of information:

  • Property type.
  • Property access level.
  • Functions that can be called to access the property such as ClusterResourceControl.
  • Structures that are used as input to or output from a property operation.
  • Control codes that can be passed to ClusterResourceControl to retrieve the property.


Private Properties for File Share Resources

File Share resources have several private properties, some that are required and others that are optional. The following table lists these properties:

MaxUsers | Optional
Path | Required
Remark | Optional
Security | Optional
ShareName | Required

Cluster Administrator presents the File Share private properties on the property page associated with the Parameters tab for File Share resources.


MaxUsers Property for File Shares

The MaxUsers property describes the number of simultaneous users that can access the file share.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the MaxUsers property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD MaxUsersData = 10;
CLUSPROP_DWORD MaxUsersValue;
MaxUsersValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
MaxUsersValue.cbLength = sizeof(DWORD);
MaxUsersValue.dw = MaxUsersData;

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Path Property for File Shares

The Path property describes the path to the directory being shared.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Path property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ PathValue;
LPCWSTR PathData = L "\\NodeA\ShareDirectory";
PathValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
PathValue.cbLength = sizeof(PathData);
lstrcpyW(PathValue.sz, PathData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Remark Property for File Shares

The Remark property provides a description of the File Share resource.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Remark property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ RemarkValue;
LPCWSTR RemarkData = L "File Share Description";
RemarkValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
RemarkValue.cbLength = sizeof(RemarkData);
lstrcpyW(RemarkValue.sz, RemarkData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Security Property for File Shares

The Security property describes the security access needed to access the file share.

Quick Info

Type: | Security descriptor
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_BINARY
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

The Security property is what is read and written when a network administrator presses the Permissions button in Cluster Administrator.

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Security property as one of the entries.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ShareName Property for File Shares

The ShareName property describes the name of the file share present on the network.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the ShareName property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ ShareNameValue;
LPCWSTR ShareNameData = L "Sharename";
ShareNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
ShareNameValue.cbLength = sizeof(ShareNameData);
lstrcpyW(ShareNameValue.sz, ShareNameData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Private Properties for Generic Application Resources

Generic Application resources have several private properties, some that are required and others that are optional. The following table lists these properties:

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.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the CommandLine property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ CommandLineValue;
LPCWSTR CommandLineData = L "C:\bin\MyApp.exe";
CommandLineValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
CommandLineValue.cbLength = sizeof(CommandLineData);
lstrcpyW(CommandLineValue.sz, CommandLineData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


CurrentDirectory Property for Generic Applications

The CurrentDirectory property describes the directory in which the application should be run.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the CurrentDirectory property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ CurrentDirectoryValue;
LPCWSTR CurrentDirectoryData = L "C:\bin";
CurrentDirectoryValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
CurrentDirectoryValue.cbLength = sizeof(CurrentDirectoryData);
lstrcpyW(CurrentDirectoryValue.sz, CurrentDirectoryData);

The path in the CurrentDirectory property must be an absolute path on a shared disk. An environment variable representing a path cannot be used. A dot (.) defaults to the directory in which the Cluster Service is installed.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


InteractWithDesktop Property for Generic Applications

The InteractWithDesktop property specifies whether the application can provide a user interface on the desktop that can be used by any person logged in on the node on which the resource is online.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the InteractWithDesktop property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD InteractWithDesktopData = TRUE;
CLUSPROP_DWORD InteractWithDesktopValue;
InteractWithDesktopValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
InteractWithDesktopValue.cbLength = sizeof(DWORD);
InteractWithDesktopValue.dw = InteractWithDesktopData;

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 access to its own windows but only write access to the rest of the desktop.

Setting InteractWithDesktop to FALSE causes the application to be inaccessible from either the desktop or the toolbar.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


UseNetworkName Property for Generic Applications

The UseNetworkName property affects the outcome of a call to the Win32 function GetComputerName.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the UseNetworkName property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD UseNetworkNameData = TRUE;
CLUSPROP_DWORD UseNetworkNameValue;
UseNetworkNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
UseNetworkNameValue.cbLength = sizeof(DWORD);
UseNetworkNameValue.dw = UseNetworkNameData;

The data for the UseNetworkName property can be set to TRUE or FALSE. Setting it to TRUE causes calls to the Win32 function GetComputerName to return the network name of the Network Name resource on which the application is dependent. Setting it to FALSE causes GetComputerName to return the name of the node that is currently online and running the application.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Private Properties for Generic Service Resources

Generic Service resources have three private properties, some that are required and others that are optional. The following table lists these properties:

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 service when it is started.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the StartupParameters property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ StartupParametersValue;
LPCWSTR StartupParametersData = L "C:\bin\MyService.exe";
StartupParametersValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
StartupParametersValue.cbLength = sizeof(StartupParametersData);
lstrcpyW(StartupParametersValue.sz, StartupParametersData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ServiceName Property for Generic Services

The ServiceName property describes the short name of the service to run.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the ServiceName property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ ServiceNameValue;
LPCWSTR ServiceNameData = L "MYSVC";
ServiceNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
ServiceNameValue.cbLength = sizeof(ServiceNameData);
lstrcpyW(ServiceNameValue.sz, ServiceNameData);

For more information about service names, see the Win32 function CreateService.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


UseNetworkName Property for Generic Services

The UseNetworkName property affects the outcome of a call to the Win32 function GetComputerName.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the UseNetworkName property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD UseNetworkNameData = TRUE;
CLUSPROP_DWORD UseNetworkNameValue;
UseNetworkNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
UseNetworkNameValue.cbLength = sizeof(DWORD);
UseNetworkNameValue.dw = UseNetworkNameData;

The data for the UseNetworkName property can be set to TRUE or FALSE. Setting it to TRUE causes calls to the Win32 function GetComputerName to return the network name of the Network Name resource on which the service is dependent. Setting it to FALSE causes GetComputerName to return the name of the node that is currently online and running the service.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Private Properties for IIS Virtual Root Resources

Each Internet Information Server (IIS) Virtual Root resource is an IIS Website, an FTP site, or a Gopher site containing a collection of IIS Virtual Directories. Each Cluster Server IIS Virtual Root resource is dependent on an IP Address resource.

IIS Virtual Root resources have several private properties, some that are required and others that are optional. The following table lists these properties:

AccessMask | Optional
Alias | Required
Directory | Required
ServiceName | Required

Cluster Administrator presents the IIS Virtual Root resource properties on the property page associated with the Parameters tab for IIS Virtual Roots.


AccessMask Property for IIS Virtual Roots

The AccessMask property specifies the protection required for the IIS Virtual Root.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the AccessMask property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD AccessMaskData = VROOT_MASK_READ;
CLUSPROP_DWORD AccessMaskValue;
AccessMaskValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
AccessMaskValue.cbLength = sizeof(DWORD);
AccessMaskValue.dw = AccessMaskData;

The data for the AccessMask property can be set to one of the following values:

VROOT_MASK_READ for read-only access

VROOT_MASK_WRITE for read/write access

VROOT_MASK_EXECUTE for execute access

AccessMask is set differently depending on the type of IIS Virtual Root. Gopher services have no permissions.

For FTP Virtual Roots that accept data from users, AccessMask should be set to VROOT_MASK_WRITE. However, assign VROOT_MASK_WRITE cautiously. It is important to prevent unauthorized users from placing files on, or deleting information from, the cluster node.

For WWW Virtual Roots that contain programs, scripts, and Internet Server API (ISAPI) applications, AccessMask should be set to VROOT_MASK_EXECUTE.

Note Although IIS Virtual Roots that contain content files should typically have an AccessMask of VROOT_MASK_READ, resources with execute access are an exception. Do not set an IIS Virtual Root's AccessMask to VROOT_MASK_EXECUTE and VROOT_MASK_READ. Setting both VROOT_MASK_EXECUTE and VROOT_MASK_READ will prevent users from seeing any executable files with interactive content.

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Alias Property for IIS Virtual Roots

The Alias property describes the subdirectory name that clients use to access the IIS Virtual Root.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

The data for the Alias property is a string that is preceded by a forward slash. When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Alias property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ AliasValue;
LPCWSTR AliasData = L "/alias";
AliasValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AliasValue.cbLength = sizeof(AliasData);
lstrcpyW(AliasValue.sz, AliasData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Directory Property for IIS Virtual Roots

The Directory property describes the physical location of the IIS Virtual Root.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

The data for the Directory property is a full directory path. When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Directory property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DirectoryValue;
LPCWSTR DirectoryData = L "C:\SCRIPTS";
DirectoryValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DirectoryValue.cbLength = sizeof(DirectoryData);
lstrcpyW(DirectoryValue.sz, DirectoryData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


ServiceName Property for IIS Virtual Roots

The ServiceName property describes the type of Web service with which the IIS Virtual Root will be used.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the ServiceName property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ ServiceNameValue;
LPCWSTR ServiceNameData = L "W3SVC";
ServiceNameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
ServiceNameValue.cbLength = sizeof(ServiceNameData);
lstrcpyW(ServiceNameValue.sz, ServiceNameData);

There are three types of Web services for IIS Virtual Roots: WWW, FTP, and Gopher. Each type has a corresponding value for the ServiceName property. The following table maps these types with the appropriate value for their ServiceName property.

Type of IIS Virtual Root | Value of ServiceName
WWW | W3SVC
FTP | MSFTPSVC
Gopher | GOPHERSVC

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Private Properties for IP Address Resources

IP Address resources have three private properties. All three are required. The following table lists these properties:

Address | Required
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.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

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.

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Address property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ AddressValue;
LPCWSTR AddressData = L "111.244.221.454";
AddressValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
AddressValue.cbLength = sizeof(AddressData);
lstrcpyW(AddressValue.sz, AddressData);


Network Property for IP Addresses

The Network property describes the network for which the IP address is to be created.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

The Network property is the name of the network. When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Network property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NetworkValue;
LPCWSTR NetworkData = L "NetworkX";
NetworkValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NetworkValue.cbLength = sizeof(NetworkData);
lstrcpyW(NetworkValue.sz, NetworkData);


SubnetMask Property for IP Addresses

The SubnetMask property describes the subnet mask to be applied for routing for the IP address.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

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.

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the SubnetMask property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ SubnetMaskValue;
LPCWSTR SubnetMaskData = L "122.232.561.478";
SubnetMaskValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
SubnetMaskValue.cbLength = sizeof(SubnetMaskData);
lstrcpyW(SubnetMaskValue.sz, SubnetMaskData);


Private Properties for Network Name Resources

Network Name resources have one private property which is required:

Name

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 Name resource.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read-only
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES

Remarks

In every cluster, there are two types of Network Name resources:

  • Core Network Name resource
  • Non core Network Name resources

The core Network Name resource belongs to the cluster group and provides the cluster name. Without it the cluster cannot operate.

Non core Network Name resources belong to other groups, groups that can be taken offline and not affect cluster operation.

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_RO_PRIVATE_PROPERTIES control code, it returns a property list that includes the Name property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ NameValue;
LPCWSTR NameData = L "Redmond Cluster";
NameValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
NameValue.cbLength = sizeof(NameData);
lstrcpyW(NameValue.sz, NameData);

All Network Name resources have a required dependency on an IP Address resource.

To set the Name property for the core Network Name resource, applications must call the Cluster API function SetClusterName.


Private Properties for Physical Disk Resources

Physical Disk resources have two private properties:

Drive

Signature

One of the properties must be defined, but not both. Cluster Administrator presents these properties on the property page associated with the Parameters tab for Physical Disk resources.


Drive Property for Physical Disks

The Drive property specifies the drive letter for the Physical Disk resource.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required only if the Signature property is not provided
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

The Drive property is used to create Physical Disk resources with the command-line tool CLUSTER.EXE. The drive letter for a disk does not have to be unique. However, it is recommended that resource DLLs attempt to make drive letters match across machines.

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes an entry for the Drive property for each partition for the resource.

The property value portion of the property list entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DriveValue;
LPCWSTR DriveData = L "D:";
DriveValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DriveValue.cbLength = sizeof(DriveData);
lstrcpyW(DriveValue.sz, DriveData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Signature Property for Physical Disks

The Signature property specifies the signature for the Physical Disk resource.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Required only if the Drive property is not provided
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

The Signature property specifies a globally unique identifier for the disk regardless of the machine. When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the Signature property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD SignatureData = 12343;
CLUSPROP_DWORD SignatureValue;
SignatureValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
SignatureValue.cbLength = sizeof(DWORD);
SignatureValue.dw = SignatureData;

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


Private Properties for Print Spooler Resources

Print Spooler resources have two private properties:

DefaultSpoolDirectory | Required
JobCompletionTimeout | Optional

Cluster Administrator presents this property 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.

Quick Info

Type: | Null-terminated Unicode string
Access: | Read/write
Status: | Required
Function: | ClusterResourceControl
Structure: | CLUSPROP_SZ
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the DefaultSpoolDirectory property as one of the entries. The property value portion of the entry contains a CLUSPROP_SZ structure that is set as follows:

CLUSPROP_SZ DefaultSpoolDirValue;
LPCWSTR DefaultSpoolDirData = L "C:\tmp";
DefaultSpoolDirValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_SZ;
DefaultSpoolDirValue.cbLength = sizeof(DefaultSpoolDirData);
lstrcpyW(DefaultSpoolDirValue.sz, DefaultSpoolDirData);

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


JobCompletionTimeout Property for Print Spoolers

The JobCompletionTimeout property is the number of milliseconds before a pending job is deleted from the Print Spooler resource's queue.

Quick Info

Type: | DWORD
Access: | Read/write
Status: | Optional
Function: | ClusterResourceControl
Structure: | CLUSPROP_DWORD
Control Code: | CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES

Remarks

When ClusterResourceControl processes the CLUSCTL_RESOURCE_GET_PRIVATE_PROPERTIES control code, it returns a property list that includes the JobCompletionTimeout property as one of the entries. The property value portion of the entry contains a CLUSPROP_DWORD structure that is set as follows:

DWORD JobCompletionTimeOutData = 200;
CLUSPROP_DWORD JobCompletionTimeOutValue;
JobCompletionTimeOutValue.Syntax = CLUSPROP_SYNTAX_LIST_VALUE_DWORD;
JobCompletionTimeOutValue.cbLength = sizeof(DWORD);
JobCompletionTimeOutValue.dw = JobCompletionTimeOutData;

QuickInfo

Version: Use Windows NT Server Enterprise Edition 4.0.
Windows CE: Unsupported.
Header: Declared in clusapi.h.


A

Arbitration
Process of granting ownership of the quorum resource. A quorum resource implements the Arbitrate and Release entry point functions in its resource DLL to support arbitration.
Asynchronous Transfer Mode (ATM)
A high-speed cell-switching network technology for LANs and WANs that handles data and real-time voice and video.
Availability
Continuous operation regardless of failures. Cluster Server is designed to make applications highly available.


B

Backup Domain Controller (BDC)
Microsoft® Windows NT® Server network operating system that contains copies of the user account information and is available to authenticate users when they log on to the domain. BDCs also provide authentication fault tolerance. If the Primary Domain Controller (PDC) is down for any reason, BDCs are available to authenticate users and guarantee their access to network resources.
Bandwidth
Amount of data per second that can be transferred from one device to another. Bandwidth is limited by (a) the speed of transfer, (b) the "width" of the pipe, (c) the number of pipes, and (d) the overhead of sending data through the pipe.


C

Checkpoint Manager
Software component in the Cluster Service that is responsible for saving data in the log file maintained by the quorum resource.
Client application
Application software that is running on a network client system and does not necessarily perform name translation or establish connections.
Client/server model
Architecture that splits an application into a front-end client component and a back-end server component. The client component running on a workstation 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 it receives a request, the server processes it and returns the requested information to the client. The client then presents the data to the user through its own user interface.
Cluster
Two computer systems running Microsoft® Windows NT® Server that are accessed and managed as a single system.
Cluster Administrator
Cluster Server application that is used to manage and administer a cluster. Cluster Administrator can run on a client or server machine regardless of whether the machine is an active member of a cluster.
Cluster Administrator extension
Software component that implements the Cluster Administrator extension API for allowing Cluster Administrator to administer a new resource type.
Cluster API
Collection of functions that are implemented by the Cluster Service and used by a cluster-aware client or server application, a cluster management application, or a resource DLL. The Cluster API includes functions for managing the cluster as a whole, nodes, groups, resources, and the cluster database.
Cluster Automation Server
The library of COM-based interfaces that developers writing in Visual Basic and various scripting languages use to create cluster management applications.
Cluster-aware application
Server application that can run on a cluster node and be managed as a cluster resource.
Cluster member
A node that is an active participant of a cluster. A cluster member is in constant communication with the other members of the cluster and maintains a current version of the cluster database.
Cluster Service
Cluster Server software component implemented as a Microsoft® Windows NT® service that controls all aspects of cluster operation and manages the configuration database. Every node in a cluster runs one instance of the Cluster Service.
Cluster-unaware application
Client application that can run on a cluster node and be managed as a cluster resource, but has no inherent knowledge of its cluster environment. Client applications function the same regardless of whether they are running on a node in a cluster or on a non-clustered system.
Communications line
Physical connection by which information flows from the network into the computer. Examples are twisted-pair, coaxial, and fiber-optic cable.
Communications Manager
Software component in the Cluster Service that maintains communication between cluster members and blocks communication when a node fails.
Core Network Name Resource
The Network Name resource for the cluster.


D

Database Manager
Software component in the Cluster Service that manages the cluster database.
Dependency
Relationship between two resources that makes it necessary for them to run in the same group and dictates the order in which they are taken offline and brought back online. For example, an application resource is dependent upon the disk resources that contain its data.
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 will still lose data.
Disk striping
Spreading data over multiple disk drives. Data is interleaved by bytes or sectors/blocks across the drives.
Domain Name System (DNS)
Service that maps friendly names to IP addresses. DNS is used on the Internet for resolving names to Internet addresses.


E

Ethernet
Widely used LAN developed by Xerox, Digital, and Intel. Ethernet networks connect up to 1,024 nodes at 10 megabits per second over twisted pair, coax, and optical fiber.
Event Processor
Software component in the Cluster Service that is responsible for initialization and supports event notification.


F

Failback
Process of moving a resource group back to its preferred node after the node has failed and come back online.
Failed
State that applies to a cluster resource that is unavailable. A resource is placed in the failed state after an unsuccessful attempt has been made by the Cluster Service to bring it online.
Failover
Process of taking a resource group offline on one node and bringing it online on another node. The offline and online transitions occur in a predefined order, with resources that are dependent on other resources taken offline before and brought online after the resources upon which they depend.
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 an administrator can set using Cluster Administrator to 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. See also Failover.
Fault tolerant
Non-stop availability. Fault tolerant systems are typically implemented by configuring a backup of the primary system that remains idle and unused until a failure occurs.
File Share resource
A file or print share that applications can access using a network path. Cluster Server provides a resource DLL to manage File Share resources.


G

Generic Application resource
A cluster-aware or cluster-unaware application that is running on a cluster node and being managed as a cluster resource. Cluster Server provides a resource DLL to manage Generic Application resources.
Generic Service resource
A Microsoft® Windows NT® service that is running on a cluster node and is being managed as a cluster resource. Cluster Server provides a resource DLL to manage Generic Service resources.
Global Update Manager
Software component in the Cluster Service that provides a global update service that is used by other components in the Cluster Service.
Group
Collection of resources to be managed as a single unit. Typically a group contains all of the resources needed to run a specific application or service. When a group contains a Network Name resource and an IP Address resource, it can be accessed as a virtual server.


H

Heartbeat
Message that is sent regularly by the Cluster Service on one node to the Cluster Service on an alternate node to maintain communication and detect failure.
Host adapter
Circuitry that translates between a processor's internal bus and a different bus, such as a SCSI. On the SCSI bus, a host acts as an initiator and the peripheral acts as the target.
Hub
Central connecting device in a network that joins communications lines together in a star configuration.


I

IIS Virtual Root resource
A virtual root to be used with Internet Information Server (IIS) that supports the WWW, FTP, and GOPHER services. IIS Virtual Root resources may have dependencies on IP Address resources, Network Name resources, and/or Physical Disk resources. Virtual roots containing access information are not supported. Cluster Server provides a resource DLL for managing IIS Virtual Root resources.
Interconnect
Private network that connects nodes in a cluster.
IP Address resource
A 32-bit number in dotted decimal format that represents an Internet Protocol (IP) address. Cluster Server provides a resource DLL for managing IP Address resources. When a group contains an IP Address resource and a Network Name resource, it can be accessed by clients as a virtual server.


L

Latency
Time between two events.
Logical unit
Physical or virtual device addressable through a SCSI target device. A physical device can have more than one logical unit.


M

Membership Manager
Software component in the Cluster Service that maintains information about the cluster's current membership.


N

Network Name resource
A friendly name of an entity that exists on a network. Cluster Server provides a resource DLL for managing Network Name resources. When a group contains a Network Name resource and an IP Address resource, it can be accessed by clients as a virtual server.
Network partition
Situation that occurs when there is a network failure and one node in a cluster cannot receive heartbeat signals from the other node. Also known as split brain syndrome.
No Remote Memory Access (NORMA)
Clustering architecture where all memory is local to each system and all communication between systems consists of message passing. Shared-disk architectures are sometimes included in this classification.
Node
Microsoft® Windows NT® Server network operating system that is an active or inactive member of a cluster.


O

Offline
State that applies to a cluster resource, group, or node and marks that object as unavailable. The Cluster Service of an offline node may or may not be running.
Online
State that applies to a cluster resource, group, or node and marks that object as available. When a node is online, it is an active member of the cluster and can own and run groups as well as honor cluster database updates, contribute votes to the quorum algorithm, and maintain heartbeats.


P

Packet switching
Transmission technique that maximizes the use of digital transmission facilities by simultaneously transmitting packets of digital data from many sources on a single communications channel. This networking technology breaks up a message into smaller pieces for transmission. It is the most common form of data transmission technology used in LANs and WANs.
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 property block.
Partitioned
A state in which one or more of the nodes in a cluster cannot communicate with the other cluster members.
Paused
State that applies to a node that is a fully active member in the cluster, but cannot own or run groups. The paused state is provided to allow an administrator to perform maintenance.
Pending
State that refers to a resource that is in the process of being brought online or taken offline.
Peripheral Component Interconnect (PCI)
Local bus for personal computers that provides a high-speed data path between the processor and peripheral devices.
Physical Disk resource
Disk on a SCSI bus connected to two or more nodes that contains shared folders or storage. Cluster Server provides a resource DLL for managing Physical Disk resources.
Preservation of transaction state
System design for preventing the loss of data in a transitional state.
Primary Domain Controller (PDC)
Microsoft® Windows NT® Server network operating system that manages all of the domain's user account information.
Print Spooler resource
A network printer that applications access using a network IP address rather than an individual name. Cluster Server provides a resource DLL for managing Print Spooler resources.
Property list
A collection of information used to describe multiple properties in control code operations. Each entry except the final one in a property lists contains a property name and property value. The property name contains a CLUSPROP_VALUE structure, a name string, and padding if necessary to align the name on a DWORD boundary. The property value contains a CLUSPROP_VALUE structure, data, and padding if necessary. The final entry contains only the CLUSPROP_SYNTAX_ENDMARK value.
Property table
An array of RESUTIL_PROPERTY_ITEM structures used as an input parameter to or output parameter from a Cluster Resource Utility function. Each entry in a property table contains information about a property and an offset to the property's data in a buffer known as a parameter block.
Pulling a group
Process of transferring control of all groups in a cluster to one or more alternate nodes when the current node fails. The remaining nodes negotiate for ownership of each group and when negotiation is complete, the nodes update their cluster databases.
Pushing a group
Process of restarting a group on a different node when one of its resources fail. This process can be initiated manually by an administrator, causing each of the affected resources to gracefully shutdown prior to the failover, or by the Resource Manager.


Q

Quorum
Voting mechanism used to guarantee that specific data necessary for recovery can be maintained consistently between all cluster members. This mechanism involves a special resource called the quorum resource. The recovery data is stored by the quorum resource, typically a physical disk or fault tolerant disk set that can be owned by one cluster node at any point in time. When the node that owns the quorum resource fails, the surviving nodes arbitrate to take over its ownership.

Each quorum resource receives one vote and that vote is transitively passed to the node that currently owns the resource. By default there is only one quorum resource per cluster. The quorum mechanism is maintained by Cluster Service's Membership Manager.

Quorum-capable resource
A cluster resource that can act as a cluster's quorum resource. A quorum-capable resource must provide a means for persistent storage of configuration information necessary for recovery and a means for arbitration. Arbitration is the process by which cluster nodes effectively negotiate for ownership of the quorum resource. The SCSI reserve and release functions are examples of this type of arbitration support. In Cluster Server version 1.0, only physical disk resources and fault tolerant disk set resources are quorum-capable.
Quorum log
See Recovery log.
Quorum resource
The quorum-capable resource selected to maintain the configuration data necessary for recovery of the cluster. This data contains details of all changes that have been applied to the cluster database. The quorum resource is generally accessible to other cluster resources so that any cluster node has 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 any of the cluster nodes. The recovery log is stored on the cluster's quorum resource and is also referred to as the quorum log.
Redundant Array of Inexpensive Disks (RAID)
A storage device that uses two or more magnetic or optical disks working in tandem to increase performance and provide various levels of error recovery and fault tolerance. RAID can be implemented in software using standard disk controllers, or it can be designed into the disk controller itself.
Reliability
Degree to which data in a transfer is guaranteed to arrive at its destination in its intended form. Reliability refers to three distinct attributes: (a) the degree to which a system or component achieves a transfer, (b) the degree to which a system or component can fail and the transfer still occur, and (c) the degree to which the integrity of the data is preserved.
Resource
Physical or logical entity owned and managed by a cluster node which can be brought online and taken offline. A resource can only be hosted on a single cluster node at any point in time.
Resource API
Set of functions that allow a resource DLL to communicate with the 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 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 Cluster Service's Failover Manager to manage resources and groups and initiate failover operations.
Resource Monitor
Cluster software component that manages communication between a node's Cluster Service and one or more of its resources.
Router
An intelligent hub that routes traffic to a designated channel.


S

Scalability
Ability to incrementally add one or more systems to an existing cluster when the overall load of the cluster exceeds its capabilities.
Server application
Application software running on a cluster node, regardless of whether it does service registration.
Service
Data or operation made available to network clients through a virtual server, a resource group that contains a Network Name resource as well as an IP Address resource. Not necessarily a Microsoft® Windows NT® Service.
Shared device model
See Shared disk model.
Shared disk model
Clustering architecture where all systems share devices.
Shared memory model
Clustering architecture where all systems share a single main memory through which all traffic between devices must flow.
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. Cluster Server uses shared nothing clusters.
Shared resource
Cluster organization in which some resources are accessible to all systems in the cluster.
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.
SMB share resource
See File Share resource.
Symmetric Multiprocessing (SMP)
A computer architecture in which multiple processors share global memory and a single copy of the operating system. Application processes run as if they were on a single processor system.
System
See Node.


T

10Base-T
Twisted-pair Ethernet connection, commonly used for wiring desktops to Ethernet hubs and switches to reduce costs.
100Base-T
Proposed standard for a 100 megabit per second LAN. 100Base-T would be completely compatible with the 10 Mbps 10Base-T, but would be 10 times as fast.
Time Service
Cluster Server resource that maintains consistent time across nodes in a cluster.


U

Uniform Memory Access (UMA)
Model where multiple processors share a common memory bus. All accesses to memory take the same length of time.
Universal Datagram Protocol (UDP)
Connectionless, unreliable transport service that is used by Microsoft for logon, browsing, and name resolution.


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.
Virtual circuit
Form of communicating where, when a transmission is complete, the transmitted information is guaranteed to be received by the intended recipient or an error is returned. Also, messages are delivered in order and are never duplicated.
Virtual server
Collection of services which gives the appearance of an actual Microsoft® Windows NT® Server network operating system to clients. A virtual server is typically a group containing all of the resources to run a particular application, such as a Network Name resource and an IP Address resource.


W

Windows Internet Name Service (WINS)
An enhanced NetBIOS Name Server (NBNS) designed by Microsoft to register NetBIOS computer names and resolve them to IP addresses for both local and remote hosts.
Windows Sockets 2
Network programming interface at the Transport Layer in the ISO reference model. Windows Sockets 2 is included with Microsoft® Windows NT® version 4.0.


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.