Compartilhar via


Função midiInMessage (mmeapi.h)

A função midiInMessage envia uma mensagem para o driver de dispositivo MIDI.

Sintaxe

MMRESULT midiInMessage(
  HMIDIIN   hmi,
  UINT      uMsg,
  DWORD_PTR dw1,
  DWORD_PTR dw2
);

Parâmetros

hmi

Identificador do dispositivo MIDI que recebe a mensagem. Você deve converter a ID do dispositivo para o tipo de identificador HMIDIIN . Se você fornecer um identificador em vez de uma ID do dispositivo, a função falhará e retornará o código de erro MMSYSERR_NOSUPPORT.

uMsg

Mensagem a ser enviada.

dw1

Parâmetro de mensagem.

dw2

Parâmetro de mensagem.

Retornar valor

Retorna o valor retornado pelo driver do dispositivo de áudio.

Comentários

Essa função é usada apenas para mensagens específicas do driver que não são compatíveis com a API MIDI.

As DRV_QUERYDEVICEINTERFACE consultas de mensagem para o nome da interface do dispositivo de um dispositivo waveIn, waveOut, midiIn, midiOut ou mixer .

Para DRV_QUERYDEVICEINTERFACE, dwParam1 é um ponteiro para um buffer alocado pelo chamador no qual a função grava uma cadeia de caracteres Unicode terminada em nulo que contém o nome da interface do dispositivo. Se o dispositivo não tiver interface do dispositivo, o comprimento da cadeia de caracteres será zero.

Para DRV_QUERYDEVICEINTERFACE, dwParam2 especifica o tamanho do buffer em bytes. Esse é um parâmetro de entrada para a função . O chamador deve especificar um tamanho maior ou igual ao tamanho do buffer recuperado pela mensagem DRV_QUERYDEVICEINTERFACESIZE .

A mensagem DRV_QUERYDEVICEINTERFACE tem suporte no Windows Me e no Windows 2000 e posterior. Essa mensagem é válida apenas para as funções waveInMessage, waveOutMessage, midiInMessage, midiOutMessage e mixerMessage . O sistema intercepta essa mensagem e retorna o valor apropriado sem enviar a mensagem para o driver do dispositivo. Para obter informações gerais sobre funções xxxMessage interceptadas pelo sistema, consulte Mensagens de dispositivo interceptadas pelo sistema.

As duas constantes de mensagem a seguir são usadas juntas para obter nomes de interface do dispositivo:

  • DRV_QUERYDEVICEINTERFACESIZE
  • DRV_QUERYDEVICEINTERFACE
A primeira mensagem obtém o tamanho em bytes do buffer necessário para manter a cadeia de caracteres que contém o nome da interface do dispositivo. A segunda mensagem recupera a cadeia de caracteres de nome em um buffer do tamanho necessário.

Para obter mais informações, consulte Obtendo um nome de interface do dispositivo.

As DRV_QUERYDEVICEINTERFACESIZE consultas de mensagem para o tamanho do buffer necessário para manter o nome da interface do dispositivo.

Para DRV_QUERYDEVICEINTERFACESIZE, dwParam1 é um ponteiro para o tamanho do buffer. Esse parâmetro aponta para uma variável ULONG na qual a função grava o tamanho do buffer necessário em bytes. O tamanho inclui espaço de armazenamento para o nulo de terminação da cadeia de caracteres de nome. O tamanho será zero se a ID do dispositivo identificar um dispositivo que não tenha interface do dispositivo.

Para DRV_QUERYDEVICEINTERFACESIZE, dwParam2 não é usado. Defina esse parâmetro como zero.

Essa mensagem é válida apenas para as funções waveInMessage, waveOutMessage, midiInMessage, midiOutMessage e mixerMessage . O sistema intercepta essa mensagem e retorna o valor apropriado sem enviar a mensagem para o driver do dispositivo. Para obter informações gerais sobre funções xxxMessage interceptadas pelo sistema, consulte Mensagens de dispositivo interceptadas pelo sistema.

O tamanho do buffer recuperado por essa mensagem é expresso como uma contagem de bytes. Ele especifica o tamanho do buffer necessário para manter a cadeia de caracteres Unicode terminada em nulo que contém o nome da interface do dispositivo. O chamador aloca um buffer do tamanho especificado e usa a mensagem DRV_QUERYDEVICEINTERFACE para recuperar a cadeia de caracteres de nome da interface do dispositivo.

Para obter mais informações, consulte Obtendo um nome de interface do dispositivo.

As DRV_QUERYDEVNODE consultas de mensagem para o número de devnode atribuído ao dispositivo pelo gerenciador de Plug and Play.

Para DRV_QUERYDEVNODE, dwParam1 é um ponteiro para uma variável DWORD alocada pelo chamador na qual a função grava o número do devnode. Se nenhum devnode for atribuído ao dispositivo, a função definirá essa variável como zero.

Para DRV_QUERYDEVNODE, dwParam2 não é usado. Defina esse parâmetro como zero.

No Windows 2000 e posterior, a mensagem sempre retorna MMSYSERR_NOTSUPPORTED. Essa mensagem é válida apenas para as funções waveInMessage, waveOutMessage, midiInMessage, midiOutMessage e mixerMessage . O sistema intercepta essa mensagem e retorna o valor apropriado sem enviar a mensagem para o driver do dispositivo. Para obter informações gerais sobre funções xxxMessage interceptadas pelo sistema, consulte Mensagens de dispositivo interceptadas pelo sistema.

A DRV_QUERYMAPPABLE mensagem consulta se o dispositivo especificado pode ser usado por um mapeador.

Para DRV_QUERYMAPPABLE, dwParam1 não é usado. Defina esse parâmetro como zero.

Para DRV_QUERYMAPPABLE, dwParam2 não é usado. Defina esse parâmetro como zero.

Essa mensagem é válida apenas para as funções waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, mixerMessage e auxOutMessage . O sistema intercepta essa mensagem e retorna o valor apropriado sem enviar a mensagem para o driver do dispositivo. Para obter informações gerais sobre funções xxxMessage interceptadas pelo sistema, consulte Mensagens de dispositivo interceptadas pelo sistema.

Quando um programa de aplicativo abre um mapeador em vez de um dispositivo de áudio específico, o sistema insere um mapeador entre o aplicativo e os dispositivos disponíveis. O mapeador seleciona um dispositivo apropriado mapeando os requisitos do aplicativo para um dos dispositivos disponíveis. Para obter mais informações sobre mapeados, consulte a documentação do SDK do Microsoft Windows.

A DRVM_MAPPER_CONSOLEVOICECOM_GET mensagem recupera a ID do dispositivo de comunicação de voz preferencial.

Para DRVM_MAPPER_CONSOLEVOICECOM_GET, dwParam1 é um ponteiro para a ID do dispositivo. Esse parâmetro aponta para uma variável DWORD na qual a função grava a ID do dispositivo de comunicação de voz preferencial atual. A função gravará o valor (-1) se nenhum dispositivo estiver disponível que se qualifique como um dispositivo de comunicação de voz preferencial.

Para DRVM_MAPPER_CONSOLEVOICECOM_GET, dwParam2 é um ponteiro para status sinalizadores. Esse parâmetro aponta para uma variável DWORD na qual a função grava os sinalizadores status dispositivo. No momento, apenas um bit de sinalizador está definido: DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY.

Essa mensagem é válida apenas para as funções waveInMessage e waveOutMessage . Quando um chamador chama essas duas funções com a mensagem DRVM_MAPPER_CONSOLEVOICECOM_GET, o chamador deve especificar a ID do dispositivo como WAVE_MAPPER e, em seguida, converter esse valor para o tipo de identificador apropriado. Para as funções waveInMessage, waveOutMessage, midiInMessage, midiOutMessage ou mixerMessage , o chamador deve converter a ID do dispositivo em um identificador do tipo HWAVEIN, HWAVEOUT, HMIDIIN, HMIDIOUT ou HMIXER, respectivamente. Observe que, se o chamador fornecer um identificador válido em vez de uma ID de dispositivo para esse parâmetro, a função falhará e retornará o código de erro MMSYSERR_NOSUPPORT.

O sistema intercepta essa mensagem e retorna o valor apropriado sem enviar a mensagem para o driver do dispositivo. Para obter informações gerais sobre funções xxxMessage interceptadas pelo sistema, consulte Mensagens de dispositivo interceptadas pelo sistema.

Essa mensagem fornece uma maneira de determinar qual dispositivo é preferido especificamente para comunicações de voz, ao contrário da mensagem DRVM_MAPPER_PREFERRED_GET , que determina qual dispositivo é preferencial para todas as outras funções de áudio.

Por exemplo, o dispositivo waveOut preferido para comunicações de voz pode ser o fone de ouvido em um fone de ouvido, mas o dispositivo waveOut preferido para todas as outras funções de áudio pode ser um conjunto de alto-falantes estéreo.

Quando o bit do sinalizador DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY é definido no local DWORD apontado por dwParam2, as APIs waveIn e waveOut usam apenas o dispositivo de comunicação de voz preferencial atual e não pesquisam outros dispositivos disponíveis se o dispositivo preferencial não estiver disponível. O sinalizador gerado pela chamada waveInMessage ou waveOutMessage se aplica ao dispositivo de comunicação de voz preferencial para as APIs waveIn e waveOut , independentemente de a chamada ser feita para waveInMessage ou waveOutMessage. Para obter mais informações, consulte Preferred Voice-Communications Device ID.

A DRVM_MAPPER_PREFERRED_GET mensagem recupera a ID do dispositivo de áudio preferencial.

Para DRVM_MAPPER_PREFERRED_GET, dwParam1 é um ponteiro para a ID do dispositivo. Esse parâmetro aponta para uma variável DWORD na qual a função grava a ID do dispositivo preferencial atual. A função gravará o valor (-1) se nenhum dispositivo estiver disponível que se qualifique como um dispositivo preferencial.

Para DRVM_MAPPER_PREFERRED_GET, dwParam2 é um ponteiro para status sinalizadores. Esse parâmetro aponta para uma variável DWORD na qual a função grava os sinalizadores status dispositivo. Apenas um bit de sinalizador está definido no momento (somente para chamadas waveInMessage e waveOutMessage ): DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY.

Essa mensagem é válida apenas para as funções waveInMessage, waveOutMessage e midiOutMessage . Quando o chamador chama essas funções com a mensagem DRVM_MAPPER_PREFERRED_GET, o chamador deve primeiro especificar a ID do dispositivo como WAVE_MAPPER (para waveInMessage ou waveOutMessage) ou MIDI_MAPPER (para midiOutMessage) e, em seguida, converter esse valor para o tipo de identificador apropriado. Para as funções waveInMessage, waveOutMessage ou midiOutMessage , o chamador deve converter a ID do dispositivo em um tipo de identificador HWAVEIN, HWAVEOUT ou HMIDIOUT, respectivamente. Observe que, se o chamador fornecer um identificador válido em vez de uma ID de dispositivo para esse parâmetro, a função falhará e retornará o código de erro MMSYSERR_NOSUPPORT.

O sistema intercepta essa mensagem e retorna o valor apropriado sem enviar a mensagem para o driver do dispositivo. Para obter informações gerais sobre funções xxxMessage interceptadas pelo sistema, consulte Mensagens de dispositivo interceptadas pelo sistema.

Essa mensagem fornece uma maneira de determinar qual dispositivo é preferido para funções de áudio em geral, ao contrário da mensagem DRVM_MAPPER_CONSOLEVOICECOM_GET , que determina qual dispositivo é preferido especificamente para comunicações de voz.

Quando o bit do sinalizador DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY é definido no local DWORD apontado por dwParam2, as APIs waveIn e waveOut usam apenas o dispositivo preferencial atual e não pesquisam outros dispositivos disponíveis se o dispositivo preferencial não estiver disponível. Observe que a função midiOutMessage não gera esse sinalizador – a API midiOut sempre usa apenas o dispositivo preferencial. O sinalizador que é gerado pela chamada waveInMessage ou waveOutMessage aplica-se ao dispositivo preferencial para as APIs waveIn e waveOut , independentemente de a chamada ser feita para waveInMessage ou waveOutMessage.

As funções xxxMessage aceitam esse valor no lugar de um identificador de dispositivo válido para permitir que um aplicativo determine a ID do dispositivo padrão sem primeiro precisar abrir um dispositivo. Para obter mais informações, consulte Acessando a ID do dispositivo preferencial.

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 mmeapi.h (inclua Windows.h)
Biblioteca Winmm.lib
DLL Winmm.dll

Confira também

Funções MIDI