×
Namespaces

Variants
Actions
(Difference between revisions)

Chamadas síncronas e assíncronas da API de serviços do WRT

From Nokia Developer Wiki
Jump to: navigation, search
hamishwillee (Talk | contribs)
m (Bot fixing redirect link)
hamishwillee (Talk | contribs)
m (Hamishwillee - Bot fixing redirect link)
Line 2: Line 2:
 
Original: [[WRT Service API Synchronous and Asynchronous calls]]
 
Original: [[WRT Service API Synchronous and Asynchronous calls]]
  
Ao trabalhar com a [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-65AAF569-D347-462B-B59A-9D7CA184AB9C.html API de serviços WRT], em geral é possível escolher entre versões '''síncronas''' e '''assíncronas''' para o mesmo método. Isto permite ter a mesma funcionalidade numa aplicação porém com um impacto ligeiramente diferente para o restante do seu código.
+
Ao trabalhar com a [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-65AAF569-D347-462B-B59A-9D7CA184AB9C.html API de serviços WRT], em geral é possível escolher entre versões '''síncronas''' e '''assíncronas''' para o mesmo método. Isto permite ter a mesma funcionalidade numa aplicação porém com um impacto ligeiramente diferente para o restante do seu código.
  
 
Este artigo descreve como manipular chamadas síncronas e assíncronas e explica quando cada tipo de chamada deve ser utilizada.
 
Este artigo descreve como manipular chamadas síncronas e assíncronas e explica quando cada tipo de chamada deve ser utilizada.
Line 13: Line 13:
 
===Valores retornados===
 
===Valores retornados===
 
Uma chamada a um método síncrono retorna um objeto contendo 2 propriedades:
 
Uma chamada a um método síncrono retorna um objeto contendo 2 propriedades:
* '''ReturnValue''': Este é o real valor retornado pelo método chamado, sendo assim você deve chegar a definição do método para saber sua estrurura. Como um exemplo: chamando o método [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-37C9E5F0-BEA9-4E0B-A40D-B953B3551007.html IDataSource.GetList()] da [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-A5853293-7B83-4CCE-9C29-B2B8F0CD8A18.html Api de serviços sobre contatos], esta propriedade irá armazenar as [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html informações de contato] atuais. Se um método não retorna qualquer informação (ex, o método [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-C7C3B541-8D28-4DC6-9003-ECF57F26C608.html ILocation.CancelNotification()] da [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-53CE4DE6-F065-4339-8C18-5C30A9540053.html API de serviços de localização]), esta propriedade não inclui o objeto retornado.
+
* '''ReturnValue''': Este é o real valor retornado pelo método chamado, sendo assim você deve chegar a definição do método para saber sua estrurura. Como um exemplo: chamando o método [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-37C9E5F0-BEA9-4E0B-A40D-B953B3551007.html IDataSource.GetList()] da [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-A5853293-7B83-4CCE-9C29-B2B8F0CD8A18.html Api de serviços sobre contatos], esta propriedade irá armazenar as [http://www.developer.nokia.com/Resources/Library/Web/ informações de contato] atuais. Se um método não retorna qualquer informação (ex, o método [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-C7C3B541-8D28-4DC6-9003-ECF57F26C608.html ILocation.CancelNotification()] da [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-53CE4DE6-F065-4339-8C18-5C30A9540053.html API de serviços de localização]), esta propriedade não inclui o objeto retornado.
* '''ErrorCode''': Um número que especifica um código de erro. Valor zero significa que não ocorreu erro. A tabela de erros completa está disponível [[http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-0A215AF3-59F0-4158-842C-0D7B030E5EA4.html aqui]
+
* '''ErrorCode''': Um número que especifica um código de erro. Valor zero significa que não ocorreu erro. A tabela de erros completa está disponível [[http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-0A215AF3-59F0-4158-842C-0D7B030E5EA4.html aqui]
* '''ErrorMessage''':Uma mensagem descrevendo o erro retornado. Messangens de erro são diferentes para cada API de serviço. Por exemplo, [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-8722B5DB-5EA6-446D-8C1D-7A0B3D8781EF.html esta] é a lista completa de mensagens de erro para a API de serviços de contados.
+
* '''ErrorMessage''':Uma mensagem descrevendo o erro retornado. Messangens de erro são diferentes para cada API de serviço. Por exemplo, [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-8722B5DB-5EA6-446D-8C1D-7A0B3D8781EF.html esta] é a lista completa de mensagens de erro para a API de serviços de contados.
  
 
===Prós e contras===
 
===Prós e contras===
Line 59: Line 59:
 
Nem todos os método suportam ambos os tipos de chamadas síncrona e assíncroa.
 
Nem todos os método suportam ambos os tipos de chamadas síncrona e assíncroa.
  
Por exemplo, o método [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-C12C81D1-13A4-4B8C-81B9-694D414A4A48.html IMessaging.GetList()] da [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-91579EE5-A608-401C-82B4-DCF1723EC7B5.html API de serviços de mensagem] suporta apenas chamadas síncronas, enquanto que o método [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-39C0BA48-E615-41B1-84FF-D4D0C4597DAB.html IDataSource.GetList()] da [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-E5684FF0-28C9-4721-9421-6B9432087086.html API de serviços de gerenciamanto de mídia] suporta apenas assíncrono.
+
Por exemplo, o método [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-C12C81D1-13A4-4B8C-81B9-694D414A4A48.html IMessaging.GetList()] da [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-91579EE5-A608-401C-82B4-DCF1723EC7B5.html API de serviços de mensagem] suporta apenas chamadas síncronas, enquanto que o método [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-39C0BA48-E615-41B1-84FF-D4D0C4597DAB.html IDataSource.GetList()] da [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-E5684FF0-28C9-4721-9421-6B9432087086.html API de serviços de gerenciamanto de mídia] suporta apenas assíncrono.
  
 
==Estudo de caso: recuperando a lista de contatos==
 
==Estudo de caso: recuperando a lista de contatos==
Line 121: Line 121:
  
 
==Leituras complementares==
 
==Leituras complementares==
* [http://library.forum.nokia.com/topic/Web_Developers_Library/GUID-4D13AF3F-4733-44E7-996F-F27A11C9D6BF_cover.html?content=GUID-65AAF569-D347-462B-B59A-9D7CA184AB9C.html WRT Service API reference]
+
* [http://www.developer.nokia.com/Resources/Library/Web/?content=GUID-65AAF569-D347-462B-B59A-9D7CA184AB9C.html WRT Service API reference]
 
* [[::Category:Web_Runtime_(WRT)|Web Runtime Wiki section]]
 
* [[::Category:Web_Runtime_(WRT)|Web Runtime Wiki section]]
* [http://www.forum.nokia.com/Develop/ Web Runtime technology landing page]
+
* [http://www.developer.nokia.com/Develop/ Web Runtime technology landing page]

Revision as of 14:15, 21 June 2011

Original: WRT Service API Synchronous and Asynchronous calls

Ao trabalhar com a API de serviços WRT, em geral é possível escolher entre versões síncronas e assíncronas para o mesmo método. Isto permite ter a mesma funcionalidade numa aplicação porém com um impacto ligeiramente diferente para o restante do seu código.

Este artigo descreve como manipular chamadas síncronas e assíncronas e explica quando cada tipo de chamada deve ser utilizada.

Contents

Chamadas síncronas

Comportamento

Chamadas síncronas requerem apenas um argumento, um objeto criteria que contém informações relevantes para o método da API de serviços chamado. Dado que a chamada é síncrona, o código de execução JavaScript irá na verdade ser bloqueado até que o método retorne.

Valores retornados

Uma chamada a um método síncrono retorna um objeto contendo 2 propriedades:

  • ReturnValue: Este é o real valor retornado pelo método chamado, sendo assim você deve chegar a definição do método para saber sua estrurura. Como um exemplo: chamando o método IDataSource.GetList() da Api de serviços sobre contatos, esta propriedade irá armazenar as informações de contato atuais. Se um método não retorna qualquer informação (ex, o método ILocation.CancelNotification() da API de serviços de localização), esta propriedade não inclui o objeto retornado.
  • ErrorCode: Um número que especifica um código de erro. Valor zero significa que não ocorreu erro. A tabela de erros completa está disponível [aqui
  • ErrorMessage:Uma mensagem descrevendo o erro retornado. Messangens de erro são diferentes para cada API de serviço. Por exemplo, esta é a lista completa de mensagens de erro para a API de serviços de contados.

Prós e contras

  • Pró: codificação simplificada: você recupera o valor esperado na mesma chamada de método sem a necessidade de implementar um mecanismo separado de callback.
  • Contra: execução bloqueada até que o método chamado retorne: Se a operação solicitada levar alguns segundos para ser executada, isto poderia causar um problema de usabilidade.

Chamdas assíncronas

Comportamento

Chamadas assíncronas requerem dois argumentos:

  • O mesmo objeto criteria passado em uma chamada síncrona.
  • uma função callback: O método a ser chamado quando o método retornar.

Sendo asssíncrono, seu código continua a sua execução normal sem a necessidade de aguardar pelo retorno do método chamado. Quando a informação retornada estiver disponível, o método de callback será chamado para manipular o retorno.

Valores retornados

O objeto retornado de uma chamada assíncrona é diferente do retornado por uma chamada síncrona e irá conter as seguintes propriedades:

  • TransactionID: Um identificador único que identifica a chamada assíncrona. Você pode utilizar este valor, por exemplo, em seu método de callback para identificar uma chamada espercífica.
  • ErrorCode: Um número que especifica um código de erro, como em uma chamada síncrona.
  • ErrorMessage: Uma mensagem descrevendo o erro retornado, como em uma chamada síncrona.

Método de callback

O método de callback é o método que é chamado quando a chamada assíncrona for finalizada e a informação a ser retornada estiver disponível. Ele deve ser definido para aceitar três argumentos:

  • transId: O ID da chamada assíncrona.
  • eventCode: Um número representando o status da callback. Valores possíveis são:
    • 2: Evento completado
    • 4: Evento de erro
    • 9: Evento em progresso
  • result: O valor real retornado pelo método chamado. Este valor é o mesmo que o retornado em uma chamada síncrona, então ele irá conter as mesmas três propriedades:
    • ReturnValue (opcional, dependendo do método chamado)
    • ErrorCode
    • ErrorMessage

Em geral as seguintes tarefas são implementadas em uma função de callback:

  • Checagem do ID de transação: para identificar a chamada assíncrona.
  • Checagem do código de evento: para verificar se o evento realmente foi finalizado (código 2), se ainda está em progresso (código 9), ou apresenta um erro (código 4).
  • Checagem do código de erro: De forma semelhante a uma chamada síncrona, antes de efetuar a manipulação das propriedades do objeto ReturnValue retornado, você deve verificar se houve algum erro na chamada do método verificando a propriedade ErrorCode.

Prós e Contras

  • Pró: execução do código não é bloqueada: Você pode fazer alo a mais (ex.: animações, outras chamadas de método) enquanto o método chamado é executado.
  • Contra: Manipulação manual da sincronia no seu código, definindo ações apropriadas dentro de um método de callback e gerenciando cuidadosamento os estados da aplicação e a UI.

Exceções

Nem todos os método suportam ambos os tipos de chamadas síncrona e assíncroa.

Por exemplo, o método IMessaging.GetList() da API de serviços de mensagem suporta apenas chamadas síncronas, enquanto que o método IDataSource.GetList() da API de serviços de gerenciamanto de mídia suporta apenas assíncrono.

Estudo de caso: recuperando a lista de contatos

Este exemplo mostra como recuperar a lista de contatos do dispositivo, usando tanto chamada síncrona quanto assíncrona. A manipualação de erros não é realizada neste exemplo, porém você deve realiza-lo em uma aplicação real.

Primeiro, instanciae o objeto Service:

var so = device.getServiceObject("Service.Contact", "IDataSource");

Agora definir o objeto criteria que irá ser usado para recuperar os contatos. Este objeto é o mesmo para chamadas síncronas e assíncronas.

var criteria = new Object();
criteria.Type = "Contact";

Então, definimos a função que irá realizar o tratamento dos contatos recuperados. Esta função pode ser igualmente utilizada para ambas as chamadas:

function handleContacts(contacts)
{
try
{
contacts.reset();
 
var contact;
 
while((contact = contacts.getNext()) != undefined)
{
//handle current contact
}
}
catch(e)
{
alert('Error while showing contacts');
}
}

Versão síncrona

A versão de chamada síncrona é bem direta. Você apenas precisa chamar o método GetList() e passar a informação retornada para o método handleContacts():

var result = so.IDataSource.GetList(criteria);
 
handleContacts(result.ReturnValue);

Versão assíncrona

Diferentemente da anterior, você deve definir um método de callback que irá ser chamado quando a chamada assíncrona ao método GetList() retornar. Em aplicações reais, você deveria também verificar os ID de transação para checar se a chamada f está realmente chamando o método de callback, e um eventCode para verificar se o evento está completo (o valor deve ser 2).

function contactsCallback(transId, eventCode, result)
{
handleContacts(result.ReturnValue);
}

Então, o método anterior (síncrono) irá mudar, tendo como segundo argumento a funçao contactsCallback. Aqui também, você deve verificar o erro retornado por esta chamada, e armazenar a propriedade TransactionID que irá ser usada no método de callback.

var result = so.IDataSource.GetList(criteria, contactsCallback);

Leituras complementares

86 page views in the last 30 days.
×