Referência MQL5Manipulação de eventosOnBookEvent

OnBookEvent

É chamada em indicadores e EAs quando ocorre o evento BookEvent. A função é projetada para processar alterações no livro de ofertas (Depth of Market).

void  OnBookEvent(
   const string&  symbol         // símbolo
   );

Parâmetros

symbol

[in] Nome do instrumento financeiro em que ocorre o evento BookEvent

Valor retornado

Sem valor retornado

Observação

Para receber eventos BookEvent em qualquer símbolo, basta fazer uma pré-assinatura a fim de receber esses eventos para este símbolo usando a função MarketBookAdd(). Para cancelar a assinatura de recebimento do evento BookEvent num símbolo específico, você deve chamar a função MarketBookRelease().

O evento BookEvent é difundido no gráfico. Isso significa que basta que um aplicativo no gráfico assine a recepção do evento BookEvent usando a função MarketBookAdd, para todos os outros indicadores e EAs - que estão sendo executados neste gráfico e que têm o manipulador OnBookEvent() - receberem esse evento. Por isso, você precisa analisar o nome do símbolo que é transferido para o manipulador OnBookEvent() como um parâmetro symbol.

Para todos os aplicativos em andamento no mesmo gráfico, são executados contadores separados para receber eventos BookEvent na seção de símbolos. Isso significa que em cada gráfico pode haver assinaturas de diferentes símbolos, e para cada símbolo existe seu próprio contador. Assinatura e remoção de assinatura de eventos BookEvent alteram o contador de assinaturas só dos símbolos especificados, apenas dentro do mesmo gráfico. Isso significa que, em dois gráficos adjacentes, pode haver assinaturas de eventos BookEvent para o mesmo símbolo, mas com valores diferentes para o contador de assinaturas.

O valor inicial do contador de assinaturas é zero. Após cada chamada da MarketBookAdd(), o contador de assinaturas para o símbolo especificado neste gráfico é aumentado em 1 (não é necessário o símbolo do gráfico e o símbolo na MarketBookAdd() coincidirem). Após a chamada da MarketBookRelease(), o contador de assinaturas para o símbolo especificado dentro do gráfico é reduzido em 1. A transmissão de eventos BookEvent em qualquer símbolo dentro do gráfico continua até que o contador de assinaturas para este símbolo se torne zero. Portanto, é importante que cada programa MQL5 contendo chamadas da MarketBookAdd(), ao concluir seu trabalho, corretamente cancele a recepção de eventos para cada símbolo com a ajuda da MarketBookRelease(). Para isso, basta que - para cada chamada - o número de chamadas da MarketBookAdd() e da MarketBookRelease() seja par durante toda a vida útil do programa MQL5. Usar sinalizadores ou próprios contadores de assinaturas dentro do programa permite trabalhar com segurança com eventos BookEvent e impede a remoção de assinaturas de recepção desse evento em programas de terceiros dentro do mesmo gráfico.

Os eventos BookEvent nunca são ignorados e sempre são enfileirados, mesmo que o processamento do evento BookEvent anterior ainda não tenha sido concluído. Deve-se ter em mente que os eventos BookEvent são entregues por eles mesmos e não levam consigo o status do livro de ofertas. Isso significa que a chamada da MarketBookGet() a partir do manipulador OnBookEvent() permite - em vez do status do livro de ofertas que causou o envio do evento BookEvent - obter o status atual do livro de ofertas no momento da chamada. Para garantir que todos os status exclusivos sejam obtidos, a função OnBookEvent() deve ser o mais rápida possível.

Exemplo

//+------------------------------------------------------------------+
//|                                           OnBookEvent_Sample.mq5 |
//|                        Copyright 2018, MetaQuotes Software Corp. |
//|                                             https://www.mql5.com |
//+------------------------------------------------------------------+
#property copyright "Copyright 2000-2024, MetaQuotes Ltd."
#property link      "https://www.mql5.com/pt/articles/2635"
#property version   "1.00"
#property description "Exemplo de medição da velocidade de atualização do livro de ofertas usando OnBookEvent()"
#property description "Código é retirado do artigo https://www.mql5.com/pt/articles/2635"
//--- parâmetros de entrada
input ulong ExtCollectTime   =30;  // tempo de teste em segundos
input ulong ExtSkipFirstTicks=10;  // número de ticks ignorados no início
//--- sinalizador da presença de assinatura de recepção de eventos BookEvent
bool book_subscribed=false;
//--- matriz para receber solicitações a partir do livro de ofertas
MqlBookInfo  book[];
//+------------------------------------------------------------------+
//| Expert initialization function                                   |
//+------------------------------------------------------------------+
int OnInit()
  {
//--- definimos o início
   Comment(StringFormat("Aguardamos a recepção dos primeiros %I64u ticks",ExtSkipFirstTicks));
   PrintFormat("Aguardamos a recepção dos primeiros %I64u ticks",ExtSkipFirstTicks);
//--- ativamos a transmissão do livro de ofertas
   if(MarketBookAdd(_Symbol))
     {
      book_subscribed=true;
      PrintFormat("%s: Função MarketBookAdd(%s) retornou true",__FUNCTION__,_Symbol);
     }
   else
      PrintFormat("%s: Função MarketBookAdd(%s) retornou false! GetLastError()=%d",__FUNCTION__,_Symbol,GetLastError());
//--- inicialização bem-sucedida
   return(INIT_SUCCEEDED);
  }
//+------------------------------------------------------------------+
//| Deinitialize expert                                              |
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
  {
//--- exibimos o código de motivo da desinicialização
   Print(__FUNCTION__,": Código de motivo da desinicialização = ",reason);
//--- cancelamos nossa assinatura de recepção de eventos a partir do livro de ofertas
   if(book_subscribed)
     {
      if(!MarketBookRelease(_Symbol))
         PrintFormat("%s: MarketBookRelease(%s) retornou false! GetLastError()=%d",_Symbol,GetLastError());
      else
         book_subscribed=false;
     }
//---
  }
//+------------------------------------------------------------------+
//| BookEvent function                                               |
//+------------------------------------------------------------------+
void OnBookEvent(const string &symbol)
  {
   static ulong starttime=0;             // tempo de início do teste
   static ulong tickcounter=0;           // contador de atualização do livro de ofertas
//--- trabalhamos com eventos do livro de ofertas somente se ele tiver sido assinado por nós mesmos
   if(!book_subscribed)
      return;
//--- consideramos atualizações apenas do próprio símbolo
   if(symbol!=_Symbol)
      return;
//--- pulamos os primeiros ticks para a limpeza primária da fila e para aquecimento
   tickcounter++;
   if(tickcounter<ExtSkipFirstTicks)
      return;
//--- lembramo-nos do tempo de início
   if(tickcounter==ExtSkipFirstTicks)
      starttime=GetMicrosecondCount();
//--- consultamos os dados do livro de ofertas
   MarketBookGet(symbol,book);
//--- quando se deve parar?
   ulong endtime=GetMicrosecondCount()-starttime;
   ulong ticks  =1+tickcounter-ExtSkipFirstTicks;
// quanto tempo passou em microssegundos desde o início do teste?
   if(endtime>ExtCollectTime*1000*1000)
     {
      PrintFormat("%I64u ticks for %.1f seconds: %.1f ticks/sec ",ticks,endtime/1000.0/1000.0,ticks*1000.0*1000.0/endtime);
      ExpertRemove();
      return;
     }
//--- exibição dos contadores no campo de comentários
   if(endtime>0)
      Comment(StringFormat("%I64u ticks for %.1f seconds: %.1f ticks/sec ",ticks,endtime/1000.0/1000.0,ticks*1000.0*1000.0/endtime));
  }

Veja também

MarketBookAdd, MarketBookRelease, MarketBookGet, OnTrade, OnTradeTransaction, OnTick, Função de manipulação de eventos, Execução do programa, Eventos do terminal do cliente

OnTradeTransaction

OnChartEvent