Compartilhar via

Implementando um indicador de progresso

  • Artigo

Aplica-se a: Outlook 2013 | Outlook 2016

Muitas das operações iniciadas pelos clientes levam um tempo significativo. Um dos parâmetros de entrada para essas operações potencialmente longas é um ponteiro para um objeto de progresso – um objeto que implementa a interface IMAPIProgress : IUnknown . Objetos de progresso controlam a aparência e a exibição de indicadores de progresso e são implementados por clientes e por MAPI. Você pode escolher se deve ou não implementar um objeto de progresso. A implementação mapi está disponível para provedores de serviços usarem se você optar por não fornecer uma implementação.

Os objetos de progresso funcionam com os seguintes dados:

  • Um valor mínimo global que, quando o método IMAPIProgress::P rogress é chamado, deve ser menor ou igual ao valor do parâmetro ulValue . No início da operação, ulValue será igual a esse valor mínimo.

  • Um valor máximo global que, quando o método IMAPIProgress::P rogress é chamado, deve ser maior ou igual ao parâmetro ulValue . No final da operação, ulValue será igual a esse valor máximo.

  • Um valor de sinalizadores que indica se o progresso corresponde a um item de nível superior ou inferior.

  • Um valor que indica o nível atual de progresso para a operação.

  • O número dos itens processados atualmente em relação ao total.

  • O número total de itens a serem processados durante a operação.

Os valores mínimos e máximos representam o início e o fim da operação no formulário numérico. Use 1 para o valor mínimo inicial e 1000 para o valor máximo inicial, passando esses valores para provedores de serviços nos métodos IMAPIProgress::GetMin e IMAPIProgress::GetMax . Os provedores de serviço redefinem esses valores quando chamam IMAPIProgress::SetLimits.

O valor dos sinalizadores é usado pelos provedores de serviços para determinar como eles devem definir os outros valores. Inicialize o valor de sinalizadores para MAPI_TOP_LEVEL e retorne esse valor na implementação do GetFlags até que o provedor de serviços o redefine chamando SetLimits.

Na implementação do método SetLimits , salve cópias locais de cada um dos parâmetros: lpulMin, lpulMax e lpulFlags. Esses valores devem estar prontamente disponíveis quando um provedor de serviços chama seus métodos GetMin, GetMax ou GetFlags .

Para atualizar a exibição do indicador de progresso, os provedores de serviços chamam o método IMAPIProgress::P rogress . Há três parâmetros para esse método: um valor, uma contagem e um total. Use o primeiro parâmetro, ulValue, para exibir o indicador de progresso. O parâmetro ulValue é o indicador de progresso e será igual ao ulMin global somente no início da operação e igual ao ulMax global somente na conclusão da operação.

Use o segundo e o terceiro parâmetros, ulCount e ulTotal, se estiverem disponíveis, para exibir uma mensagem opcional, como "5 itens concluídos em 10". Se o segundo e o terceiro parâmetros forem definidos como 0, você poderá escolher se deve ou não alterar visualmente o indicador de progresso. Alguns provedores de serviços definem esses parâmetros como zeros para indicar que estão processando um subobjeto cujo progresso é monitorado em relação a um objeto pai. Nessa situação, faz sentido alterar a exibição somente quando o objeto pai relata o progresso. Alguns provedores de serviços passam zeros para esses parâmetros sempre.