Fonction DsBackupPrepare

Article
06/13/2023

[Cette fonction est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. À partir de Windows Vista, utilisez plutôt le service VSS (Volume Shadow Copy Service ).

La fonction DsBackupPrepare prépare le répertoire sur le serveur spécifié pour la sauvegarde en ligne et retourne un handle de contexte de sauvegarde utilisé dans les appels suivants à d’autres fonctions de sauvegarde.

Syntaxe

HRESULT DsBackupPrepare(
  _In_  LPCTSTR szBackupServer,
  _In_  ULONG   grbit,
  _In_  ULONG   btBackupType,
  _Out_ PVOID   *ppvExpiryToken,
  _Out_ LPDWORD pcbExpiryTokenSize,
  _Out_ HBC     *phbc
);

Paramètres

szBackupServer [in]: Pointeur vers une chaîne terminée par null qui contient le nom du serveur à sauvegarder. Les barres obliques inverses précédentes sont facultatives. Le serveur doit être le même ordinateur à partir duquel cette fonction est appelée. Le nom du serveur ne peut pas contenir un caractère de soulignement (_). Un exemple de nom de serveur est « \\server1 ».
grbit [in]: Détermine si les fichiers journaux seront sauvegardés. Cette valeur doit toujours être 0, car les sauvegardes incrémentielles ne sont pas prises en charge.
btBackupType [in]: Spécifie le type de sauvegarde. Il peut s’agir de l’une des valeurs suivantes.
BACKUP_TYPE_FULL: Spécifie une sauvegarde complète. Le répertoire complet (DIT, fichiers journaux et fichiers de mise à jour) est sauvegardé. Toutes les données sont sauvegardées et les fichiers journaux des transactions sont tronqués. Seules les sauvegardes complètes sont prises en charge.
BACKUP_TYPE_LOGS_ONLY: Cette valeur n’est pas prise en charge. Spécifie que seuls les journaux de base de données, et non la base de données elle-même, seront sauvegardés. Il est normalement utilisé lors de l’exécution d’une sauvegarde différentielle ou incrémentielle.
BACKUP_TYPE_INCREMENTAL: Cette valeur n’est pas prise en charge. DsBackupPrepare retourne ERROR_INVALID_PARAMETER.

ppvExpiryToken [out]

Pointeur vers une valeur PVOID qui reçoit un pointeur vers un jeton d’expiration associé à cette sauvegarde. pcbExpiryTokenSize reçoit la taille, en octets, de ces données. L’appelant doit enregistrer le contenu de ce jeton avec la sauvegarde, car le jeton doit être passé à DsRestorePrepare lors de la tentative de restauration des données. Une fois le jeton stocké et n’est plus nécessaire, l’appelant doit libérer la mémoire allouée à l’aide de DsBackupFree.

pcbExpiryTokenSize [out]

Pointeur vers une valeur DWORD qui reçoit la taille, en octets, du jeton dans ppvExpiryToken.

phbc [out]

Pointeur vers une valeur HBC qui reçoit le handle pour la sauvegarde. Ce handle est utilisé lors de l’appel d’autres fonctions de sauvegarde du service d’annuaire, telles que DsBackupOpenFile et DsBackupEnd.

Valeur retournée

Retourne S_OK si la fonction réussit ou si un code d’erreur est contraire. La liste suivante répertorie d’autres codes d’erreur possibles.

ERROR_ACCESS_DENIED: L’appelant ne dispose pas des privilèges d’accès appropriés pour appeler cette fonction. La fonction DsSetAuthIdentity peut être utilisée pour définir les informations d’identification à utiliser pour les fonctions de sauvegarde et de restauration.
ERROR_INVALID_PARAMETER: szBackupServer ou phbcBackupContext ne sont pas valides.
ERROR_NOT_ENOUGH_MEMORY: Un échec d’allocation de mémoire s’est produit.
hrCouldNotConnect: Le serveur dans szBackupServer est introuvable, n’est pas un contrôleur de domaine ou szBackupServer n’est pas mis en forme correctement. Cette valeur est définie dans ntdsbmsg.h.
hrInvalidParam: ppvExpiryToken et/ou pcbExpiryTokenSize ne sont pas valides. Cette valeur est définie dans Ntdsbmsg.h.
RPC_S_INVALID_BINDING: La fonction est appelée à distance ou le serveur dans szServerName n’est pas un contrôleur de domaine.

Notes

Cette fonction nécessite que l’appelant dispose du privilège SE_BACKUP_NAME . La fonction DsSetAuthIdentity peut être utilisée pour modifier le contexte de sécurité dans lequel cette fonction est appelée.

Spécifications

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
En-tête	Ntdsbcli.h
Bibliothèque	Ntdsbcli.lib
DLL	Ntdsbcli.dll
Noms Unicode et ANSI	DsBackupPrepareW (Unicode) et DsBackupPrepareA (ANSI)

Voir aussi

DsRestorePrepare
DsBackupFree
DsBackupOpenFile
DsBackupEnd
DsSetAuthIdentity
Sauvegarde d’un serveur Active Directory
Fonctions de sauvegarde d’annuaire

Partager via