Jack Description (propiedad)
En Windows Vista y versiones posteriores, la propiedad KSPROPERTY_JACK_DESCRIPTION describe un conector de audio u otro conector físico en un adaptador de audio. El valor de la propiedad describe el color del conector, la ubicación física del conector, el tipo de conector y otras características de jack. El propósito de esta información es ayudar al usuario a encontrar la toma correcta para conectar un dispositivo de punto de conexión de audio, como un micrófono, auriculares o altavoces. Para obtener más información, consulte Dispositivos de punto de conexión de audio.
Si un filtro KS en un adaptador de audio admite la propiedad KSPROPERTY_JACK_DESCRIPTION, el panel de control multimedia de Windows, Mmsys.cpl, muestra la información del conector para los patillas de puente en el filtro. Un pin de puente representa una conexión (normalmente, un conector) a un dispositivo de punto de conexión de audio. Aunque el valor de la propiedad contiene información sobre un pin (o, en su lugar, el conector o los conectores asociados con el pin), la propiedad es una propiedad del filtro, no del pin. Para obtener más información sobre los patillas de puente, vea Gráficos de filtros de audio. Para obtener más información sobre las propiedades de filtro y las propiedades de patillas, vea Propiedades de filtro, Pin y Nodo.
Una aplicación de audio puede obtener el valor de la propiedad KSPROPERTY_JACK_DESCRIPTION para un dispositivo de punto de conexión de audio llamando al método IKsJackDescription::GetJackDescription en la API DeviceTopology. Por ejemplo, una aplicación puede usar la información del conector para ayudar al usuario a distinguir un micrófono conectado a un conector XLR verde de un micrófono conectado a un conector XLR naranja. Para obtener más información sobre la API deviceTopology, consulte Topologías de dispositivo.
El controlador de clase de audio HD de Microsoft construye automáticamente los valores de propiedad KSPROPERTY_JACK_DESCRIPTION a partir de los datos que lee de los registros de configuración del pin en un códec de audio HD. Sin embargo, cualquier controlador de audio basado en KS puede implementar compatibilidad con esta propiedad en sus tablas de automatización de filtros. Para obtener más información sobre el controlador de clase HD Audio, consulte HD Audio y UAA. Para obtener más información sobre los registros de configuración de patillas, consulte las notas del producto Directrices de configuración de patillas para dispositivos de audio de alta definición .
Un dispositivo de punto de conexión de audio puede conectarse a un pin de puente a través de uno o varios conectores. Por ejemplo, un conjunto de altavoces estéreo (dos canales) requiere un conector, pero un conjunto de altavoces de sonido envolvente 5.1 requiere tres conectores (suponiendo que cada conector controla dos de los seis canales).
La descripción de cada conector se encuentra en una estructura de KSJACK_DESCRIPTION . Por ejemplo, el valor de la propiedad KSPROPERTY_JACK_DESCRIPTION para un dispositivo de punto de conexión de audio con un conector contiene una estructura de KSJACK_DESCRIPTION, pero el valor de propiedad de un dispositivo de punto de conexión con tres conectores contiene tres estructuras de KSJACK_DESCRIPTION. En cualquier caso, la estructura o las estructuras de KSJACK_DESCRIPTION del valor de propiedad van precedidas de una estructura KSMULTIPLE_ITEM que especifica el tamaño del valor de propiedad. Para obtener más información, consulte KSPROPERTY_JACK_DESCRIPTION.
La información de Jack es especialmente útil para ayudar a los usuarios a distinguir entre los conectores que se conectan a una configuración de altavoz multicanal. En el ejemplo de código siguiente se muestra una matriz de estructuras de KSJACK_DESCRIPTION que un controlador de audio usa para describir los tres conectores para un conjunto de altavoces envolventes 5.1:
KSJACK_DESCRIPTION ar_5dot1_Jacks[] =
{
// Jack 1
{
(SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // ChannelMapping (L,R)
RGB(0,255,0), // Color (green)
eConnType3Point5mm, // ConnectionType
eGeoLocRear, // GeoLocation
eGenLocPrimaryBox, // GenLocation
ePortConnJack, // PortConnection
TRUE // IsConnected
},
// Jack 2
{
(SPEAKER_FRONT_CENTER | SPEAKER_LOW_FREQUENCY), // (C,Sub)
RGB(0,0,255), // (red)
eConnType3Point5mm,
eGeoLocRear,
eGenLocPrimaryBox,
ePortConnJack,
TRUE
},
// Jack 3
{
(SPEAKER_SIDE_LEFT | SPEAKER_SIDE_RIGHT), // (SL,SR)
RGB(0,255,255), // (yellow)
eConnType3Point5mm,
eGeoLocRear,
eGenLocPrimaryBox,
ePortConnJack,
TRUE
}
};
Si el hardware de audio puede detectar si el dispositivo está conectado, el controlador actualiza dinámicamente el valor de este miembro para indicar si el dispositivo está conectado actualmente (TRUE) o desconectado (FALSE)
En el ejemplo de código anterior, el miembro IsConnected de cada elemento de matriz se establece en TRUE para indicar que el dispositivo de punto de conexión está conectado al conector. Sin embargo, si el hardware carece de detección de presencia de jack, IsConnected siempre debe establecerse en TRUE, si hay un dispositivo conectado al conector. Para quitar la ambigüedad resultante de este significado dual del valor devuelto TRUE , una aplicación cliente puede llamar a IKsJackDescription2::GetJackDescription2 para leer la marca JackCapabilities de la estructura KSJACK_DESCRIPTION2 . Si esta marca tiene el JACKDESC2_PRESENCE_DETECT_CAPABILITY bit establecido, indica que el punto de conexión sí admite la detección de presencia de jack. En ese caso, el valor del miembro IsConnected se puede interpretar como una reflexión precisa del estado de inserción del conector.
La macro RGB que aparece en las estructuras anteriores se define en el archivo de encabezado Wingdi.h en Windows SDK.
Además, se puede usar una matriz de descripciones de jack para mostrar que dos o más conectores son funcionalmente equivalentes entre sí. En el ejemplo de código siguiente, el controlador de audio combina las descripciones del conector para un conector RCA amarillo y para un conector óptico digital negro en una matriz para indicar al usuario que los dos conectores llevan la misma señal:
KSJACK_DESCRIPTION ar_SPDIF_Jacks[] =
{
// Jack 1
{
(SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // ChannelMapping (L,R)
RGB(0,255,255), // Color (yellow)
eConnTypeRCA, // ConnectionType (RCA)
eGeoLocRear, // GeoLocation
eGenLocPrimaryBox, // GenLocation
ePortConnJack, // PortConnection
TRUE // IsConnected
},
// Jack 2
{
(SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // (L,R)
RGB(0,0,0), // (black)
eConnTypeOptical, // (optical)
eGeoLocRear,
eGenLocPrimaryBox,
ePortConnJack,
TRUE
}
};
En el ejemplo de código anterior, los valores de los miembros ChannelMapping de las dos estructuras de KSJACK_DESCRIPTION son idénticos.
El controlador de ejemplo MSVAD "Simple" del WDK (en el directorio de ejemplo Src\Audio\Msvad\Simple) se puede adaptar para admitir la propiedad KSPROPERTY_JACK_DESCRIPTION. Este controlador de ejemplo es conveniente para demostrar el uso de la propiedad porque no requiere hardware real. Por lo tanto, se puede instalar en cualquier equipo que ejecute Windows. (Sin embargo, solo Windows Vista y los sistemas operativos posteriores proporcionan compatibilidad completa con la propiedad KSPROPERTY_JACK_DESCRIPTION). Para obtener más información sobre este ejemplo, consulta Ejemplos del Kit de controladores de Windows.
El filtro de topología para el ejemplo de MSVAD simple define tres patillas de puente. Estos pines se enumeran en la tabla siguiente.
Id. de patilla | Descripción |
---|---|
KSPIN_TOPO_SYNTHIN_SOURCE |
Conector de entrada MIDI |
KSPIN_TOPO_MIC_SOURCE |
Conector de entrada del micrófono |
KSPIN_TOPO_LINEOUT_DEST |
Conector de salida del altavoz estéreo |
En el resto de este tema se explica cómo modificar el controlador de ejemplo de MSVAD simple para proporcionar la información de jack para los tres pines de puente.
En primer lugar, se puede especificar la información de jack de estos pines de la siguiente manera:
// Describe MIDI input jack (pin ID = KSPIN_TOPO_SYNTHIN_SOURCE).
static KSJACK_DESCRIPTION SynthIn_Jack[] =
{
{
0, // ChannelMapping
RGB(255,255,0), // Color (cyan)
eConnType3Point5mm, // ConnectionType
eGeoLocRear, // GeoLocation
eGenLocPrimaryBox, // GenLocation
ePortConnJack, // PortConnection
TRUE // IsConnected
}
};
// Describe microphone jack (pin ID = KSPIN_TOPO_MIC_SOURCE).
static KSJACK_DESCRIPTION MicIn_Jack[] =
{
{
0,
RGB(0,128,255), // (orange)
eConnType3Point5mm,
eGeoLocFront,
eGenLocPrimaryBox,
ePortConnJack,
TRUE
}
};
// Describe stereo speaker jack (pin ID = KSPIN_TOPO_LINEOUT_DEST).
static KSJACK_DESCRIPTION LineOut_Jack[] =
{
{
(SPEAKER_FRONT_LEFT | SPEAKER_FRONT_RIGHT), // ChannelMapping (L,R)
RGB(0,255,0), // (green)
eConnType3Point5mm,
eGeoLocRear,
eGenLocPrimaryBox,
ePortConnJack,
TRUE
}
};
En el ejemplo de código anterior se establecen los miembros ChannelMapping para los dos pines de captura en 0. Solo los pines de representación analógica deben tener valores channelMapping distintos de cero.
La modificación principal del ejemplo de MSVAD simple es agregar el siguiente controlador de propiedades a la implementación de la minipuerto de topología en el archivo de ejemplo Mintopo.cpp:
#define ARRAY_LEN(a) sizeof(a)/sizeof(a[0]);
#define MAXIMUM_VALID_PIN_ID KSPIN_TOPO_WAVEIN_DEST
NTSTATUS
CMiniportTopology::PropertyHandlerJackDescription(
IN PPCPROPERTY_REQUEST PropertyRequest)
{
PAGED_CODE();
ASSERT(PropertyRequest);
DPF_ENTER(("[PropertyHandlerJackDescription]"));
NTSTATUS ntStatus = STATUS_INVALID_DEVICE_REQUEST;
ULONG nPinId = (ULONG)-1;
if (PropertyRequest->InstanceSize >= sizeof(ULONG))
{
nPinId = *((PULONG)(PropertyRequest->Instance));
if (nPinId > MAXIMUM_VALID_PIN_ID)
{
ntStatus = STATUS_INVALID_PARAMETER;
}
else if (PropertyRequest->Verb & KSPROPERTY_TYPE_BASICSUPPORT)
{
ntStatus = PropertyHandler_BasicSupport(
PropertyRequest,
KSPROPERTY_TYPE_BASICSUPPORT | KSPROPERTY_TYPE_GET,
VT_ILLEGAL);
}
else
{
PKSJACK_DESCRIPTION pJack = NULL;
ULONG cJacks = 0;
switch (nPinId)
{
case KSPIN_TOPO_SYNTHIN_SOURCE:
pJack = SynthIn_Jack;
cJacks = ARRAY_LEN(SynthIn_Jack);
break;
case KSPIN_TOPO_MIC_SOURCE:
pJack = MicIn_Jack;
cJacks = ARRAY_LEN(MicIn_Jack);
break;
case KSPIN_TOPO_LINEOUT_DEST:
pJack = LineOut_Jack;
cJacks = ARRAY_LEN(LineOut_Jack);
break;
default:
break;
}
ULONG cbNeeded = sizeof(KSMULTIPLE_ITEM) +
sizeof(KSJACK_DESCRIPTION) * cJacks;
if (PropertyRequest->ValueSize == 0)
{
PropertyRequest->ValueSize = cbNeeded;
ntStatus = STATUS_BUFFER_OVERFLOW;
}
else if (PropertyRequest->ValueSize < cbNeeded)
{
ntStatus = STATUS_BUFFER_TOO_SMALL;
}
else if (PropertyRequest->Verb & KSPROPERTY_TYPE_GET)
{
PKSMULTIPLE_ITEM pMI = (PKSMULTIPLE_ITEM)PropertyRequest->Value;
pMI->Size = cbNeeded;
pMI->Count = cJacks;
// Copy jack description structure into Value buffer.
// RtlCopyMemory correctly handles the case Length=0.
PKSJACK_DESCRIPTION pDesc = (PKSJACK_DESCRIPTION)(pMI + 1);
RtlCopyMemory(pDesc, pJack, pMI->Size * pMI->Count);
ntStatus = STATUS_SUCCESS;
}
}
}
return ntStatus;
}
NTSTATUS
PropertyHandler_TopoFilter(IN PPCPROPERTY_REQUEST PropertyRequest)
{
PAGED_CODE();
ASSERT(PropertyRequest);
DPF_ENTER(("[PropertyHandler_TopoFilter]"));
// PropertyRequest structure is filled by PortCls.
// MajorTarget is a pointer to miniport object for miniports.
//
NTSTATUS ntStatus = STATUS_INVALID_DEVICE_REQUEST;
PCMiniportTopology pMiniport = (PCMiniportTopology)PropertyRequest->MajorTarget;
if (IsEqualGUIDAligned(*PropertyRequest->PropertyItem->Set, KSPROPSETID_Jack) &&
(PropertyRequest->PropertyItem->Id == KSPROPERTY_JACK_DESCRIPTION))
{
ntStatus = pMiniport->PropertyHandlerJackDescription(PropertyRequest);
}
return ntStatus;
}
El ejemplo de código anterior hace referencia a las tres variables de KSJACK_DESCRIPTION ( SynthIn_Jack, MicIn_Jack y LineOut_Jack ) que se definieron anteriormente. Si el cliente consulta el filtro para la descripción del conector de un pin válido, pero uno que no es un pin de puente (y, por lo tanto, no tiene ninguna descripción de jack), la consulta se realiza correctamente (con el código de estado STATUS_SUCCESS), pero el controlador de propiedades devuelve una descripción de jack vacía que consta de una estructura de KSMULTIPLE_ITEM y nada más. Si el cliente especifica un identificador de pin no válido (que identifica un pin inexistente), el controlador devuelve el código de estado STATUS_INVALID_PARAMETER.
Se requieren dos modificaciones adicionales en el ejemplo de MSVAD simple para admitir la propiedad KSPROPERTY_JACK_DESCRIPTION. Son las siguientes:
Agregue la declaración del método PropertyHandlerJackDescription en el ejemplo de código anterior a la definición de clase CMiniportTopology en el archivo de encabezado Mintopo.h.
Implemente una tabla de automatización para el filtro de topología y cargue la dirección de esta tabla en el miembro AutomationTable de la estructura de PCFILTER_DESCRIPTOR en el archivo de encabezado Toptable.h. Esta estructura se denomina MiniportFilterDescriptor.
Para implementar la tabla de automatización para el filtro, inserte el código siguiente en el archivo de encabezado Toptable.h (antes de la definición de MiniportFilterDescriptor):
static PCPROPERTY_ITEM PropertiesTopoFilter[] =
{
{
&KSPROPSETID_Jack,
KSPROPERTY_JACK_DESCRIPTION,
KSPROPERTY_TYPE_GET | KSPROPERTY_TYPE_BASICSUPPORT,
PropertyHandler_TopoFilter
}
};
DEFINE_PCAUTOMATION_TABLE_PROP(AutomationTopoFilter, PropertiesTopoFilter);
En el ejemplo de código anterior, el miembro Handler de la estructura PCPROPERTY_ITEM contiene un puntero de función al controlador de propiedades que se agregó a Mintopo.cpp en un paso anterior. Para que el controlador de propiedades sea accesible desde el archivo de encabezado, inserte una declaración de función extern para PropertyHandler_TopoFilter al principio del archivo de encabezado.
Para obtener más información sobre la propiedad de descripción de jack, vea Descripciones de Jack para subdispositivos de audio dinámico.