Função mmioOpen (mmiscapi.h)
A função mmioOpen abre um arquivo para E/S não armazenada em buffer ou sem buffer; cria um arquivo; exclui um arquivo; ou verifica se existe um arquivo. O arquivo pode ser um arquivo padrão, um arquivo de memória ou um elemento de um sistema de armazenamento personalizado. O identificador retornado por mmioOpen não é um identificador de arquivo padrão; não o use com funções de E/S de arquivo diferentes de funções de E/S de arquivo multimídia.
Sintaxe
HMMIO mmioOpen(
LPSTR pszFileName,
LPMMIOINFO pmmioinfo,
DWORD fdwOpen
);
Parâmetros
pszFileName
Ponteiro para um buffer que contém o nome do arquivo. Se nenhum procedimento de E/S for especificado para abrir o arquivo, o nome do arquivo determinará como o arquivo é aberto, da seguinte maneira:
- Se o nome do arquivo não contiver um sinal de adição (+), será considerado o nome de um arquivo padrão (ou seja, um arquivo cujo tipo não seja HMMIO).
- Se o nome do arquivo for do formulário EXEMPLO. EXT+ABC, supõe-se que a extensão EXT identifique um procedimento de E/S instalado que é chamado para executar E/S no arquivo. Para obter mais informações, consulte mmioInstallIOProc.
- Se o nome do arquivo for NULL e nenhum procedimento de E/S for fornecido, o membro adwInfo da estrutura MMIOINFO será considerado o identificador de arquivo padrão (não HMMIO) de um arquivo aberto no momento.
Ao abrir um arquivo de memória, defina szFilename como NULL.
pmmioinfo
Ponteiro para uma estrutura MMIOINFO que contém parâmetros extras usados por mmioOpen. A menos que você esteja abrindo um arquivo de memória, especificando o tamanho de um buffer para E/S em buffer ou especificando um procedimento de E/S desinstalado para abrir um arquivo, esse parâmetro deve ser NULL. Se esse parâmetro não for NULL, todos os membros não utilizados da estrutura MMIOINFO que ele referenciar deverão ser definidos como zero, incluindo os membros reservados.
fdwOpen
Sinalizadores para a operação aberta. Os sinalizadores MMIO_READ, MMIO_WRITE e MMIO_READWRITE são mutuamente exclusivos– apenas um deve ser especificado. Os sinalizadores MMIO_COMPAT, MMIO_EXCLUSIVE, MMIO_DENYWRITE, MMIO_DENYREAD e MMIO_DENYNONE são sinalizadores de compartilhamento de arquivos. Os valores a seguir são definidos.
| Valor | Significado |
|---|---|
| MMIO_ALLOCBUF | Abre um arquivo para E/S em buffer. Para alocar um buffer maior ou menor que o tamanho do buffer padrão (8K, definido como MMIO_DEFAULTBUFFER), defina o membro cchBuffer da estrutura MMIOINFO para o tamanho do buffer desejado. Se cchBuffer for zero, o tamanho do buffer padrão será usado. Se você estiver fornecendo seu próprio buffer de E/S, esse sinalizador não deverá ser usado. |
| MMIO_COMPAT | Abre o arquivo com o modo de compatibilidade, permitindo que qualquer processo em um determinado computador abra o arquivo várias vezes. Se o arquivo tiver sido aberto com qualquer um dos outros modos de compartilhamento, mmioOpen falhará. |
| MMIO_CREATE | Cria um arquivo novo. Se o arquivo já existir, ele será truncado para comprimento zero. Para arquivos de memória, esse sinalizador indica que o final do arquivo está inicialmente no início do buffer. |
| MMIO_DELETE | Exclui um arquivo. Se esse sinalizador for especificado, szFilename não deverá ser NULL. O valor retornado será TRUE (convertido em HMMIO) se o arquivo tiver sido excluído com êxito ou FALSE caso contrário. Não chame a função mmioClose para um arquivo que foi excluído. Se esse sinalizador for especificado, todos os outros sinalizadores que abrem arquivos serão ignorados. |
| MMIO_DENYNONE | Abre o arquivo sem negar a outros processos acesso de leitura ou gravação ao arquivo. Se o arquivo tiver sido aberto no modo de compatibilidade por qualquer outro processo, mmioOpen falhará. |
| MMIO_DENYREAD | Abre o arquivo e nega que outros processos tenham acesso de leitura ao arquivo. Se o arquivo tiver sido aberto no modo de compatibilidade ou para acesso de leitura por qualquer outro processo, mmioOpen falhará. |
| MMIO_DENYWRITE | Abre o arquivo e nega que outros processos gravam acesso ao arquivo. Se o arquivo tiver sido aberto no modo de compatibilidade ou para acesso de gravação por qualquer outro processo, mmioOpen falhará. |
| MMIO_EXCLUSIVE | Abre o arquivo e nega outros processos de acesso de leitura e gravação ao arquivo. Se o arquivo tiver sido aberto em qualquer outro modo para acesso de leitura ou gravação, mesmo pelo processo atual, mmioOpen falhará. |
| MMIO_EXIST | Determina se o arquivo especificado existe e cria um nome de arquivo totalmente qualificado do caminho especificado em szFilename. O valor retornado será TRUE (convertido em HMMIO) se a qualificação tiver sido bem-sucedida e o arquivo existir ou FALSE caso contrário. O arquivo não é aberto e a função não retorna um identificador de arquivo de E/S de arquivo multimídia válido, portanto, não tente fechar o arquivo.
Nota Em vez disso, os aplicativos devem chamar GetFileAttributes ou GetFileAttributesEx .
|
| MMIO_GETTEMP |
Cria um nome de arquivo temporário, opcionalmente usando os parâmetros passados em szFilename. Por exemplo, você pode especificar "C:F" para criar um arquivo temporário que reside na unidade C, começando com a letra "F". O nome do arquivo resultante é copiado para o buffer apontado por szFilename. O buffer deve ser grande o suficiente para conter pelo menos 128 caracteres.
Se o nome do arquivo temporário tiver sido criado com êxito, o valor retornado será MMSYSERR_NOERROR (convertido em HMMIO). Caso contrário, o valor retornado será MMIOERR_FILENOTFOUND caso contrário. O arquivo não é aberto e a função não retorna um identificador de arquivo de E/S de arquivo multimídia válido, portanto, não tente fechar o arquivo. Esse sinalizador substitui todos os outros sinalizadores. Nota Em vez disso, os aplicativos devem chamar GetTempFileName .
|
| MMIO_PARSE |
Cria um nome de arquivo totalmente qualificado do caminho especificado em szFilename. O nome totalmente qualificado é copiado para o buffer apontado por szFilename. O buffer deve ser grande o suficiente para conter pelo menos 128 caracteres.
Se a função for bem-sucedida, o valor retornado será TRUE (convertido em HMMIO). Caso contrário, o valor retornado será FALSE. O arquivo não é aberto e a função não retorna um identificador de arquivo de E/S de arquivo multimídia válido, portanto, não tente fechar o arquivo. Se esse sinalizador for especificado, todos os sinalizadores que abrem arquivos serão ignorados. Nota Em vez disso, os aplicativos devem chamar GetFullPathName .
|
| MMIO_READ | Abre o arquivo para somente leitura. Esse será o padrão se MMIO_WRITE e MMIO_READWRITE não forem especificados. |
| MMIO_READWRITE | Abre o arquivo para leitura e gravação. |
| MMIO_WRITE | Abre o arquivo somente gravação. |
Retornar valor
Retorna um identificador do arquivo aberto. Se o arquivo não puder ser aberto, o valor retornado será NULL. Se lpmmioinfo não for NULL, o membro wErrorRet da estrutura MMIOINFO conterá um dos valores de erro a seguir.
| Código de retorno | Descrição |
|---|---|
|
O arquivo está protegido e não pode ser aberto. |
|
Outra condição de falha ocorreu. Esse é o erro padrão para uma falha de arquivo aberto. |
|
A rede não está respondendo à solicitação para abrir um arquivo remoto. |
|
A especificação do diretório está incorreta. |
|
O arquivo está sendo usado por outro aplicativo e não está disponível. |
|
O número de arquivos abertos simultaneamente está em um nível máximo. O sistema ficou sem identificadores de arquivo disponíveis. |
Comentários
Se lpmmioinfo apontar para uma estrutura MMIOINFO , inicialize os membros da estrutura da seguinte maneira. Todos os membros não utilizados devem ser definidos como zero, incluindo membros reservados.
- Para solicitar que um arquivo seja aberto com um procedimento de E/S instalado, defina fccIOProc como o código de quatro caracteres do procedimento de E/S e defina pIOProc como NULL.
- Para solicitar que um arquivo seja aberto com um procedimento de E/S desinstalado, defina IOProc para apontar para o procedimento de E/S e defina fccIOProc como NULL.
- Para solicitar que mmioOpen determine qual procedimento de E/S usar para abrir o arquivo com base no nome do arquivo contido em szFilename, defina fccIOProc e pIOProc como NULL. Esse será o comportamento padrão se nenhuma estrutura MMIOINFO for especificada.
- Para abrir um arquivo de memória usando um buffer gerenciado e alocado internamente, defina pchBuffer como NULL, fccIOProc para FOURCC_MEM, cchBuffer para o tamanho inicial do buffer e adwInfo para o tamanho de expansão incremental do buffer. Esse arquivo de memória será expandido automaticamente em incrementos do número de bytes especificados em adwInfo quando necessário. Especifique o sinalizador MMIO_CREATE para o parâmetro dwOpenFlags definir inicialmente o final do arquivo como o início do buffer.
- Para abrir um arquivo de memória usando um buffer fornecido pelo aplicativo, defina pchBuffer para apontar para o buffer de memória, fccIOProc para FOURCC_MEM, cchBuffer para o tamanho do buffer e adwInfo para o tamanho de expansão incremental do buffer. O tamanho da expansão em adwInfo só deverá ser diferente de zero se pchBuffer for um ponteiro obtido chamando as funções GlobalAlloc e GlobalLock ; Nesse caso, a função GlobalReAlloc será chamada para expandir o buffer. Em outras palavras, se pchBuffer apontar para uma matriz local ou global ou um bloco de memória no heap local, adwInfo deverá ser zero. Especifique o sinalizador MMIO_CREATE para o parâmetro dwOpenFlags definir inicialmente o final do arquivo como o início do buffer. Caso contrário, todo o bloco de memória será considerado legível.
- Para usar um identificador de arquivo padrão aberto no momento (ou seja, um identificador de arquivo que não tem o tipo HMMIO ) com serviços de E/S de arquivo multimídia, defina fccIOProc como FOURCC_DOS, pchBuffer como NULL e adwInfo como o identificador de arquivo padrão. Os deslocamentos dentro do arquivo serão relativos ao início do arquivo e não estão relacionados à posição no arquivo padrão no momento em que mmioOpen é chamado; o deslocamento inicial de E/S do arquivo multimídia será o mesmo que o deslocamento no arquivo padrão quando mmioOpen for chamado. Para fechar o identificador de arquivo de E/S do arquivo multimídia sem fechar o identificador de arquivo padrão, passe o sinalizador MMIO_FHOPEN para mmioClose.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | mmiscapi.h (inclua Mmiscapi.h, Windows.h) |
| Biblioteca | Winmm.lib |
| DLL | Winmm.dll |