Share via

funzione mmioOpen (mmiscapi.h)

  • Articolo

La funzione mmioOpen apre un file per I/O non memorizzati nel buffer; crea un file; elimina un file; o verifica se esiste un file. Il file può essere un file standard, un file di memoria o un elemento di un sistema di archiviazione personalizzato. L'handle restituito da mmioOpen non è un handle file standard; non usarlo con funzioni di I/O file diverse da funzioni di I/O file multimediali.

Nota Questa funzione è deprecata. Le applicazioni devono chiamare CreateFile per creare o aprire file.
 

Sintassi

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

Parametri

pszFileName

Puntatore a un buffer contenente il nome del file. Se non viene specificata alcuna procedura di I/O per aprire il file, il nome del file determina la modalità di apertura del file, come indicato di seguito:

  • Se il nome del file non contiene un segno più (+), si presuppone che sia il nome di un file standard, ovvero un file il cui tipo non è HMMIO.
  • Se il nome del file è del modulo EXAMPLE. EXT+ABC, si presuppone che l'estensione EXT identifichi una procedura di I/O installata chiamata per eseguire I/O nel file. Per altre informazioni, vedere mmioInstallIOProc.
  • Se il nome del file è NULL e non viene specificata alcuna procedura di I/O, si presuppone che il membro adwInfo della struttura MMIOINFO sia l'handle di file standard (non HMMIO) di un file attualmente aperto.
Il nome del file non deve essere superiore a 128 caratteri, incluso il carattere NULL terminante.

Quando si apre un file di memoria, impostare szFilename su NULL.

pmmioinfo

Puntatore a una struttura MMIOINFO contenente parametri aggiuntivi usati da mmioOpen. A meno che non si stia aprendo un file di memoria, specificando le dimensioni di un buffer per l'I/O memorizzato nel buffer o specificando una procedura di I/O disinstallata per aprire un file, questo parametro deve essere NULL. Se questo parametro non è NULL, tutti i membri inutilizzati della struttura MMIOINFO a cui fa riferimento devono essere impostati su zero, inclusi i membri riservati.

fdwOpen

Flag per l'operazione aperta. I flag MMIO_READ, MMIO_WRITE e MMIO_READWRITE si escludono a vicenda, solo uno deve essere specificato. I flag di MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD e MMIO_DENYNONE sono flag di condivisione file. I valori seguenti sono definiti.

Valore Significato
MMIO_ALLOCBUF Apre un file per L/O memorizzato nel buffer. Per allocare un buffer maggiore o minore della dimensione predefinita del buffer (8K, definita come MMIO_DEFAULTBUFFER), impostare il membro cchBuffer della struttura MMIOINFO sulla dimensione del buffer desiderata. Se cchBuffer è zero, viene usata la dimensione predefinita del buffer. Se si fornisce un buffer di I/O personalizzato, questo flag non deve essere usato.
MMIO_COMPAT Apre il file con la modalità di compatibilità, consentendo a qualsiasi processo in un determinato computer di aprire il file in qualsiasi numero di volte. Se il file è stato aperto con una delle altre modalità di condivisione, mmioOpen ha esito negativo.
MMIO_CREATE Crea un nuovo file. Se il file esiste già, viene troncato a lunghezza zero. Per i file di memoria, questo flag indica la fine del file inizialmente all'inizio del buffer.
MMIO_DELETE Elimina un file. Se questo flag è specificato, szFilename non deve essere NULL. Il valore restituito è TRUE (cast a HMMIO) se il file è stato eliminato correttamente o FALSE in caso contrario. Non chiamare la funzione mmioClose per un file eliminato. Se questo flag viene specificato, vengono ignorati tutti gli altri flag che aprono file.
MMIO_DENYNONE Apre il file senza negare ad altri processi l'accesso in lettura o scrittura al file. Se il file è stato aperto in modalità di compatibilità da qualsiasi altro processo, mmioOpen ha esito negativo.
MMIO_DENYREAD Apre il file e nega ad altri processi l'accesso in lettura al file. Se il file è stato aperto in modalità di compatibilità o per l'accesso in lettura da qualsiasi altro processo, mmioOpen ha esito negativo.
MMIO_DENYWRITE Apre il file e nega l'accesso in scrittura ad altri processi al file. Se il file è stato aperto in modalità di compatibilità o per l'accesso in scrittura da qualsiasi altro processo, mmioOpen ha esito negativo.
MMIO_EXCLUSIVE Apre il file e nega l'accesso in lettura e scrittura ad altri processi al file. Se il file è stato aperto in qualsiasi altra modalità per l'accesso in lettura o scrittura, anche dal processo corrente, mmioOpen ha esito negativo.
MMIO_EXIST Determina se il file specificato esiste e crea un nome di file completo dal percorso specificato in szFilename. Il valore restituito è TRUE (cast a HMMIO) se la qualifica è riuscita e il file esiste o FALSE in caso contrario. Il file non viene aperto e la funzione non restituisce un handle di file multimediale I/O valido, quindi non tentare di chiudere il file.
Nota Le applicazioni devono invece chiamare GetFileAttributes o GetFileAttributesEx .
 
MMIO_GETTEMP Crea un nome file temporaneo, facoltativamente usando i parametri passati in szFilename. Ad esempio, è possibile specificare "C:F" per creare un file temporaneo che risiede nell'unità C, a partire dalla lettera "F". Il nome del file risultante viene copiato nel buffer a cui fa riferimento szFilename. Il buffer deve essere abbastanza grande per contenere almeno 128 caratteri.

Se il nome del file temporaneo è stato creato correttamente, il valore restituito è MMSYSERR_NOERROR (cast in HMMIO). In caso contrario, il valore restituito è MMIOERR_FILENOTFOUND in caso contrario. Il file non viene aperto e la funzione non restituisce un handle di file multimediale I/O valido, quindi non tentare di chiudere il file. Questo flag esegue l'override di tutti gli altri flag.

Nota Le applicazioni devono invece chiamare GetTempFileName .
 
MMIO_PARSE Crea un nome di file completo dal percorso specificato in szFilename. Il nome completo viene copiato nel buffer a cui fa riferimento szFilename. Il buffer deve essere abbastanza grande per contenere almeno 128 caratteri.

Se la funzione ha esito positivo, il valore restituito è TRUE (cast in HMMIO). In caso contrario, il valore restituito è FALSE. Il file non viene aperto e la funzione non restituisce un handle di file multimediale I/O valido, quindi non tentare di chiudere il file. Se questo flag viene specificato, tutti i flag aperti vengono ignorati.

Nota Le applicazioni devono invece chiamare GetFullPathName .
 
MMIO_READ Apre il file in sola lettura. Si tratta del valore predefinito se MMIO_WRITE e MMIO_READWRITE non sono specificati.
MMIO_READWRITE Apre il file per la lettura e la scrittura.
MMIO_WRITE Apre il file per la sola scrittura.

Valore restituito

Restituisce un handle del file aperto. Se il file non può essere aperto, il valore restituito è NULL. Se lpmmioinfo non è NULL, il membro wErrorRet della struttura MMIOINFO conterrà uno dei valori di errore seguenti.

Codice restituito Descrizione
MMIOERR_ACCESSDENIED
 Il file è protetto e non può essere aperto.
MMIOERR_INVALIDFILE
 Si è verificata un'altra condizione di errore. Si tratta dell'errore predefinito per un errore open-file.
MMIOERR_NETWORKERROR
 La rete non risponde alla richiesta per aprire un file remoto.
MMIOERR_PATHNOTFOUND
 La specifica della directory non è corretta.
MMIOERR_SHARINGVIOLATION
 Il file viene usato da un'altra applicazione e non è disponibile.
MMIOERR_TOOMANYOPENFILES
 Il numero di file aperti simultaneamente è a un livello massimo. Il sistema ha esaurito gli handle di file disponibili.

Commenti

Se lpmmioinfo punta a una struttura MMIOINFO , inizializzare i membri della struttura come indicato di seguito. Tutti i membri inutilizzati devono essere impostati su zero, inclusi i membri riservati.

  • Per richiedere l'apertura di un file con una procedura di I/O installata, impostare fccIOProc sul codice a quattro caratteri della procedura di I/O e impostare pIOProc su NULL.
  • Per richiedere l'apertura di un file con una procedura di I/O disinstallata, impostare IOProc per puntare alla procedura di I/O e impostare fccIOProc su NULL.
  • Per richiedere che mmioOpen determini quale procedura di I/O usare per aprire il file in base al nome del file contenuto in szFilename, impostare fccIOProc e pIOProc su NULL. Si tratta del comportamento predefinito se non viene specificata alcuna struttura MMIOINFO .
  • Per aprire un file di memoria usando un buffer allocato e gestito internamente, impostare pchBuffer su NULL, fccIOProc su FOURCC_MEM, cchBuffer alle dimensioni iniziali del buffer e adwInfo alle dimensioni incrementali del buffer. Questo file di memoria verrà espanso automaticamente in incrementi del numero di byte specificati in adwInfo quando necessario. Specificare il flag MMIO_CREATE per il parametro dwOpenFlags per impostare inizialmente la fine del file come inizio del buffer.
  • Per aprire un file di memoria usando un buffer fornito dall'applicazione, impostare pchBuffer per puntare al buffer di memoria, fccIOProc su FOURCC_MEM, cchBuffer alle dimensioni del buffer e adwInfo alle dimensioni incrementali del buffer. Le dimensioni di espansione in adwInfo devono essere non zero solo se pchBuffer è un puntatore ottenuto chiamando le funzioni GlobalAlloc e GlobalLock ; in questo caso, la funzione GlobalReAlloc verrà chiamata per espandere il buffer. In altre parole, se pchBuffer punta a una matrice locale o globale o a un blocco di memoria nell'heap locale, adwInfo deve essere zero. Specificare il flag MMIO_CREATE per il parametro dwOpenFlags per impostare inizialmente la fine del file come inizio del buffer. In caso contrario, l'intero blocco di memoria viene considerato leggibile.
  • Per usare un handle di file standard attualmente aperto, ovvero un handle di file che non ha il tipo HMMIO , con servizi di I/O multimediali, impostare fccIOProc su FOURCC_DOS, pchBuffer su NULL e adwInfo per l'handle file standard. Gli offset all'interno del file saranno relativi all'inizio del file e non sono correlati alla posizione nel file standard al momento in cui viene chiamato mmioOpen ; l'offset di I/O multimediale iniziale sarà lo stesso dell'offset nel file standard quando viene chiamato mmioOpen . Per chiudere l'handle di file di I/O multimediale senza chiudere l'handle di file standard, passare il flag MMIO_FHOPEN a mmioClose.
È necessario chiamare mmioClose per chiudere un file aperto usando mmioOpen. I file aperti non vengono chiusi automaticamente quando un'applicazione viene chiusa.

Requisiti

Requisito Valore
Client minimo supportato Windows 2000 Professional [solo app desktop]
Server minimo supportato Windows 2000 Server [solo app desktop]
Piattaforma di destinazione Windows
Intestazione mmiscapi.h (includono Mmiscapi.h, Windows.h)
Libreria Winmm.lib
DLL Winmm.dll