Nomes amigáveis para dispositivos de ponto de extremidade de áudio

No Windows Vista, Windows Server 2008 e versões posteriores do Windows, o subsistema de áudio dá suporte à noção de um dispositivo de ponto de extremidade de áudio, por exemplo, alto-falantes, fones de ouvido, microfones e players de CD. Esse conceito de pontos de extremidade de áudio ajuda a criar aplicativos de áudio amigáveis que têm interfaces de usuário que se referem aos dispositivos de ponto de extremidade que os usuários manipulam diretamente. Esses pontos de extremidade têm nomes amigáveis, como "alto-falantes", "fones de ouvido", "microfone" e "cd player" que os aplicativos podem exibir em suas interfaces do usuário. Para obter mais informações sobre dispositivos de ponto de extremidade, consulte Dispositivos de ponto de extremidade de áudio.

O subsistema de áudio modela um dispositivo PnP (Plug and Play) em um adaptador de áudio como um filtro KS. Os fluxos de dados entram e saem do filtro por meio de pinos KS. Um pino de ponte é um pino KS por meio do qual um dispositivo de ponto de extremidade de áudio se conecta a um filtro KS. Para obter mais informações sobre pinos de ponte, consulte Gráficos de filtro de áudio.

O subsistema de áudio obtém informações sobre um dispositivo de ponto de extremidade de áudio examinando as propriedades do pino de ponte ao qual o dispositivo de ponto de extremidade se conecta. Uma dessas propriedades é a propriedade de categoria de pino (KSPROPERTY_PIN_CATEGORY).

Para cada filtro KS, o driver do adaptador fornece uma tabela de estruturas PCPIN_DESCRIPTOR que descrevem as propriedades dos pinos KS no filtro. O GUID da categoria de pino é armazenado no membro KsPinDescriptor.Category da estrutura PCPIN_DESCRIPTOR. Para um pino de ponte, o valor do GUID da categoria de pino indica o tipo de ponto de extremidade que se conecta ao pino da ponte. Por exemplo, o GUID de categoria de pino KSNODETYPE_MICROPHONE indica que o pino de ponte se conecta a um microfone, o guid KSNODETYPE_SPEAKER indica que o pino de ponte se conecta aos alto-falantes e assim por diante. Os GUIDs KSNODETYPE_XXX são definidos no arquivo de cabeçalho Ksmedia.h.

Além disso, o PCPIN_DESCRIPTOR inclui um GUID que pode ser usado para identificar o pino por um nome exclusivo. Esse GUID de nome de pino é armazenado no membro KsPinDescriptor.Name da estrutura PCPIN_DESCRIPTOR. Esse guid de nome é usado pela propriedade (KSPROPERTY_PIN_NAME) para associar um nome amigável encontrado no registro ao pino.

O subsistema de áudio invoca a propriedade KSPROPERTY_PIN_NAME para associar um nome amigável a um ponto de extremidade de áudio. O KS manipula essa solicitação pesquisando primeiro uma cadeia de caracteres unicode no registro que descreve o GUID KsPinDescriptor.Name . Se o KS não encontrar uma entrada, ele pesquisará no Registro uma cadeia de caracteres unicode que descreve o GUID KsPinDescriptor.Category .

Começando com Atualização de outubro de 2018 para o Windows 10, versão 1809, ao pesquisar o registro, o KS procura pela primeira vez uma entrada na chave de software do dispositivo. Isso é criado pelo INF por meio de uma seção AddReg referenciada pela seção [Models] do INF do driver de dispositivo. A seção AddReg constrói essas entradas usando a chave HKR\MediaCategories. Isso permite que o desenvolvedor do driver crie nomes amigáveis específicos do dispositivo para GUIDs de Nome e Categoria, independentemente de o GUID ser exclusivo do dispositivo ou não.

Se uma entrada não tiver sido instalada na chave de software do dispositivo ou se o driver estiver em execução em um sistema operacional antes de Windows 10 versão 1809, o KS verificará a chave do Registro MediaCategories. Essa segunda chave é tratada como um espaço de nome global. A partir do Windows 10 versão 1809, esse espaço é reservado para definições globais e não deve ser modificado por novos drivers. Não haverá suporte para a modificação de entradas nessa chave em uma versão futura do sistema operacional.

Os dispositivos de áudio que expõem pinos com guids de categorias padrão devem incluir/precisar da caixa de entrada KS. INF ou KSCAPTUR. Registro de nome INF no INF do dispositivo. Essas INFs de caixa de entrada contêm definições de nome amigável padrão para GUIDs de categoria predefinidos que seu driver pode querer preencher. Esses são os mesmos GUIDs encontrados no membro KsPinDescriptor.Category da estrutura PCPIN_DESCRIPTOR. Por exemplo, a entrada guid da categoria KSNODETYPE_MICROPHONE tem o nome amigável associado "microfone" e a entrada de KSNODETYPE_SPEAKER guid da categoria tem o nome amigável associado "alto-falantes" e assim por diante.

Os GUIDs e nomes amigáveis para GUIDs de Categoria e Nome são armazenados no registro. Para cada par guid-name no registro, a cadeia de caracteres GUID é usada como uma subchave na chave MediaCategories. Na chave GUID, nomeie amigável um valor de cadeia de caracteres Unicode na variável "Name".

Se nenhum dos nomes amigáveis e categorias de pino definidos pelo subsistema de áudio descrever adequadamente seu dispositivo, você poderá definir sua própria categoria de pino e nomear GUIDs e associar nomes amigáveis a eles em seu INF. Para garantir que o GUID de categoria de pino seja exclusivo, use um utilitário como Uuidgen.exe para gerar o GUID. Em seguida, modifique o arquivo INF que instala o adaptador de áudio para gravar o GUID da categoria de pino e o nome amigável no registro. O exemplo de código a seguir mostra um fragmento de um arquivo INF que adiciona dois GUIDs de categoria de pino e seus nomes amigáveis associados ao registro:

[Manufacturer]
MyOEMName=Unicorn,NTamd64

[Unicorn.NTamd64]
MyDeviceName=MyDevice,Root\MyDevice

[MyDevice.NT]
Include=ks.inf, kscaptur.inf
Needs=KS.Registration, KSCAPTUR.Registration.NT
CopyFiles=MyDevice.CopyFiles
AddReg=PinNameRegistration

...

[PinNameRegistration]
HKR,%MediaCategories%\%GUID.MyNewEndpointCategory%,Name,,%Name.MyNewEndpointCategory%
HKR,%MediaCategories%\%GUID.MyNewEndpointName%,Name,,%Name.MyNewEndpointName%

...

[Strings]
MyOEMName="Unicorns Inc."
MyDeviceName="Sparkly Unicorn"
MediaCategories="MediaCategories"

GUID.MyNewEndpointCategory="{B72FBD1A-4634-4240-B207-0E6B52F3701C}"
GUID.MyNewEndpoint_2="{71DD3A5D-E303-49A0-ACEE-908634AA9520}"

Name.MyNewEndpointCategory="Unicorn"
Name.MyNewEndpointName="Fred the Unicorn"

Ambas as cadeias de caracteres GUID foram geradas por Uuidgen.exe.

Os aplicativos podem acessar as propriedades de um dispositivo de ponto de extremidade de áudio usando a interface IPropertyStore do dispositivo. A interface usa as chaves de propriedade definidas nos arquivos de cabeçalho Functiondiscoverykeys_devpkey.h e Mmdeviceapi.h para identificar as propriedades. Um aplicativo pode usar a chave de propriedade PKEY_Device_FriendlyName para recuperar o nome amigável de um dispositivo de ponto de extremidade. Para interfaces de usuário restritas por espaço, uma versão mais curta do nome amigável pode ser recuperada usando a chave de propriedade PKEY_Device_DeviceDesc . Para obter mais informações sobre essas chaves de propriedade, consulte IMMDevice::OpenPropertyStore.

Uma instância de interface IPropertyStore mantém um repositório de propriedades persistente para um dispositivo de ponto de extremidade de áudio. O repositório de propriedades copia seu valor inicial para a chave de propriedade PKEY_Device_DeviceDesc da cadeia de caracteres de nome amigável associada ao GUID da categoria de pino KS no registro. Os aplicativos podem ler o valor da propriedade PKEY_Device_DeviceDesc (a cadeia de caracteres de nome) do repositório de propriedades, mas não podem alterar o valor. No entanto, os usuários podem modificar o nome usando o painel de controle multimídia do Windows, Mmsys.cpl. Por exemplo, no Windows Vista, você pode usar as seguintes etapas para modificar o nome de um dispositivo de ponto de extremidade de renderização:

1. Para executar Mmsys.cpl, abra uma janela do Prompt de Comando e insira o seguinte comando:

   mmsys.cpl
   

   (Como alternativa, você pode executar Mmsys.cpl clicando com o botão direito do mouse no ícone do alto-falante na área de notificação, que está localizada no lado direito da barra de tarefas e clicando em Dispositivos de Reprodução.)

2. Clique no nome de um dispositivo de renderização e clique em Propriedades.

3. Na janela Propriedades, clique na guia Geral. O nome amigável deve aparecer em uma caixa de texto na parte superior da folha de propriedades. Você pode editar o nome amigável e salvar suas alterações clicando em OK.

As etapas anteriores alteram o nome amigável armazenado no repositório de propriedades do dispositivo de ponto de extremidade de áudio. Essas etapas não têm efeito sobre os nomes amigáveis associados a outros dispositivos de ponto de extremidade de áudio que pertencem à mesma categoria de pino KS. Eles também não têm nenhum efeito sobre nenhum componente que possa consultar ks diretamente para um nome.