• Download do projeto de exemplo - 32 Kb
• Download código-fonte do projeto de exemplo - 35 Kb

Introdução

Ao desenvolver aplicações Palm OS que sincronizam informações com computadores através de Conduits, é comum termos a necessidade de saber quando ocorreu o último sincronismo (HotSync), se foi bem sucedido, quem foi o usuário responsável pelo último sincronismo, e até mesmo o log de todo o processo, incluindo informações individuais sobre todos Conduits executados durante o HotSync. Embora seja possível efetuar este controle através do próprio Conduit, o Palm OS oferece uma API própria para consultar informações do HotSync, e que na maioria dos casos, é suficiente, economizando tempo ao desenvolvedor.

Conceito

A função API DlkGetSyncInfo é a função responsável em obter informações do HotSync. Esta API do Palm OS, recebe seis parâmetros via referência (ByRef) e retorna as seguintes informações sobre o HotSync nestes mesmos parâmetros:

• succSyncDateP - Data e Hora do último HotSync terminado com sucesso;
• lastSyncDateP - Data e Hora do último HotSync iniciado (terminado com sucesso ou não);
• syncStateP - Código de status do sincronismo, onde cada código corresponde à um status diferente (ver tabela abaixo);
• nameBufP - Nome do usuário que executou o HotSync pela última vez;
• logBufP - Log do processo de sincronismo com as informações de Log de todos os Conduits executados;
• logLenP - Quantidade de caracteres no Log do processo de sincronismo. Equivale a Len(logBufP).

Importante: Caso o PDA/SmartPhone nunca tenha sido sincronizado, a data e hora do último sincronismo será 01/01/1904 12:00 am, que corresponde à menor data possível no HB++, e representada internamente pela constante hbLimitDateMin.

Os códigos de status retornados pela pela função DlkGetSyncInfo, através do parâmetro syncStateP, possuem os seguintes significados:

• dlkSyncStateNeverSynced - O dispositivo nunca foi sincronizado;
• dlkSyncStateInProgress - O dispositivo está sendo sincronizado neste instante;
• dlkSyncStateLostConnection - O dispositivo perdeu a conexão durante o último sincronismo;
• dlkSyncStateLocalCan - O último sincronismo foi cancelado a partir do PDA/Smartphone;
• dlkSyncStateRemoteCan - O último sincronismo foi cancelado a partir do computador;
• dlkSyncStateLowMemoryOnTD - O último sincronismo foi cancelado por falta de memória no dispositivo;
• dlkSyncStateAborted - O último sincronismo foi abortado por motivos desconhecidos;
• dlkSyncStateCompleted - O último sincronismo foi completado com sucesso;
• dlkSyncStateIncompatibleProducts - O último sincronismo foi cancelado por incompatibilidade entre o HotSync do PDA e do computador;
• dlkSyncStateNPOD - O último sincronismo foi cancelado devido à existência de senha no PDA, incompatível com o HotSync do computador.

Programação

Por tratar-se de uma função API ainda não implementada por nenhuma classe nativa do Handheld Basic, precisamos declarar a chamada da função API e as constantes utilizadas em um módulo de nossa aplicação:

Public Const dlkSizeOfHotSyncUserName    As Byte    = 41        '(41 Bytes)
Public Const dlkSizeofHotSyncLog         As Integer = 20 * 1024 '(20 Kb)

'Constantes utilizadas para identificar o status do HotSync
Public Enum eDlkSyncState
    dlkSyncStateNeverSynced             'PDA nunca foi sincronizado
    dlkSyncStateInProgress              'Está sincronizando
    dlkSyncStateLostConnection          'Perdeu a conexão
    dlkSyncStateLocalCan                'Cancelado pelo PDA
    dlkSyncStateRemoteCan               'Cancelado pelo PC
    dlkSyncStateLowMemoryOnTD           'Cancelado por falta de espaço
    dlkSyncStateAborted                 'Cancelado por motivo desconhecido
    dlkSyncStateCompleted               'Completado com sucesso
    dlkSyncStateIncompatibleProducts    'Cancelado por incompatibilidade software
    dlkSyncStateNPOD                    'Cancelado por incompatibilidade de senha
End Enum

'API FtrGet utilizada para obter características do PDA
Public Declare Function DlkGetSyncInfo(ByRef succSyncDateP As StreamMemory, ByRef lastSyncDateP As StreamMemory, ByRef syncStateP As StreamMemory, ByRef nameBufP As StreamMemory, ByRef logBufP As StreamMemory, ByRef logLenP As StreamMemory) As eDlkSyncState TRAP &HA2A9

Em seguida, para fazermos a chamada à função DlkGetSyncInfo precisamos criar variáveis e alocar memória para que a função possa utilizar e devolver as informações que precisamos. A classe StreamMemory permite a manipulação de blocos de memória de forma sequencial, efetuando a alocação e a liberação de memória automaticamente. É a classe ideal para receber parâmetros de aplicações externas, funções desenvolvidas em C/C++ e claro, funções API do Palm OS que não utilizam tipos nativos (Integer, Long, String, Date, etc...) do HB++, como é o caso da função DlkGetSyncInfo:

    'Variáveis do tipo StreamMemory que serão utilizadas
    'Para receberem os dados via referência (ByRef)
    Dim st_dtUltSucesso     As New StreamMemory
    Dim st_dtUltHotSync     As New StreamMemory
    Dim st_lUltStatus       As New StreamMemory
    Dim st_sNomeUsuario     As New StreamMemory
    Dim st_sLogBuffer       As New StreamMemory
    Dim st_lTamLogBuffer    As New StreamMemory

    'Alocação de memória para as variáveis:

    '4 bytes para armazenar a data e hora (Date)
    Write st_dtUltSucesso, Space(hbSizeOfDate)

    '4 bytes para armazenar a data e hora (Date)
    Write st_dtUltHotSync, Space(hbSizeOfDate)

    '4 bytes para armazenar o Status (Long)
    Write st_lUltStatus, Space(hbSizeOfLong)

    '41 bytes para armazenar o nome do usuário (String)
    Write st_sNomeUsuario, Space(dlkSizeOfHotSyncUserName)

    '20 kilobytes para armazenar o Log do HotSync (String)
    Write st_sLogBuffer, Space(dlkSizeofHotSyncLog) 

    '4 bytes para armazenar a quantidade de caracteres
    'contidos no Log do HotSync - Equivale a Len(sLogBuffer)
    Write st_lTamLogBuffer, Space(hbSizeOfLong)

Com as variáveis StreamMemory preparadas, podemos executar a função DlkGetSyncInfo e obter as informações do HotSync:

    'Executa a função API DlkGetSyncInfo, para obter os dados do HotSync    
		Dim lErro As Long
    lErro = DlkGetSyncInfo(st_dtUltSucesso, st_dtUltHotSync, st_lUltStatus, st_sNomeUsuario, st_sLogBuffer, st_lTamLogBuffer)

    'A função executou corretamente?
    If (lErro = 0) Then
        'Posiciona o cursor no início de cada variável
        st_dtUltSucesso.SeekToBegin
        st_dtUltHotSync.SeekToBegin
        st_lUltStatus.SeekToBegin
        st_sNomeUsuario.SeekToBegin
        st_sLogBuffer.SeekToBegin
        st_lTamLogBuffer.SeekToBegin

        'Variáveis com os tipos corretos para
        'a conversão e utilização
        Dim dtUltSucesso  As Date
        Dim dtUltHotSync  As Date
        Dim lUltStatus    As eDlkSyncState
        Dim sNomeUsuario  As String
        Dim sLogBuffer    As String
        Dim lTamLogBuffer As Long

        'Cópia do conteádo de cada variável StreamMemory
        'Para a variável "tipada" correspondente
        Read st_dtUltSucesso,  dtUltSucesso
        Read st_dtUltHotSync,  dtUltHotSync
        Read st_lUltStatus,    lUltStatus
        Read st_sNomeUsuario,  sNomeUsuario
        Read st_sLogBuffer,    sLogBuffer
        Read st_lTamLogBuffer, lTamLogBuffer
				
        '///////////////////////////////////////////////////////////////////////////////
        '//                                                                           //
        '// Neste momento possuimos todas as informações do HotSync nas variáveis:    //
        '// ----------------------------------------------------------------------    //
        '// dtUltSucesso    - Data e hora do último HotSync finalizado com sucesso    //
        '// dtUltHotSync    - Data e hora do último HotSync (finalizado ou não)       //
        '// lUltStatus      - Código correspondente ao status do último HotSync       //
        '// sNomeUsuario    - Nome do usuário que efetuou o último HotSync            //
        '// sLogBuffer      - Arquivo de Log do último HotSync                        //
        '//                                                                           //
        '///////////////////////////////////////////////////////////////////////////////
	
        'Verifica se o PDA já foi sincronizado (com sucesso) alguma vez
        If dtUltSucesso > hbLimitDateMin Then
            'Mostra a data e hora do último HotSync executado com sucesso
            MsgBox "Último HotSync executado com sucesso em " & Format(dtUltSucesso, "dd/mm/yyyy hh:nn", False)
        End If

        'Verifica se o PDA já foi sincronizado (com ou sem sucesso) alguma vez
        If lUltStatus <> dlkSyncStateNeverSynced Then
            'Mostra os dados do último HotSync (independente se terminou com sucesso ou não)
            MsgBox "O último HotSync aconteceu em " & Format(dtUltHotSync, "dd/mm/yyyy hh:nn", False)
            MsgBox "O status do último HotSync foi: " & obterDescricaoSync(lUltStatus)
            MsgBox "O usuário que executou o último HotSync foi: " & sNomeUsuario
            MsgBox "HotSync Log\n" & sLogBuffer
        Else
            'Mostra a mensagem de que o PDA nunca foi sincronizado
            MsgBox obterDescricaoSync(dlkSyncStateNeverSynced)
        End If
    Else
        'Se lErro contiver qualquer numero diferente de zero, significa que não
        'foi possível executar a função API DlkGetSyncInfo.
        MsgBox "Não foi possível consultar o HotSync. Erro " & CStr(lErro), hbMsgBoxError
    End If

E no exemplo, podemos visualizar os seguintes resultados:

Histórico

• 07/05/2007 - Primeira versão deste artigo.

Sobre o Autor

Veja o todos os artigos publicados por Caio Proiete no PDAExpert.

Artigos Relacionados

• Como obter o nome de usuário do HotSync?