Implementando terminais conectáveis
Os requisitos gerais para a implementação do terminal conectável são:
- O código de streaming subjacente de um terminal conectável deve corresponder aos recursos dos MSPs desejados.
- O terminal deve usar filtros DirectShow para trabalhar com a maioria dos MSPs (isso é assumido daqui em diante).
- Os terminais de áudio devem dar suporte a PCM linear mono de 8 kHz de 16 bits para a maioria dos MSPs.
- O terminal deve habilitar o marshalling threaded gratuito implementando IMarshal. O terminal pode fazer isso chamando a API COM CoCreateFreeThreadedMarshaler e agregando IMarshal para o ponteiro retornado. O destruidor do objeto terminal deve chamar IMarshal-Release>.
- O terminal deve implementar ou agregar quaisquer interfaces adicionais específicas do terminal apropriadas.
- A implementação do terminal deve ser thread-safe.
- A implementação do terminal deve #include Termmgr.h para a definição de ITTerminalControl. Isso se soma às inclusões e libs usuais necessárias para aplicativos TAPI 3 ou TAPI 3 no Windows 2000 SP1.
Notas de implementação de interface e método:
O terminal deve implementar ITTerminal (interface dupla–vtable + IDispatch).
O terminal deve retornar uma representação BSTR de um GUID que você escolheu que identifica seu tipo de terminal. Aloque o BSTR por meio de SysAllocString. Para converter de GUID para BSTR, chame StringFromCLSID, SysAllocString e CoTaskMemFree.
O terminal geralmente deve retornar TT_DYNAMIC se um aplicativo implementar o terminal. Retornar TT_STATIC também funcionará e retornar esse valor poderá ser apropriado se o terminal corresponder a um dispositivo de hardware; no entanto, fazer isso pode ser confuso para os usuários porque um terminal estático não estará presente na enumeração de terminal estático do MSP.
Se a implementação do terminal não limitar arbitrariamente o número de fluxos aos quais o terminal pode ser conectado simultaneamente, o terminal sempre deverá retornar TS_NOTINUSE.
Caso contrário, a implementação do terminal limita arbitrariamente o número de fluxos aos quais o terminal pode ser conectado por vez. Nesse caso, o terminal deve manter uma contagem de quantos fluxos ele está conectado. O terminal deve incrementar essa contagem interna em uma chamada ITTerminalControl::ConnectTerminal bem-sucedida e decrementá-la em uma chamada ITTerminalControl::D isconnectTerminal bem-sucedida. Em ITTerminal::get_State, ele deverá retornar TS_INUSE se essa contagem for igual ao número máximo de fluxos em que o terminal pode ser selecionado por vez; caso contrário, ele deve retornar TS_NOTINUSE. Observe que, se o limite for um, a contagem poderá ser simplesmente um valor booliano ou TERMINAL_STATE.
O terminal deve retornar um nome BSTR de sua escolha, alocado por meio de SysAllocString. Esse nome deve ser significativo para o usuário e deve ser localizado.
O terminal deve retornar seu tipo de mídia, seja TAPIMEDIATYPE_AUDIO ou TAPIMEDIATYPE_VIDEO.
O terminal retorna o valor de enumeração TERMINAL_DIRECTION indicando a direção do terminal. Se o terminal for bidirecional (por exemplo, uma ponte), ele deverá retornar TD_BIDIRECTIONAL.
O terminal deve implementar ITTerminalControl (somente vtable).
ITTerminalControl::get_AddressHandle
Um terminal fornecido pelo aplicativo sempre deve retornar NULL como o identificador de endereço. Isso indica ao MSP que esse terminal não foi criado em um objeto de endereço MSP específico.
ITTerminalControl::ConnectTerminal
Nessa chamada, o terminal adicionará seus filtros ao grafo especificado e os conectará uns aos outros, se aplicável. Em seguida, o terminal deve retornar os pinos expostos pelo terminal para a direção do fluxo especificada.
Um terminal que não dá suporte à conexão simultânea com vários fluxos definiria uma variável interna como TS_INUSE após a conclusão bem-sucedida desse método.
O terminal pode usar o parâmetro dwTerminalDirection dessa chamada para determinar a direção do fluxo ao qual está sendo conectado. Isso é necessário para terminais bidirecionais.
Observação
Normalmente (nas classes base msp e em todos os MSPs conhecidos), o código de fluxo MSP falhará na conexão se o terminal retornar mais de um pino de uma única chamada ConnectTerminal . Isso é bom, pois um terminal que retorna mais de um pino durante a conexão requer que o MSP tenha conhecimento especial do terminal para usar os pinos extras efetivamente.
ITTerminalControl::CompleteConnectTerminal
O terminal deve retornar apenas S_OK. O terminal também poderá fazer a inicialização pós-conexão, se necessário.
ITTerminalControl::D isconnectTerminal
O terminal deve fazer o que for necessário para desconectar o terminal do restante do grafo. Normalmente, isso envolve a remoção de todos os filtros dos terminais do grafo e a definição do estado do terminal como TS_NOTINUSE.
ITTerminalControl::RunRenderFilter
O terminal deve retornar apenas E_NOTIMPL.
ITTerminalControl::StopRenderFilter
O terminal deve retornar apenas E_NOTIMPL.