mmioOpenW-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 Multimedia-Datei-E/A-Funktionen.

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

Syntax

HMMIO mmioOpenW(
  LPWSTR     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 abschließenden NULL-Zeichens.

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

pmmioinfo

Zeiger auf eine MMIOINFO-Struktur , die zusätzliche Parameter enthält, 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 er verweist, auf Null festgelegt werden, einschließlich der reservierten Member.

fdwOpen

Flags für den Öffnen-Vorgang. Die Flags MMIO_READ, MMIO_WRITE und MMIO_READWRITE schließen sich gegenseitig aus . Es sollte nur ein Flag 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-Vorgänge. Um einen Puffer zuzuweisen, der größer oder kleiner als die Standardpuffergröße (8K, definiert als MMIO_DEFAULTBUFFER), 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 0 (null) abgeschnitten. Bei Speicherdateien gibt dieses Flag an, dass sich das Ende der Datei anfänglich 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 (in HMMIO umgewandelt), 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 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 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 pfad, der in szFilename angegeben ist. Der Rückgabewert ist TRUE (in HMMIO umgewandelt), wenn die Qualifizierung 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 daher nicht, die Datei zu schließen.
Hinweis Anwendungen sollten stattdessen GetFileAttributes oder GetFileAttributesEx aufrufen.
 
MMIO_GETTEMP Erstellt einen temporären Dateinamen, optional mit den parametern, die in szFilename übergeben werden. Beispielsweise können Sie "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 zu enthalten.

Wenn der temporäre Dateiname erfolgreich erstellt wurde, lautet 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 daher nicht, die Datei zu schließen. Dieses Flag überschreibt alle anderen Flags.

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 zu enthalten.

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE (umwandlung in HMMIO). 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 daher 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 sind.
MMIO_READWRITE Öffnet die Datei zum Lesen und Schreiben.
MMIO_WRITE Öffnet die Datei nur zum Schreiben.

Rückgabewert

Keine

Bemerkungen

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.

Hinweis

Der mmiscapi.h-Header definiert mmioOpen als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

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