Méthode CVssWriterEx ::InitializeEx (vswriter.h)
Initialise un objet CVssWriterEx et permet à une application writer d’interagir avec VSS. Contrairement à la méthode Initialize , la méthode InitializeEx permet à l’appelant de spécifier des informations sur la version de l’enregistreur.
InitializeEx est une méthode publique implémentée par la classe de base CVssWriterEx .
Les rédacteurs doivent appeler Initialize ou InitializeEx, mais pas les deux.
Syntaxe
HRESULT InitializeEx(
[in] VSS_ID WriterId,
[in] LPCWSTR wszWriterName,
[in] DWORD dwMajorVersion,
[in] DWORD dwMinorVersion,
[in] VSS_USAGE_TYPE ut,
[in] VSS_SOURCE_TYPE st,
[in] VSS_APPLICATION_LEVEL nLevel,
[in] DWORD dwTimeoutFreeze,
[in] VSS_ALTERNATE_WRITER_STATE aws,
[in] bool bIOThrottlingOnly,
[in] LPCWSTR wszWriterInstanceName
);
Paramètres
[in] WriterId
Identificateur global unique (GUID) de la classe writer.
[in] wszWriterName
Chaîne de caractères larges terminée par null qui contient le nom de l’enregistreur. Cette chaîne n’est pas localisée.
[in] dwMajorVersion
Version principale de l’application writer. Pour plus d'informations, consultez la section Notes.
[in] dwMinorVersion
Version mineure de l’application writer. Pour plus d'informations, consultez la section Notes.
[in] ut
Valeur d’énumération VSS_USAGE_TYPE qui indique comment les données gérées par l’enregistreur sont utilisées sur le système hôte.
[in] st
Valeur d’énumération VSS_SOURCE_TYPE qui indique le type de données géré par l’enregistreur.
[in] nLevel
Valeur d’énumération VSS_APPLICATION_LEVEL qui indique le niveau de l’application auquel l’enregistreur reçoit une notification d’événement Freeze .
La valeur par défaut de ce paramètre est VSS_APP_FRONT_END.
[in] dwTimeoutFreeze
Durée maximale autorisée, en millisecondes, entre la réception par l’enregistreur d’une notification d’événement Freeze et la réception d’une notification d’événement de dégel correspondante de VSS. Une fois le délai d’expiration expiré, la méthode OnAbort de l’enregistreur est appelée automatiquement.
La valeur par défaut de ce paramètre est 60000.
[in] aws
Valeur d’énumération VSS_ALTERNATE_WRITER_STATE qui indique si l’enregistreur a un autre writer associé.
La valeur par défaut de ce paramètre est VSS_AWS_NO_ALTERNATE_WRITER. L’appelant ne doit pas remplacer cette valeur par défaut. Ce paramètre est réservé à un usage futur.
[in] bIOThrottlingOnly
Définissez ce paramètre sur true si les méthodes de limitation d’E/S sont activées, ou false dans le cas contraire.
La valeur par défaut de ce paramètre est false. L’appelant ne doit pas remplacer cette valeur par défaut. Ce paramètre est réservé à un usage futur.
[in] wszWriterInstanceName
Chaîne de caractères larges terminée par null qui contient le nom instance writer.
La valeur par défaut de ce paramètre est NULL. Si l’enregistreur a plusieurs instances et nécessite des événements de restauration, ce paramètre est obligatoire et ne peut pas être NULL. Pour plus d'informations, consultez la section Notes qui suit.
Valeur retournée
Voici les codes de retour valides pour cette méthode.
| Valeur | Signification |
|---|---|
|
L’objet writer a été correctement initialisé. |
|
Impossible d’initialiser l’objet writer ; l’infrastructure de l’enregistreur VSS était inactive, car Windows était en mode sans échec ou était configuré. |
|
L’appelant n’est pas un administrateur. |
|
L’une des valeurs de paramètre n’est pas valide. |
|
L’appelant n’a plus de mémoire ou d’autres ressources système. |
|
Erreur inattendue. Le code d’erreur est enregistré dans le fichier journal des erreurs. Pour plus d’informations, consultez Gestion des événements et des erreurs sous VSS.
Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Cette valeur n’est pas prise en charge tant que Windows Server 2008 R2 et Windows 7. E_UNEXPECTED est utilisé à la place. |
Remarques
La méthode InitializeEx est identique à la méthode Initialize à l’exception des paramètres dwMajorVersion et dwMinorVersion . Si l’enregistreur utilise Initialize au lieu d’InitializeEx, la version de l’enregistreur est signalée comme 0.0 (version majeure = 0, version mineure = 0) par la méthode IVssExamineWriterMetadataEx2 ::GetVersion .
Les paramètres dwMajorVersion et dwMinorVersion sont utilisés pour spécifier les numéros de version majeure et secondaire de l’enregistreur conformément aux conventions VSS suivantes :
- Si l’enregistreur a changé depuis Windows XP ou s’il est nouveau pour Windows Vista, il doit spécifier la version 1.0 ou une version ultérieure pour son numéro de version.
- Le numéro de version mineure d’un writer doit être incrémenté d’un chaque fois qu’une version publiée de l’enregistreur contient des modifications mineures qui affectent l’interaction de l’enregistreur avec les demandeurs. Par exemple, une correction d’une spécification de fichier dans un QFE ou un Service Pack writer justifierait l’incrémentation du numéro de version mineure. Toutefois, une modification entre les versions bêta ou release candidate d’un writer ne justifierait pas la modification du numéro de version mineure.
- Le numéro de version principale d’un writer doit être incrémenté d’un chaque fois qu’une version publiée de l’enregistreur contient une modification significative. Par exemple, si les données sauvegardées avec une nouvelle version d’un writer ne peuvent pas être restaurées à l’aide de la version précédente de l’enregistreur, le numéro de version principale du nouvel enregistreur doit être incrémenté.
- Chaque fois que le numéro de version principale est incrémenté, le numéro de version secondaire doit être réinitialisé à zéro.
VSS affecte un id de instance d’enregistreur unique à chaque instance d’une application writer. Si plusieurs instance sont présents sur le système en même temps (par exemple, si plusieurs serveurs SQL s’exécutent sur un système), chaque enregistreur est identifié de manière unique par la combinaison de son ID de classe writer et de son ID de instance writer.
Le paramètre wszWriterInstanceName permet à un enregistreur multi-instance de spécifier un nom persistant pour chaque writer instance sous la forme d’une chaîne lisible par l’homme. Ce nom doit être unique dans toutes les instances de l’enregistreur sur le système. Si un writer a plusieurs instances et nécessite des événements de restauration, il doit spécifier une chaîne non NULL pour ce paramètre. VSS utilise le nom instance pour restaurer correctement les enregistreurs multi-instance.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | vswriter.h (inclure Vss.h, VsWriter.h) |
| Bibliothèque | VssApi.lib |