Partager via

Utilisation de bibliothèques dans votre programme

  • Article

Cette rubrique décrit certains éléments à prendre en compte lors de l’utilisation de bibliothèques dans votre programme.

Dans cette rubrique :

Vue d’ensemble de la programmation de bibliothèque

Les bibliothèques permettent aux utilisateurs d’organiser leur contenu basé sur les fichiers d’une manière qui leur soit pertinente et qui ne soit pas limitée par la organization du système de fichiers. Lorsque votre programme prend en charge les bibliothèques, il permet à l’utilisateur de trouver son contenu d’une manière qui lui convient tout en présentant une interface utilisateur cohérente avec l’expérience utilisateur de Windows 7. Les bibliothèques permettent également à votre programme de localiser plus facilement le contenu basé sur des fichiers stocké dans différents dossiers ou sur différentes machines.

Les rubriques de cette section décrivent comment ajouter la prise en charge des bibliothèques à votre programme et tirer parti des nouvelles fonctionnalités offertes par les bibliothèques. Windows 7 fournit une partie de cette prise en charge par défaut. Si votre programme ne modifie pas les boîtes de dialogue de fichier courantes qu’il utilise actuellement, il peut nécessiter très peu de programmation supplémentaire pour prendre en charge les bibliothèques.

Cette section décrit certaines des fonctionnalités clés fournies par les bibliothèques et comment les prendre en charge dans votre programme. Avec ces informations, vous pouvez décider quelles fonctionnalités offriront la meilleure expérience utilisateur de votre programme. Si votre programme personnalise les boîtes de dialogue de fichier courantes, les informations de cette section peuvent vous aider à déterminer comment utiliser les nouvelles boîtes de dialogue de fichier commun pour utiliser des bibliothèques et fournir des fonctionnalités équivalentes dans Windows 7.

Programmation avec des bibliothèques

Le modèle de programmation Windows Shell décrit comment un programme interagit avec les objets de programmation Windows Shell. Bien que les objets de système de fichiers, tels que les fichiers et les répertoires, soient représentés par des objets Windows Shell, tous les objets Windows Shell ne sont pas représentés par le système de fichiers. Les bibliothèques, par exemple, sont des objets Windows Shell qui n’ont pas d’équivalent de système de fichiers. L’utilisation d’objets Windows Shell dans votre programme permet à votre programme d’accéder à tous les objets Shell et pas seulement aux objets de système de fichiers.

Pour obtenir de meilleurs résultats, votre programme utilise l’API Bibliothèque Shell pour interagir avec les bibliothèques et accéder à leur contenu. Bien que les bibliothèques contiennent des éléments de système de fichiers tels que des dossiers et des fichiers, les bibliothèques ne sont pas des éléments de système de fichiers. Par conséquent, les API de système de fichiers ne peuvent pas être utilisées pour accéder aux fonctionnalités de bibliothèque ou au contenu de la bibliothèque.

Si vous avez un programme existant qui utilise actuellement de nombreuses API de système de fichiers, votre programme peut toujours tirer parti des fonctionnalités de bibliothèque. L’API bibliothèque shell peut fournir des références de système de fichiers aux éléments qui se trouvent dans une bibliothèque et ces références de système de fichiers, telles que le nom et le chemin d’accès, peuvent être passées aux API de système de fichiers existantes qui se trouvent dans votre programme existant.

Déplacement de dossiers connus vers des bibliothèques

Avant Windows 7, il était courant d’utiliser un dossier connu, tel que le dossier Mes documents, comme dossier par défaut dans les opérations d’enregistrement ou d’ouverture de fichier. Dans Windows 7, la bibliothèque correspondante doit être utilisée afin que l’utilisateur ait la même expérience dans votre programme qu’avec d’autres programmes Windows 7, tels que windows Explorer.

Si vous utilisez actuellement l’API Windows Shell dans votre programme, l’ajout de la prise en charge de la bibliothèque est simple. Par exemple, si vous appelez actuellement la fonction SHGetKnownFolderItem pour obtenir l’emplacement du dossier Mes documents, vous pouvez remplacer la valeur KNOWNFOLDERID du dossier Mes documents connus par la valeur KNOWNFOLDERID de la bibliothèque correspondante.

Le tableau suivant montre la relation entre les valeurs KNOWNFOLDERID des dossiers connus et la valeur KNOWNFOLDERID de la bibliothèque correspondante dans Windows 7.

Valeurs connues du dossier KNOWNFOLDERID Valeurs de la bibliothèque KNOWNFOLDERID
FOLDERID_Documents FOLDERID_DocumentsLibrary
FOLDERID_Pictures FOLDERID_PicturesLibrary
FOLDERID_Music FOLDERID_MusicLibrary
FOLDERID_RecordedTV FOLDERID_RecordedTVLibrary

 

Groupe résidentiel et bibliothèques partagées

L’ajout de la prise en charge des bibliothèques à votre programme permet de prendre en charge les bibliothèques partagées dans un groupe résidentiel. Le groupe résidentiel est identifié par sa valeur KNOWNFOLDERIDde FOLDERID_HomeGroup. Votre programme peut identifier l’emplacement d’enregistrement par défaut privé ou partagé de l’utilisateur en définissant la valeur DEFAULTSAVEFOLDERTYPE dans l’appel à la méthode IShellLibrary::GetDefaultSaveFolder .

Utilisation d’un fichier commun avec des bibliothèques

Utilisation d’une boîte de dialogue de fichier commun avec des bibliothèques La boîte de dialogue Fichier commun a été mise à jour pour prendre en charge les bibliothèques dans Windows 7. L’illustration suivante montre comment la boîte de dialogue de fichier commun s’affiche pour un utilisateur dans Windows 7.

capture d’écran de la boîte de dialogue de fichier commun montrant les bibliothèques

Dans Windows 7, si votre programme affiche actuellement une boîte de dialogue de fichier commune et ne modifie pas le modèle de boîte de dialogue ni ne connecte aucun de ses événements, il affiche automatiquement la nouvelle version de Windows 7 de la boîte de dialogue. Plus précisément, dans l’appel à la fonction de boîte de dialogue de fichier commun, les membres lpfnHook, hInstance et lpTemplatename de la structure OPENFILENAME doivent être NULL et les indicateurs OFN_ENABLEHOOK et OFN_ENABLETEMPLATE doivent être clairs.

Dans Windows 7, les interfaces liées à IFileDialog remplacent les fonctions de boîte de dialogue de fichier courantes utilisées dans les versions antérieures de Windows. Les fonctions de boîte de dialogue de fichiers communs antérieures sont toujours prises en charge dans Windows 7, mais elles ne fournissent pas l’expérience utilisateur complète de Windows 7 et ne prennent pas en charge les bibliothèques. Voici quelques-unes des nouvelles fonctionnalités prises en charge par les interfaces liées à IFileDialog :

  • L’utilisateur peut accéder aux propriétés de fichier prises en charge par l’Explorer Windows Windows 7 pour rechercher et sélectionner les fichiers.
  • Le programme peut utiliser des interfaces et des méthodes de l’API d’espace de noms Shell pour travailler avec les éléments.
  • Le programme peut utiliser un modèle de personnalisation piloté par les données au lieu d’un modèle de personnalisation piloté par les fichiers de ressources pour ajouter de nouveaux contrôles aux boîtes de dialogue de fichier courantes.

Vous devez utiliser les interfaces liées à IFileDialog dans les cas suivants :

  • vous devez personnaliser la boîte de dialogue de fichier commun pour votre programme dans Windows 7. Cela permettra à votre programme d’utiliser des bibliothèques et de prendre en charge la personnalisation de votre boîte de dialogue.
  • vous souhaitez que l’utilisateur puisse sélectionner plusieurs fichiers dans une boîte de dialogue de fichier commun. Cela garantit que vous obtenez les chemins d’accès corrects à l’objet sélectionné, car une bibliothèque peut avoir du contenu stocké dans différents dossiers.

Pour plus d’informations sur les interfaces liées à IFileDialog, consultez :

Activation de la sélection de bibliothèque à partir de l’interface utilisateur

Si votre programme permet à l’utilisateur de sélectionner un dossier, par exemple pour les fonctions d’importation ou d’exportation, dans Windows 7, il doit également lui permettre de sélectionner une bibliothèque. L’interface IFileOpenDialog et la fonction SHBrowseForFolder permettent à l’utilisateur de sélectionner une bibliothèque lorsqu’il est invité à sélectionner un dossier. L’interface IFileOpenDialog est préférable à la fonction SHBrowseForFolder , car IFileOpenDialog prend en charge l’interface utilisateur de Windows 7.

Pour permettre aux utilisateurs de sélectionner des dossiers lors de l’utilisation de l’interface IFileOpenDialog , appelez SetOptions avec l’indicateur FOS_PICKFOLDERS et vérifiez que l’indicateur FOS_FORCEFILESYSTEM est clair.

FILEOPENDIALOGOPTIONS fileOptions;

hr = fileOpenDialogBox->GetOptions(&fileOptions);
fileOptions = fileOptions | FOS_PICKFOLDERS | ~FOS_FORCEFILESYSTEM;
hr = fileOpenDialogBox->SetOptions(fileOptions);

Pour permettre aux utilisateurs de sélectionner des dossiers lors de l’appel de la fonction SHBrowseForFolder, dans le membre ulFlags de la structure BROWSEINFO , définissez l’indicateur BIF_USENEWUI et effacez l’indicateur BIF_RETURNONLYFSDIRS.

BROWSEINFO    browseInfo;
browseInfo.ulFlags = BIF_USENEWUI | ~BIF_RETURNONLYFSDIRS;
// Set other member values
pidl = SHBrowseForFolder(&browseInfo);

Accès au contenu de bibliothèque dans un programme

Pour accéder au contenu d’une bibliothèque, vous devez utiliser l’API Windows Shell. Les fonctions de l’API de système de fichiers ne peuvent pas être utilisées pour accéder au contenu de la bibliothèque, car les bibliothèques ne sont pas des objets de système de fichiers. Si votre programme utilise un navigateur de fichiers personnalisé basé sur l’API du système de fichiers, il ne pourra pas parcourir les bibliothèques ni accéder au contenu de la bibliothèque.

Cette section décrit comment accéder au contenu de la bibliothèque afin de sélectionner la meilleure façon de mettre à jour votre programme pour qu’il fonctionne avec des bibliothèques.

Accès au contenu de la bibliothèque avec l’interface IShellLibrary

Le moyen le plus simple pour un programme d’accéder au contenu de la bibliothèque consiste à utiliser l’API De la bibliothèque shell. Si vous travaillez sur un programme qui utilise l’API de système de fichiers, l’API bibliothèque shell peut retourner les dossiers de système de fichiers d’une bibliothèque, ce qui réduit la modification du code de votre programme existant.

IShellLibrary *picturesLibrary;

hr = SHLoadLibraryFromKnownFolder(FOLDERID_PicturesLibrary, 
                                  STGM_READ, 
                                  IID_PPV_ARGS(&picturesLibrary));

// picturesLibrary now points to the user's picture library
    
IShellItemArray *pictureFolders; 

hr = pslLibrary->GetFolders(LFF_FORCEFILESYSTEM, IID_PPV_ARGS(&pictureFolders));

// pictureFolders now contains an array of Shell items that
// represent the folders found in the user's pictures library

Accès au contenu de la bibliothèque avec les API Shell

Étant donné que les objets de bibliothèque font partie du modèle de programmation Shell, ils peuvent être utilisés avec d’autres API Windows Shell. Par exemple, vous pouvez utiliser les interfaces IShellItem et IShellFolder dans votre programme, ainsi que les fonctions d’assistance associées, pour accéder au contenu d’une bibliothèque de la même façon que vous énumériez les dossiers et le contenu des dossiers pour accéder au contenu avec les API du système de fichiers.

Les API Windows Shell prennent en charge deux modes d’énumération pour accéder au contenu d’une bibliothèque :

  • Parcourir l’énumération

    Parcourir l’énumération est le mode d’énumération par défaut et énumère le contenu d’un dossier de bibliothèque. Désactivez l’indicateur SHCONTF_NAVIGATION_ENUM pour utiliser ce mode.

  • Énumération de navigation

    L’énumération de navigation énumère les dossiers de bibliothèque. Définissez l’indicateur SHCONTF_NAVIGATION_ENUM pour utiliser ce mode.

Si votre programme utilise un contrôle d’arborescence personnalisé pour parcourir les dossiers de l’utilisateur, l’énumération des dossiers en mode d’énumération de navigation vous donne une liste des dossiers d’une bibliothèque qui est cohérente avec la façon dont windows Explorer énumère les dossiers dans Windows 7.

Pour obtenir des exemples d’utilisation de ces fonctionnalités dans un programme, consultez l’exemple ShellStorage dans le Kit de développement logiciel (SDK) Windows.

Enregistrement du contenu utilisateur dans une bibliothèque

Votre programme peut enregistrer le contenu utilisateur dans une bibliothèque ainsi que dans un dossier de la bibliothèque. De même, l’utilisateur peut enregistrer dans un dossier spécifique d’une bibliothèque ou simplement enregistrer dans la bibliothèque.

Chaque bibliothèque a un dossier désigné comme emplacement d’enregistrement par défaut. L’emplacement d’enregistrement par défaut est défini lors de la création de la bibliothèque ; Toutefois, l’utilisateur peut réaffecter l’emplacement d’enregistrement par défaut à n’importe quel dossier de la bibliothèque. Bien que l’utilisateur n’ait pas besoin de configurer un emplacement d’enregistrement par défaut, il a la possibilité de le modifier. Si l’utilisateur supprime le dossier actuellement défini comme emplacement d’enregistrement par défaut, la bibliothèque configure automatiquement le dossier suivant dans la bibliothèque pour qu’il soit l’emplacement d’enregistrement par défaut.

Il existe plusieurs façons d’enregistrer le contenu utilisateur dans une bibliothèque.

  • Shell API

    Si vous utilisez le modèle de programmation Shell et que vous enregistrez un élément Shell, tel que représenté par un IShellItem, IStorage ou IStream, dans un objet de bibliothèque, l’élément Shell est automatiquement stocké à l’emplacement d’enregistrement par défaut de la bibliothèque.

  • API de système de fichiers

    Si vous avez un programme existant qui utilise de nombreux appels d’API de système de fichiers, vous pouvez obtenir un chemin d’accès au dossier défini comme emplacement d’enregistrement par défaut de la bibliothèque. Le chemin d’accès au dossier peut ensuite être passé à une API de système de fichiers.

Pour obtenir des exemples d’utilisation de ces fonctionnalités dans un programme, consultez l’exemple ShellStorage dans le Kit de développement logiciel (SDK) Windows.

Prise en charge des opérations de glisser-déplacer dans une bibliothèque

Si votre programme prend en charge les actions glisser-déplacer, celles-ci doivent être mises à jour pour prendre en charge l’interaction correcte de la bibliothèque. Si un fichier est supprimé dans une bibliothèque, le fichier supprimé doit être enregistré à l’emplacement d’enregistrement par défaut. Si un dossier est déposé dans une bibliothèque, le dossier supprimé doit être ajouté en tant que nouveau dossier à la bibliothèque. Si un fichier est supprimé dans un dossier existant qui n’est pas l’emplacement d’enregistrement par défaut, le fichier doit être ajouté au dossier sélectionné.

Pour obtenir des exemples d’ajout de la prise en charge des bibliothèques pour la fonctionnalité glisser-déplacer de vos programmes, consultez l’exemple ShellLibraryCommandLine dans le Kit de développement logiciel (SDK) Windows.

Synchronisation avec une bibliothèque

Cette rubrique décrit comment un programme peut maintenir à jour sa vue du contenu d’une bibliothèque.

Mise à jour en bloc

Étant donné que l’utilisateur peut modifier les dossiers d’une bibliothèque de manière interactive lorsque votre programme n’est pas en cours d’exécution, il doit appeler SHResolveLibrary lorsqu’il commence à découvrir et à stocker les modifications apportées à la bibliothèque. L’API Shell fournit la fonction SHResolveLibrary pour permettre à un programme d’obtenir le contenu actuel d’une bibliothèque et les emplacements actuels des dossiers qu’elle peut contenir.

Notez que SHResolveLibrary est une fonction bloquante qui peut prendre beaucoup de temps à retourner en fonction de ce qui a changé dans la bibliothèque. Par conséquent, il ne doit pas être appelé à partir d’un thread d’interface utilisateur.

Une fois le programme mis à jour, il peut s’inscrire aux notifications de modification afin de conserver une vue actuelle.

Notification de l’API Shell

L’API De l’interpréteur de commandes Windows fournit la fonction SHChangeNotifyRegister , qui est le moyen préféré pour les processus hors service d’être avertis d’un changement dans la bibliothèque.

Pour détecter les modifications apportées aux éléments d’une bibliothèque à l’aide de l’API Windows Shell, appelez SHChangeNotifyRegister pour inscrire votre programme pour recevoir des notifications de modifications apportées aux éléments d’un dossier de bibliothèque. Cette fonction peut avertir votre programme s’il y a un changement dans une bibliothèque ou simplement dans une bibliothèque spécifique. Les notifications sont envoyées immédiatement lorsqu’une bibliothèque est modifiée.

Notification de l’API du système de fichiers

Les notifications de système de fichiers doivent être utilisées dans les processus de service.

Pour détecter les modifications apportées aux éléments d’une bibliothèque à l’aide de l’API de système de fichiers, énumérez les dossiers dans la bibliothèque et appelez FindFirstChangeNotification pour chaque dossier à surveiller. Votre programme reçoit une notification lorsqu’un dossier surveillé change. Pour rechercher le fichier spécifique des fichiers modifiés dans le dossier, appelez ReadDirectoryChangesW. Pour détecter les modifications apportées au fichier de description de la bibliothèque, surveillez le dossier qui le contient. Le fichier de description de la bibliothèque se trouve dans le dossier FOLDERID_Libraries . Toutefois, le fichier de description de la bibliothèque ne doit pas être ouvert ou modifié.

À propos des bibliothèques

IShellLibrary

Liens de l’interpréteur de commande

Dossiers connus

Schéma de description de la bibliothèque

IID_PPV_ARGS