UCC API – Unified Communications Client API – Parte 2 – Category e Category Instances

Objetivo

Nessa parte veremos o conceito de “Category” e “Category instance” da UCC API. A idéia é ilustrar o padrão existente para fazer as assinaturas e recuperar as informações do servidor.

O que é um “Category” na UCC API

Category é uma abstração de dados. Toda informação consultada do servidor OCS faz parte de uma categoria e é representada por um category instance (instância de categoria).

A forma de assinar essas informações são as mesmas independente de qual categoria é assinada. Para saber informações detalhadas de um category instance, é necessário fazer um cast da instância para a interface COM especializada desta category instance.

Um category instance pode ser:

  • Presença: estado, cartão de contato, notas, etc.:
  • Contatos e grupos
  • Containers: relacionados ao controle de acesso da publicação das category instances
  • Configurações

Você pode encontrar mais informações no MSDN: Category and category instances.

Como obter informações de categorias

A informação de uma categoria pode ser obtida através de uma assinatura. Uma assinatura é criada e é feito um Advise dos eventos nesta categoria. As informações são chamadas através de eventos numa interface de dispatch.

O primeiro passo é fazer um cast do IUccEndpoint para um IUccSubscriptionManager e criar a assinatura:

    public void SubscribeServerConfiguration()
    {
      IUccSubscriptionManager subscriptionManager = (IUccSubscriptionManager)myEndpoint.uccEndpoint;

      IUccSubscription serverConfigurationSubscription = subscriptionManager.CreateSubscription(null);

      UccPresentity presentity = serverConfigurationSubscription.CreatePresentity(myEndpoint.uccEndpoint.Uri, null);
      ComHelper.Advise<_IUccPresentityEvents>(presentity, this);
      serverConfigurationSubscription.AddPresentity(presentity);
      serverConfigurationSubscription.AddCategoryName("ServerConfiguration");
      serverConfigurationSubscription.Query(null);
    }

Esse código cria uma assinatura para uma categoria “ServerConfiguration”. Sim, as categorias são strings hard-coded (ou reservadas, para ser mais elegante).

O myEndpoint.uccEndpoint é um endpoint já inicializado (ver parte 1). O método CreateSubscription instancia um novo objeto “Subscription” (assinatura).

Os objetos “Presentity” são os que vão receber os eventos de assinatura. Eu não sei porque não é o próprio objeto subscription que recebe os eventos, mas deixo essa pergunta para os projetistas da API. Por enquanto, vamos apenas explicar o código acima. Nos fazemos um advise no _IUccPresentityEvents porque ele vai receber a notificação da assinatura no método OnCategoryContextAdded. Isso significa que o objeto presentity ouve esta categoria. Toda vez que uma categoria é adicionada ou removida ocorrerão chamadas nos eventos OnCategoryContextAdded e OnCategoryContextRemoved.

Então chamamos o método Query. Dependendo da categoria assinada (a string hard-coded) você precisa chamar o método Query ou Subscribe. A documentação da MSDN explica qual método chamar para cada uma das categorias.

Seguimos então para a chamada do OnCategoryInstanceAdded:

    public void OnCategoryContextAdded(UccPresentity pPresentity, UccCategoryContextEvent pCategoryCtxtEvent)
    {
      ComHelper.Advise<_IUccCategoryContextEvents>(pCategoryCtxtEvent.CategoryContext, this);
    }

Nós apenas fazemos um advise da interface _IUccCategoryContextEvents. Nesta interface temos os métodos OnCategoryInstanceAdded e OnCategoryInstanceRemoved. Isso significa que toda vez que um valor mudar dentro de uma categoria (ex.: um contato, uma configuração, o estado de um usuário), ocorrerá uma chamada em um destes métodos.

Por último, vamos tratar o evento OnCategoryInstanceAdded:

    public void OnCategoryInstanceAdded(IUccCategoryContext pCategoryCtxt, UccCategoryInstanceEvent pCategoryInstanceEvent)
    {
      if (pCategoryCtxt.Name == "ServerConfiguration")
      {
        IUccServerConfigurationCategory category = (IUccServerConfigurationCategory)pCategoryInstanceEvent.CategoryInstance;
        this.FocusUri = category.FocusFactory;
        MessageBox.Show(FocusUri.Value);
      }
}

Neste código, vamos apenas testar se a categoria é do tipo “ServerConfiguration”. Isso é útil quando você tem mais de uma categoria no mesmo subscription. Você pode usar o mesmo método para tratar uma ou mais assinaturas.

Então fazemos um cast do pCategoryInstanceEvent.CategoryInstance (o category instance recém adicionado no category context) para um IUccServerConfigurationCategory. Nós podemos fazer isso porque nós sabemos (através da documentação da MSDN)) que podemos fazer isso. Cada um dos category contexts possui uma interface equivalente.

Então podemos acessar os valores especializados da category instance, como o FocusUri (útil para conferências).

Informações de Contatos

O MSDN fornece um exmeplo completo que nos mostra como obter informações dos contatos, mas isso não é muito simples de compreender. Como é um pouco difícil entender o exemplo, resolvi escrever essa parte pra tentar manter a coisa simples.

Para assinar a categoria de contatos, fazemos:

    public void SubscribeContacts()
    {
      IUccSubscriptionManager subscriptionManager = (IUccSubscriptionManager)myEndpoint.uccEndpoint;

      IUccSubscription serverConfigurationSubscription = subscriptionManager.CreateSubscription(null);

      UccPresentity presentity = serverConfigurationSubscription.CreatePresentity(myEndpoint.uccEndpoint.Uri, null);
      ComHelper.Advise<_IUccPresentityEvents>(presentity, this);
      serverConfigurationSubscription.AddPresentity(presentity);
      serverConfigurationSubscription.AddCategoryName("contacts");
      serverConfigurationSubscription.Subscribe(null);
    }

É a mesma coisa do exemplo assima, apenas chamando a categoria “contacts”.

Então, na chamada do OnCategoryContextAdded:

    public void OnCategoryContextAdded(UccPresentity pPresentity, UccCategoryContextEvent pCategoryCtxtEvent)
    {
      ComHelper.Advise<_IUccCategoryContextEvents>(pCategoryCtxtEvent.CategoryContext, this);
    }

E na chamada do OnCategoryInstanceAdded:

    public void OnCategoryInstanceAdded(IUccCategoryContext pCategoryCtxt, UccCategoryInstanceEvent pCategoryInstanceEvent)
    {
      if (pCategoryCtxt.Name == "contacts")
      {
        IUccContact contact = (IUccContact)pCategoryInstanceEvent.CategoryInstance;
        MessageBox.Show("Contact: " + contact.Uri.Value + " / " + contact.Name);

        IUccSubscriptionManager subscriptionManager = (IUccSubscriptionManager)myEndpoint.uccEndpoint;
  
        IUccSubscription theContactSubscription = subscriptionManager.CreateSubscription(null);

        UccPresentity presentity = theContactSubscription.CreatePresentity(contact.Uri, null);
        ComHelper.Advise<_IUccPresentityEvents>(presentity, this);
        theContactSubscription.AddPresentity(presentity);
        theContactSubscription.AddCategoryName("contactCard");
        theContactSubscription.AddCategoryName("state");
        theContactSubscription.Subscribe(null);      
      }
  }

O que muda neste exemplo é que criamos um presentity baseado na Uri do contato para então fazermos novas assinaturas para cada um dos contatos e pegar suas informações de contato e presença.

Conclusão

Espero que com esses exemplos extremamente simplistas fique fácil entender a mecânica da assinatura das categorias. Eu escrevi essa parte apenas para ficar mais simples o entendimento de outras mais complexas, como controle de acesso a containers e criação de conferências.

O objetivo desse post é ser somente uma introdução. A documentação da MSDN é muito mais completa como uma referência.

Anúncios

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s