mmioOpen-Funktion (mmiscapi.h)

  • Artikel

Die mmioOpen-Funktion öffnet eine Datei für ungepufferte oder gepufferte E/A-Vorgänge. erstellt eine Datei; löscht eine Datei; oder überprüft, ob eine Datei vorhanden ist. Die Datei kann eine Standarddatei, eine Speicherdatei oder ein Element eines benutzerdefinierten Speichersystems sein. Das von mmioOpen zurückgegebene Handle ist kein Standarddateihandle. verwenden Sie es nicht mit anderen Datei-E/A-Funktionen als Multimediadatei-E/A-Funktionen.

Hinweis Diese Funktion ist veraltet. Anwendungen sollten CreateFile aufrufen, um Dateien zu erstellen oder zu öffnen.
 

Syntax

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

Parameter

pszFileName

Zeiger auf einen Puffer, der den Namen der Datei enthält. Wenn keine E/A-Prozedur zum Öffnen der Datei angegeben ist, bestimmt der Dateiname wie folgt, wie die Datei geöffnet wird:

  • Wenn der Dateiname kein Pluszeichen (+) enthält, wird davon ausgegangen, dass es sich um den Namen einer Standarddatei handelt (d. h. eine Datei, deren Typ nicht HMMIO ist).
  • Wenn der Dateiname das Format EXAMPLE hat. EXT+ABC, die Erweiterung EXT wird angenommen, um eine installierte E/A-Prozedur zu identifizieren, die aufgerufen wird, um E/A für die Datei auszuführen. Weitere Informationen finden Sie unter mmioInstallIOProc.
  • Wenn der Dateiname NULL ist und keine E/A-Prozedur angegeben wird, wird angenommen, dass das adwInfo-Element der MMIOINFO-Struktur das Standarddateihandle (nicht HMMIO) einer derzeit geöffneten Datei ist.
Der Dateiname darf nicht länger als 128 Zeichen sein, einschließlich des beendenden NULL-Zeichens.

Legen Sie beim Öffnen einer Speicherdatei szFilename auf NULL fest.

pmmioinfo

Zeiger auf eine MMIOINFO-Struktur mit zusätzlichen Parametern, die von mmioOpen verwendet werden. Sofern Sie keine Speicherdatei öffnen, die Größe eines Puffers für gepufferte E/A-Vorgänge oder eine deinstallierte E/A-Prozedur zum Öffnen einer Datei angeben, sollte dieser Parameter NULL sein. Wenn dieser Parameter nicht NULL ist, müssen alle nicht verwendeten Member der MMIOINFO-Struktur , auf die verwiesen wird, auf Null festgelegt werden, einschließlich der reservierten Elemente.

fdwOpen

Flags für den geöffneten Vorgang. Die flags MMIO_READ, MMIO_WRITE und MMIO_READWRITE schließen sich gegenseitig aus – es sollte nur eine angegeben werden. Die flags MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD und MMIO_DENYNONE sind Dateifreigabeflags. Die folgenden Werte werden definiert.

Wert Bedeutung
MMIO_ALLOCBUF Öffnet eine Datei für gepufferte E/A. Um einen Puffer zuzuweisen, der größer oder kleiner als die Standardpuffergröße (8K, definiert als MMIO_DEFAULTBUFFER) ist, legen Sie den cchBuffer-Member der MMIOINFO-Struktur auf die gewünschte Puffergröße fest. Wenn cchBuffer null ist, wird die Standardpuffergröße verwendet. Wenn Sie Einen eigenen E/A-Puffer bereitstellen, sollte dieses Flag nicht verwendet werden.
MMIO_COMPAT Öffnet die Datei im Kompatibilitätsmodus, sodass jeder Prozess auf einem bestimmten Computer die Datei beliebig oft öffnen kann. Wenn die Datei mit einem der anderen Freigabemodi geöffnet wurde, schlägt mmioOpen fehl.
MMIO_CREATE Erstellt eine neue Datei. Wenn die Datei bereits vorhanden ist, wird sie auf die Länge null abgeschnitten. Bei Speicherdateien gibt dieses Flag an, dass sich das Ende der Datei zunächst am Anfang des Puffers befindet.
MMIO_DELETE Löscht eine Datei. Wenn dieses Flag angegeben ist, sollte szFilename nicht NULL sein. Der Rückgabewert ist TRUE (umwandlung in HMMIO), wenn die Datei erfolgreich gelöscht wurde oder andernfalls FALSE . Rufen Sie die mmioClose-Funktion nicht für eine datei auf, die gelöscht wurde. Wenn dieses Flag angegeben ist, werden alle anderen Flags ignoriert, die Dateien öffnen.
MMIO_DENYNONE Öffnet die Datei, ohne anderen Prozessen lese- oder schreibzugriff auf die Datei zu verweigern. Wenn die Datei von einem anderen Prozess im Kompatibilitätsmodus geöffnet wurde, schlägt mmioOpen fehl.
MMIO_DENYREAD Öffnet die Datei und verweigert anderen Prozessen den Lesezugriff auf die Datei. Wenn die Datei im Kompatibilitätsmodus oder für den Lesezugriff durch einen anderen Prozess geöffnet wurde, schlägt mmioOpen fehl.
MMIO_DENYWRITE Öffnet die Datei und verweigert anderen Prozessen den Schreibzugriff auf die Datei. Wenn die Datei im Kompatibilitätsmodus oder für den Schreibzugriff durch einen anderen Prozess geöffnet wurde, schlägt mmioOpen fehl.
MMIO_EXCLUSIVE Öffnet die Datei und verweigert anderen Prozessen lese- und schreibzugriff auf die Datei. Wenn die Datei in einem anderen Modus für Lese- oder Schreibzugriff geöffnet wurde, auch durch den aktuellen Prozess, schlägt mmioOpen fehl.
MMIO_EXIST Bestimmt, ob die angegebene Datei vorhanden ist, und erstellt einen vollqualifizierten Dateinamen aus dem in szFilename angegebenen Pfad. Der Rückgabewert ist TRUE (umwandlung in HMMIO), wenn die Qualifikation erfolgreich war und die Datei vorhanden ist, oder andernfalls FALSE . Die Datei wird nicht geöffnet, und die Funktion gibt kein gültiges E/A-Dateihandle für Multimediadateien zurück. Versuchen Sie also nicht, die Datei zu schließen.
Hinweis Anwendungen sollten stattdessen GetFileAttributes oder GetFileAttributesEx aufrufen.
 
MMIO_GETTEMP Erstellt einen temporären Dateinamen, optional mithilfe der parameter, die in szFilename übergeben werden. Sie können beispielsweise "C:F" angeben, um eine temporäre Datei auf Laufwerk C zu erstellen, beginnend mit dem Buchstaben "F". Der resultierende Dateiname wird in den Puffer kopiert, auf den szFilename verweist. Der Puffer muss groß genug sein, um mindestens 128 Zeichen aufzunehmen.

Wenn der temporäre Dateiname erfolgreich erstellt wurde, wird der Rückgabewert MMSYSERR_NOERROR (in HMMIO umgewandelt). Andernfalls wird der Rückgabewert andernfalls MMIOERR_FILENOTFOUND . Die Datei wird nicht geöffnet, und die Funktion gibt kein gültiges E/A-Dateihandle für Multimediadateien zurück. Versuchen Sie also nicht, die Datei zu schließen. Dieses Flag setzt alle anderen Flags außer Kraft.

Hinweis Anwendungen sollten stattdessen GetTempFileName aufrufen.
 
MMIO_PARSE Erstellt einen vollqualifizierten Dateinamen aus dem pfad, der in szFilename angegeben ist. Der vollqualifizierte Name wird in den Puffer kopiert, auf den szFilename verweist. Der Puffer muss groß genug sein, um mindestens 128 Zeichen aufzunehmen.

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE (in HMMIO umgewandelt). Andernfalls ist der Rückgabewert FALSE. Die Datei wird nicht geöffnet, und die Funktion gibt kein gültiges E/A-Dateihandle für Multimediadateien zurück. Versuchen Sie also nicht, die Datei zu schließen. Wenn dieses Flag angegeben ist, werden alle Flags ignoriert, die Dateien öffnen.

Hinweis Anwendungen sollten stattdessen GetFullPathName aufrufen.
 
MMIO_READ Öffnet eine Datei nur zum Lesen. Dies ist die Standardeinstellung, wenn MMIO_WRITE und MMIO_READWRITE nicht angegeben werden.
MMIO_READWRITE Öffnet die Datei zum Lesen und Schreiben.
MMIO_WRITE Öffnet die Datei nur zum Schreiben.

Rückgabewert

Gibt ein Handle der geöffneten Datei zurück. Wenn die Datei nicht geöffnet werden kann, ist der Rückgabewert NULL. Wenn lpmmioinfo nicht NULL ist, enthält das wErrorRet-Element der MMIOINFO-Struktur einen der folgenden Fehlerwerte.

Rückgabecode Beschreibung
MMIOERR_ACCESSDENIED
 Die Datei ist geschützt und kann nicht geöffnet werden.
MMIOERR_INVALIDFILE
 Eine weitere Fehlerbedingung ist aufgetreten. Dies ist der Standardfehler für einen Fehler beim Öffnen einer Datei.
MMIOERR_NETWORKERROR
 Das Netzwerk reagiert nicht auf die Anforderung, eine Remotedatei zu öffnen.
MMIOERR_PATHNOTFOUND
 Die Verzeichnisspezifikation ist falsch.
MMIOERR_SHARINGVIOLATION
 Die Datei wird von einer anderen Anwendung verwendet und ist nicht verfügbar.
MMIOERR_TOOMANYOPENFILES
 Die Anzahl der gleichzeitig geöffneten Dateien ist auf einem maximalen Niveau. Dem System sind keine verfügbaren Dateihandles mehr verfügbar.

Hinweise

Wenn lpmmioinfo auf eine MMIOINFO-Struktur verweist, initialisieren Sie die Member der -Struktur wie folgt. Alle nicht verwendeten Member müssen auf Null festgelegt werden, einschließlich reservierter Member.

  • Um anzufordern, dass eine Datei mit einer installierten E/A-Prozedur geöffnet wird, legen Sie fccIOProc auf den vierstelligen Code der E/A-Prozedur und pIOProc auf NULL fest.
  • Um anzufordern, dass eine Datei mit einer deinstallierten E/A-Prozedur geöffnet wird, legen Sie IOProc so fest, dass auf die E/A-Prozedur verweist, und legen Sie fccIOProc auf NULL fest.
  • Legen Sie fccIOProc und pIOProc auf NULL fest, um mmioOpen aufzufordern, welche E/A-Prozedur zum Öffnen der Datei verwendet werden soll. Dies ist das Standardverhalten, wenn keine MMIOINFO-Struktur angegeben wird.
  • Um eine Speicherdatei mit einem intern zugeordneten und verwalteten Puffer zu öffnen, legen Sie pchBuffer auf NULL, fccIOProc auf FOURCC_MEM, cchBuffer auf die Anfangsgröße des Puffers und adwInfo auf die inkrementelle Erweiterungsgröße des Puffers fest. Diese Speicherdatei wird bei Bedarf automatisch in Inkrementen der in adwInfo angegebenen Anzahl von Bytes erweitert. Geben Sie das MMIO_CREATE-Flag für den dwOpenFlags-Parameter an, um das Ende der Datei zunächst als Anfang des Puffers festzulegen.
  • Um eine Speicherdatei mit einem von der Anwendung bereitgestellten Puffer zu öffnen, legen Sie pchBuffer so fest, dass er auf den Speicherpuffer zeigt, fccIOProc auf FOURCC_MEM, cchBuffer auf die Größe des Puffers und adwInfo auf die inkrementelle Erweiterungsgröße des Puffers. Die Erweiterungsgröße in adwInfo sollte nur ungleich null sein, wenn pchBuffer ein Zeiger ist, der durch Aufrufen der GlobalAlloc - und GlobalLock-Funktionen abgerufen wird. In diesem Fall wird die GlobalReAlloc-Funktion aufgerufen, um den Puffer zu erweitern. Anders ausgedrückt: Wenn pchBuffer auf ein lokales oder globales Array oder einen Speicherblock im lokalen Heap zeigt, muss adwInfo null sein. Geben Sie das MMIO_CREATE-Flag für den dwOpenFlags-Parameter an, um das Ende der Datei zunächst als Anfang des Puffers festzulegen. Andernfalls gilt der gesamte Speicherblock als lesbar.
  • Legen Sie fccIOProc auf FOURCC_DOS, pchBuffer auf NULL und adwInfo auf das Standarddateihandle fest, um ein derzeit geöffnetes Standarddateihandle (d. h. ein Dateihandle, das nicht über den HMMIO-Typ verfügt) mit Multimediadatei-E/A-Diensten zu verwenden. Offsets innerhalb der Datei sind relativ zum Anfang der Datei und beziehen sich nicht auf die Position in der Standarddatei zum Zeitpunkt des Aufrufs von mmioOpen . Der anfängliche E/A-Offset der Multimediadatei entspricht dem Offset in der Standarddatei, wenn mmioOpen aufgerufen wird. Um das E/A-Dateihandle für Multimediadateien zu schließen, ohne das Standarddateihandle zu schließen, übergeben Sie das flag MMIO_FHOPEN an mmioClose.
Sie müssen mmioClose aufrufen, um eine Datei zu schließen, die mit mmioOpen geöffnet wurde. Geöffnete Dateien werden nicht automatisch geschlossen, wenn eine Anwendung beendet wird.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile mmiscapi.h (include Mmiscapi.h, Windows.h)
Bibliothek Winmm.lib
DLL Winmm.dll