Partager via

fonction mmioOpen (mmiscapi.h)

  • Article

La fonction mmioOpen ouvre un fichier pour les E/S sans tampon ou mises en mémoire tampon ; crée un fichier ; supprime un fichier ; ou vérifie si un fichier existe. Le fichier peut être un fichier standard, un fichier mémoire ou un élément d’un système de stockage personnalisé. Le handle retourné par mmioOpen n’est pas un handle de fichier standard ; ne l’utilisez pas avec des fonctions d’E/S de fichier autres que les fonctions d’E/S de fichier multimédia.

Note Cette fonction est déconseillée. Les applications doivent appeler CreateFile pour créer ou ouvrir des fichiers.
 

Syntaxe

HMMIO mmioOpen(
  LPSTR      pszFileName,
  LPMMIOINFO pmmioinfo,
  DWORD      fdwOpen
);

Paramètres

pszFileName

Pointeur vers une mémoire tampon qui contient le nom du fichier. Si aucune procédure d’E/S n’est spécifiée pour ouvrir le fichier, le nom du fichier détermine comment le fichier est ouvert, comme suit :

  • Si le nom de fichier ne contient pas de signe plus (+), il est supposé être le nom d’un fichier standard (autrement dit, un fichier dont le type n’est pas HMMIO).
  • Si le nom de fichier est de la forme EXAMPLE. EXT+ABC, l’extension EXT est supposée identifier une procédure d’E/S installée qui est appelée pour effectuer des E/S sur le fichier. Pour plus d’informations, consultez mmioInstallIOProc.
  • Si le nom de fichier est NULL et qu’aucune procédure d’E/S n’est donnée, le membre adwInfo de la structure MMIOINFO est supposé être le handle de fichier standard (non-HMMIO) d’un fichier actuellement ouvert.
Le nom de fichier ne doit pas comporter plus de 128 caractères, y compris le caractère NULL de fin.

Lors de l’ouverture d’un fichier mémoire, définissez szFilename sur NULL.

pmmioinfo

Pointeur vers une structure MMIOINFO contenant des paramètres supplémentaires utilisés par mmioOpen. À moins d’ouvrir un fichier mémoire, de spécifier la taille d’une mémoire tampon pour les E/S mises en mémoire tampon ou de spécifier une procédure d’E/S désinstallée pour ouvrir un fichier, ce paramètre doit avoir la valeur NULL. Si ce paramètre n’est pas NULL, tous les membres inutilisés de la structure MMIOINFO qu’il référence doivent être définis sur zéro, y compris les membres réservés.

fdwOpen

Indicateurs pour l’opération d’ouverture. Les indicateurs MMIO_READ, MMIO_WRITE et MMIO_READWRITE s’excluent mutuellement . Un seul indicateur doit être spécifié. Les indicateurs MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD et MMIO_DENYNONE sont des indicateurs de partage de fichiers. Les valeurs suivantes sont définies.

Valeur Signification
MMIO_ALLOCBUF Ouvre un fichier pour les E/S mises en mémoire tampon. Pour allouer une mémoire tampon supérieure ou inférieure à la taille de mémoire tampon par défaut (8 Ko, définie comme MMIO_DEFAULTBUFFER), définissez le membre cchBuffer de la structure MMIOINFO sur la taille de mémoire tampon souhaitée. Si cchBuffer est égal à zéro, la taille de mémoire tampon par défaut est utilisée. Si vous fournissez votre propre mémoire tampon d’E/S, cet indicateur ne doit pas être utilisé.
MMIO_COMPAT Ouvre le fichier en mode de compatibilité, ce qui permet à n’importe quel processus sur un ordinateur donné d’ouvrir le fichier un nombre quelconque de fois. Si le fichier a été ouvert avec l’un des autres modes de partage, mmioOpen échoue.
MMIO_CREATE Crée un nouveau fichier. Si le fichier existe déjà, il est tronqué à la longueur nulle. Pour les fichiers mémoire, cet indicateur indique que la fin du fichier se trouve initialement au début de la mémoire tampon.
MMIO_DELETE Supprime un fichier. Si cet indicateur est spécifié, szFilename ne doit pas avoir la valeur NULL. La valeur de retour est TRUE (converti en HMMIO) si le fichier a été supprimé avec succès ou FALSE dans le cas contraire. N’appelez pas la fonction mmioClose pour un fichier qui a été supprimé. Si cet indicateur est spécifié, tous les autres indicateurs qui ouvrent des fichiers sont ignorés.
MMIO_DENYNONE Ouvre le fichier sans refuser à d’autres processus l’accès en lecture ou en écriture au fichier. Si le fichier a été ouvert en mode de compatibilité par un autre processus, mmioOpen échoue.
MMIO_DENYREAD Ouvre le fichier et refuse à d’autres processus l’accès en lecture au fichier. Si le fichier a été ouvert en mode de compatibilité ou pour un accès en lecture par tout autre processus, mmioOpen échoue.
MMIO_DENYWRITE Ouvre le fichier et refuse à d’autres processus l’accès en écriture au fichier. Si le fichier a été ouvert en mode de compatibilité ou pour un accès en écriture par tout autre processus, mmioOpen échoue.
MMIO_EXCLUSIVE Ouvre le fichier et refuse à d’autres processus l’accès en lecture et en écriture au fichier. Si le fichier a été ouvert dans un autre mode pour l’accès en lecture ou en écriture, même par le processus actuel, mmioOpen échoue.
MMIO_EXIST Détermine si le fichier spécifié existe et crée un nom de fichier complet à partir du chemin spécifié dans szFilename. La valeur de retour est TRUE (cast en HMMIO) si la qualification a réussi et que le fichier existe ou FALSE dans le cas contraire. Le fichier n’est pas ouvert et la fonction ne retourne pas de handle d’E/S de fichier multimédia valide. N’essayez donc pas de fermer le fichier.
Note Les applications doivent appeler GetFileAttributes ou GetFileAttributesEx à la place.
 
MMIO_GETTEMP Crée un nom de fichier temporaire, éventuellement à l’aide des paramètres passés dans szFilename. Par exemple, vous pouvez spécifier « C :F » pour créer un fichier temporaire résidant sur le lecteur C, en commençant par la lettre « F ». Le nom de fichier résultant est copié dans la mémoire tampon pointée par szFilename. La mémoire tampon doit être suffisamment grande pour contenir au moins 128 caractères.

Si le nom de fichier temporaire a été créé avec succès, la valeur de retour est MMSYSERR_NOERROR (cast vers HMMIO). Sinon, la valeur de retour est MMIOERR_FILENOTFOUND sinon. Le fichier n’est pas ouvert et la fonction ne retourne pas de handle d’E/S de fichier multimédia valide. N’essayez donc pas de fermer le fichier. Cet indicateur remplace tous les autres indicateurs.

Note Les applications doivent appeler GetTempFileName à la place.
 
MMIO_PARSE Crée un nom de fichier complet à partir du chemin spécifié dans szFilename. Le nom complet est copié dans la mémoire tampon pointée par szFilename. La mémoire tampon doit être suffisamment grande pour contenir au moins 128 caractères.

Si la fonction réussit, la valeur de retour est TRUE (cast en HMMIO). Sinon, la valeur de retour est FALSE. Le fichier n’est pas ouvert et la fonction ne retourne pas de handle d’E/S de fichier multimédia valide. N’essayez donc pas de fermer le fichier. Si cet indicateur est spécifié, tous les indicateurs qui ouvrent des fichiers sont ignorés.

Note Les applications doivent appeler GetFullPathName à la place.
 
MMIO_READ Ouvre le fichier pour un accès en lecture uniquement. Il s’agit de la valeur par défaut si MMIO_WRITE et MMIO_READWRITE ne sont pas spécifiés.
MMIO_READWRITE Ouvre le fichier pour la lecture et l’écriture.
MMIO_WRITE Ouvre le fichier pour l'accès en écriture uniquement.

Valeur retournée

Retourne un handle du fichier ouvert. Si le fichier ne peut pas être ouvert, la valeur de retour est NULL. Si lpmmioinfo n’est pas NULL, le membre wErrorRet de la structure MMIOINFO contient l’une des valeurs d’erreur suivantes.

Code de retour Description
MMIOERR_ACCESSDENIED
 Le fichier est protégé et ne peut pas être ouvert.
MMIOERR_INVALIDFILE
 Une autre condition d’échec s’est produite. Il s’agit de l’erreur par défaut pour un échec d’ouverture de fichier.
MMIOERR_NETWORKERROR
 Le réseau ne répond pas à la demande d’ouverture d’un fichier distant.
MMIOERR_PATHNOTFOUND
 La spécification du répertoire est incorrecte.
MMIOERR_SHARINGVIOLATION
 Le fichier est utilisé par une autre application et n’est pas disponible.
MMIOERR_TOOMANYOPENFILES
 Le nombre de fichiers ouverts simultanément est à un niveau maximal. Le système n’a plus de descripteurs de fichiers disponibles.

Remarques

Si lpmmioinfo pointe vers une structure MMIOINFO , initialisez les membres de la structure comme suit. Tous les membres inutilisés doivent être définis sur zéro, y compris les membres réservés.

  • Pour demander l’ouverture d’un fichier avec une procédure d’E/S installée, définissez fccIOProc sur le code à quatre caractères de la procédure d’E/S, puis définissez pIOProc sur NULL.
  • Pour demander l’ouverture d’un fichier avec une procédure d’E/S désinstallée, définissez IOProc pour qu’il pointe vers la procédure d’E/S et définissez fccIOProc sur NULL.
  • Pour demander à mmioOpen de déterminer la procédure d’E/S à utiliser pour ouvrir le fichier en fonction du nom de fichier contenu dans szFilename, définissezfccIOProc et pIOProc sur NULL. Il s’agit du comportement par défaut si aucune structure MMIOINFO n’est spécifiée.
  • Pour ouvrir un fichier mémoire à l’aide d’une mémoire tampon allouée et gérée en interne, définissez pchBuffer sur NULL, fccIOProc sur FOURCC_MEM, cchBuffer sur la taille initiale de la mémoire tampon et adwInfo sur la taille d’expansion incrémentielle de la mémoire tampon. Ce fichier mémoire est automatiquement développé par incréments du nombre d’octets spécifié dans adwInfo si nécessaire. Spécifiez l’indicateur MMIO_CREATE pour que le paramètre dwOpenFlags définisse initialement la fin du fichier comme début de la mémoire tampon.
  • Pour ouvrir un fichier mémoire à l’aide d’une mémoire tampon fournie par l’application, définissez pchBuffer pour qu’il pointe vers la mémoire tampon, fccIOProc sur FOURCC_MEM, cchBuffer sur la taille de la mémoire tampon et adwInfo sur la taille d’expansion incrémentielle de la mémoire tampon. La taille d’expansion dans adwInfo doit être différente de zéro uniquement si pchBuffer est un pointeur obtenu en appelant les fonctions GlobalAlloc et GlobalLock ; dans ce cas, la fonction GlobalReAlloc est appelée pour développer la mémoire tampon. En d’autres termes, si pchBuffer pointe vers un tableau local ou global ou un bloc de mémoire dans le tas local, adwInfo doit être égal à zéro. Spécifiez l’indicateur MMIO_CREATE pour que le paramètre dwOpenFlags définisse initialement la fin du fichier comme début de la mémoire tampon. Sinon, la totalité du bloc de mémoire est considérée comme lisible.
  • Pour utiliser un handle de fichier standard actuellement ouvert (autrement dit, un handle de fichier qui n’a pas le type HMMIO ) avec des services d’E/S de fichiers multimédias, définissez fccIOProc sur FOURCC_DOS, pchBuffer sur NULL et adwInfo sur le handle de fichier standard. Les décalages dans le fichier seront relatifs au début du fichier et ne sont pas liés à la position dans le fichier standard au moment où mmioOpen est appelé ; le décalage d’E/S du fichier multimédia initial sera le même que le décalage dans le fichier standard lorsque mmioOpen est appelé. Pour fermer le handle de fichier d’E/S multimédia sans fermer le handle de fichier standard, passez l’indicateur MMIO_FHOPEN à mmioClose.
Vous devez appeler mmioClose pour fermer un fichier ouvert à l’aide de mmioOpen. Les fichiers ouverts ne sont pas automatiquement fermés lorsqu’une application se ferme.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête mmiscapi.h (inclure Mmiscapi.h, Windows.h)
Bibliothèque Winmm.lib
DLL Winmm.dll