FilterAttachAtAltitude, fonction (fltuser.h)
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\ »
[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 |
|---|---|
|
Une instance existe déjà à cette altitude sur le volume spécifié. |
|
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 |