Fonction MoveClusterGroupEx (clusapi.h)

Étend la méthode MoveClusterGroup existante avec l’ajout d’indicateurs et d’une mémoire tampon. Les indicateurs contrôlent le comportement de la stratégie de basculement de cluster, et la mémoire tampon d’entrée permet au client d’envoyer des instructions spéciales aux ressources du groupe.

Syntaxe

DWORD MoveClusterGroupEx(
  [in]           HGROUP hGroup,
  [in, optional] HNODE  hDestinationNode,
  [in]           DWORD  dwMoveFlags,
  [in, optional] PBYTE  lpInBuffer,
  [in]           DWORD  cbInBufferSize
);

Paramètres

[in] hGroup

Handle d’un groupe de clusters.

[in, optional] hDestinationNode

Handle vers un nœud de cluster, indiquant le nœud vers lequel le groupe doit être déplacé. Ce paramètre est facultatif. S’il est laissé sur null, le cluster déplace le groupe vers le nœud le plus approprié, conformément aux stratégies de basculement configurées pour le cluster et pour ce groupe particulier.

[in] dwMoveFlags

Combinaison au niveau du bit des indicateurs qui influencent la stratégie de basculement en ce qui concerne cette opération de déplacement.

CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS (0x00000001)

Force le déplacement du groupe même si une ressource a indiqué qu’elle doit être « verrouillée » dans son état actuel sur le nœud actuel et arrête la ressource si nécessaire.

CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR (0x00000002)

Si le groupe ne parvient pas à atteindre son état persistant sur le nœud de destination (qu’il soit spécifié avec hDestinationNode ou choisi par le cluster), retourne le groupe au nœud source et l’amène à son état persistant.

CLUSAPI_GROUP_MOVE_QUEUE_ENABLED (0x00000004)

Si une DLL de ressource dans le groupe indique que le déplacement n’est pas possible pour le moment, mais qu’il peut l’être dans un avenir proche, met en file d’attente ce déplacement dans le service de cluster et continue de réessayer, lorsqu’il le juge approprié, jusqu’à ce que l’opération de déplacement se termine ou soit annulée par le client.

CLUSAPI_GROUP_MOVE_HIGH_PRIORITY_START (0x00000008)

Amène ce groupe à son état persistant sur le nœud de destination dès que possible, sans tenir compte des stratégies spécifiques à l’implémentation qui régissent l’ordre et/ou la hiérarchisation des groupes à leur état persistant.

CLUSAPI_GROUP_MOVE_FAILBACK (0x00000010)

Réservé.

[in, optional] lpInBuffer

Liste de propriétés qui contient des instructions d’opération de déplacement pour des ressources spécifiques au sein du groupe. Les instructions sont contenues dans les valeurs de propriété. Les ressources du groupe recherchent dans la liste des propriétés les noms de propriétés qu’elles prennent en charge pour les opérations de déplacement, puis interprètent les instructions de la valeur de propriété associée. Les propriétés prises en charge par une ressource dans une opération MoveClusterGroupEx ne sont pas liées aux propriétés privées associées à une ressource.

[in] cbInBufferSize

Taille de lpInBuffer, en octets.

Valeur retournée

MoveClusterGroupEx retourne ERROR_IO_PENDING si la commande move a été acceptée et est en cours. MoveClusterGroupEx retourne un code d’erreur différent de zéro si la commande move a été rejetée immédiatement sans aucune modification de l’état du groupe. Par instance, cela se produit si hDestinationNode n’est pas up au moment de la demande de déplacement.

Remarques

MoveClusterGroupEx échoue immédiatement avec l’erreur ERROR_CLUSTER_RESOURCE_LOCKED_STATUS si l’indicateur CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS n’est pas défini et qu’une ressource du groupe est en ligne et a indiqué qu’elle est « verrouillée » dans son état actuel.

Une fois que MoveClusterGroupEx a retourné ERROR_IO_PENDING, il existe un certain nombre de résultats possibles, notamment :

• L’opération de déplacement peut réussir et le groupe peut atteindre son état persistant sur le nœud cible.
• L’opération de déplacement peut échouer, dans la mesure où le groupe ne peut pas atteindre son état persistant sur le nœud cible. Si dwMoveFlags n’inclut pas CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR, le cluster prendra les mesures appropriées (conformément aux stratégies configurées) pour amener le groupe à son état persistant, peut-être sur d’autres nœuds du cluster. Si dwMoveFlags inclut CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR, le cluster tente d’amener le groupe à son état persistant sur le nœud source. En cas d’échec, le cluster prendra les mesures appropriées (selon les stratégies configurées) pour amener le groupe à son état persistant, peut-être sur d’autres nœuds du cluster.
• L’opération de déplacement peut être mise en file d’attente si une ressource indique qu’elle ne peut pas se déplacer immédiatement et que l’indicateur CLUSAPI_GROUP_MOVE_QUEUE_ENABLED est défini.
• L’opération de déplacement peut être rejetée par une ressource du groupe, ce qui ramène le groupe à son état persistant sur le nœud source sans incrémenter le nombre d’échecs ou déclencher des stratégies d’échec. Cela ne peut pas se produire si l’indicateur CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS est défini.

Pour une migration dynamique d’une machine virtuelle, procédez comme suit :

1. Dans le paramètre dwMoveFlags , définissez les indicateurs CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR, CLUSAPI_GROUP_MOVE_QUEUE_ENABLED et CLUSAPI_GROUP_MOVE_HIGH_PRIORITY_START .
2. Dans le paramètre lpInBuffer , ajoutez à la liste de propriétés un type de ressource nommé « Machine virtuelle » ou « Configuration de machine virtuelle » qui spécifie une valeur d’énumération CLUSTER_PROPERTY_FORMAT de CLUSPROP_FORMAT_DWORD (qui représente le format de données de la propriété) et une valeur de propriété de VmResdllContextLiveMigration (à partir de l’énumération VM_RESDLL_CONTEXT d’actions de machine virtuelle possibles).

MoveClusterGroupEx exige que le client bénéficie d’un accès complet dans le descripteur de sécurité du cluster.

Exemples

#include "stdafx.h"
#include <windows.h>
#include <stdio.h>
#include <ClusAPI.h>


#define DemoResDllTypeName L"dummy"
#define DemoGroupName L"DemoGroup"


int __cdecl main( void )
{
    HCLUSTER hCluster= NULL;
    HGROUP hGroup = NULL;
    DWORD error = 0;

    hCluster = OpenCluster( NULL );
    if ( hCluster == NULL )
    {
        error = GetLastError();
        wprintf( L"Failed to open cluster: 0x%x\n", error );
        goto Cleanup;
    }

    hGroup = OpenClusterGroup( hCluster, DemoGroupName );
    if ( hGroup == NULL )
    {
        error = GetLastError();
        wprintf( L"Failed to open cluster group " DemoGroupName L": 0x%x\n", error );
        goto Cleanup;
    }


    // Move Group example
    error = MoveClusterGroupEx( hGroup,
                                NULL,
                                CLUSAPI_GROUP_MOVE_RETURN_TO_SOURCE_NODE_ON_ERROR | CLUSAPI_GROUP_MOVE_IGNORE_RESOURCE_STATUS,
                                NULL,
                                0);

    if ( error == ERROR_IO_PENDING  )
    {
        wprintf( L"Group move pending" DemoGroupName L": 0x%x\n", error );
        error = ERROR_SUCCESS;
    }
    else if ( error != ERROR_SUCCESS)
    {
        wprintf( L"Failed to move group" DemoGroupName L": 0x%x\n", error );
    }
    else 
    {
        wprintf( L"Group move completed" DemoGroupName L": 0x%x\n");
    }

Cleanup:

    if ( hGroup != NULL )
    {
        CloseClusterGroup( hGroup );
        hGroup = NULL;
    }
    if ( hCluster != NULL )
    {
        CloseCluster( hCluster );
        hCluster = NULL;
    }

    return (int)error;
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Aucun pris en charge
Serveur minimal pris en charge	Windows Server 2012
Plateforme cible	Windows
En-tête	clusapi.h
Bibliothèque	ClusAPI.lib
DLL	ClusAPI.dll