FilterAttachAtAltitude, fonction (fltuser.h)

  • Article

La fonction FilterAttachAtAltitude est une fonction de prise en charge du débogage qui attache un nouveau minifiltre instance à un volume à une altitude spécifiée, en remplaçant tous les paramètres du fichier INF (Informations d’installation) du minifilter.

Syntaxe

HRESULT FilterAttachAtAltitude(
  [in]            LPCWSTR lpFilterName,
  [in]            LPCWSTR lpVolumeName,
  [in]            LPCWSTR lpAltitude,
  [in, optional]  LPCWSTR lpInstanceName,
  [in, optional]  DWORD   dwCreatedInstanceNameLength,
  [out, optional] LPWSTR  lpCreatedInstanceName
);

Paramètres

[in] lpFilterName

Pointeur vers une chaîne de caractères larges terminée par null contenant le nom du minifiltre pour lequel une instance doit être créée. Ce paramètre est obligatoire et ne peut pas être NULL.

[in] lpVolumeName

Pointeur vers une chaîne de caractères larges terminée par un caractère null contenant le nom du volume auquel le instance nouvellement créé doit être attaché.

La chaîne d’entrée lpVolumeName peut être l’une des valeurs suivantes. La barre oblique inverse de fin (\) est facultative.

  • Une lettre de lecteur, telle que « D:\ »
  • Chemin d’accès à un point de montage de volume, tel que « c:\mnt\edrive\ »
  • Un identificateur de volume unique (également appelé nom GUID de volume), tel que « \ ? » \Volume{7603f260-142a-11d4-ac67-806d6172696f}\ »
  • Un nom d’appareil non persistant (également appelé nom de cible ou nom d’appareil NT), tel que « \Device\HarddiskVolume1\ »
Ce paramètre est obligatoire et ne peut pas être NULL.

[in] lpAltitude

Pointeur vers une chaîne de caractères larges terminée par null qui contient une valeur numérique spécifiant la position cible que le minifiltre instance doit occuper dans la pile du volume. Plus le nombre est élevé, plus la position relative dans la pile est élevée. Une chaîne d’altitude se compose d’un ou plusieurs chiffres dans la plage comprise entre 0 et 9, et elle peut inclure une seule virgule décimale. La virgule décimale est facultative. Par exemple, « 100.123456 » est une chaîne d’altitude valide. Ce paramètre est obligatoire et ne peut pas être NULL.

[in, optional] lpInstanceName

Pointeur vers une chaîne de caractères larges terminée par null contenant le nom instance de la nouvelle instance. Ce paramètre est facultatif et peut être NULL. Si ce paramètre a la valeur NULL, le nouveau instance reçoit le nom de instance par défaut du minifilter, comme décrit dans la section Remarques pour FltAttachVolume.

[in, optional] dwCreatedInstanceNameLength

Longueur, en octets, de la mémoire tampon vers laquelle lpCreatedInstanceName pointe. Ce paramètre est facultatif et peut être égal à zéro.

[out, optional] lpCreatedInstanceName

Pointeur vers une variable allouée par l’appelant qui reçoit le nom de instance de la nouvelle instance si le instance est correctement attaché au volume. Ce paramètre est facultatif et peut être NULL. S’il n’est pas NULL, la mémoire tampon doit être suffisamment grande pour contenir INSTANCE_NAME_MAX_CHARS caractères plus une marque de fin NULL.

Valeur retournée

FilterAttachAtAltitude retourne S_OK en cas de réussite. Sinon, elle retourne une valeur d’erreur telle que l’une des valeurs suivantes.

Code de retour Description
ERROR_FLT_INSTANCE_ALTITUDE_COLLISION
 Une instance existe déjà à cette altitude sur le volume spécifié.
ERROR_FLT_INSTANCE_NAME_COLLISION
 Une instance existe déjà avec ce nom sur le volume spécifié.

Notes

Une application doit uniquement utiliser FilterAttachAtAltitude pour le débogage. Il ne doit pas appeler cette fonction dans une version commerciale de l’application.

FilterAttachAtAltitude est l’équivalent Win32 de FltAttachVolumeAtAltitude.

Le terme « altitude » fait référence à la position qu’un instance occupe (ou doit occuper) dans le minifiltre instance pile d’un volume. Plus l’altitude est élevée, plus le instance est éloigné du système de fichiers de base dans la pile. Une seule instance peut être attachée à une altitude donnée sur un volume donné.

L’altitude est spécifiée par une chaîne d’altitude, qui est un tableau de caractères larges contenant un ou plusieurs chiffres décimaux dans la plage comprise entre 0 et 9, et elle peut inclure une seule virgule décimale. La virgule décimale est facultative. Par exemple, « 100.123456 » et « 03333 » sont des chaînes d’altitude valides.

La chaîne « 03333 » représente une altitude supérieure à « 100.123456 ». (Les zéros de début et de fin sont ignorés.) En d’autres termes, un instance dont l’altitude est « 03333 » est plus éloigné du système de fichiers de base qu’un instance dont l’altitude est « 100,123456 ». Toutefois, cette comparaison n’est significative que si les deux instances sont attachées au même volume.

Le nom instance retourné dans lpCreatedInstanceName est unique dans le système.

Pour détacher un minifiltre instance d’un volume, appelez FilterDetach.

Spécifications

   
Plateforme cible Universal
En-tête fltuser.h (inclure Fltuser.h)
Bibliothèque FltLib.lib
DLL FltLib.dll

Voir aussi

FilterAttach

FilterDetach

FltAttachVolumeAtAltitude