Tutorial FTC C++ 1.4.1

Table of Contents

Introdução
Visão geral
Desenvolvimento
Build da demo através da ferramenta Boost Build - Linux
Exemplo dos comandos de execução da demo em uma máquina Unix.
Servidor
Cliente
Referencia do FTC C++

O FTC (File Transfer Channel) é um protocolo de camada de aplicação que tem por objetivo forcener uma solução programática e eficiente para a transferência de dados que possuem uma ordem de grandeza de gigabytes com relação ao tamanho. O protocolo foi desenvolvido considerando como contexto um ambiente distribuído e heterogêneo.

A finalidade deste documento é auxiliar um desenvolvedor C++ na utilização da biblioteca FTC C++ no seu projeto. O tutorial está estruturado em três seções:

  1. Introdução: O que é e para que serve o FTC.
  2. Visão geral: Como funciona e quais são os principais conceitos.
  3. Desenvolvimento: Como usar a biblioteca FTC C++ usando-se como guia a demo que acompanha o pacote.

Recomenda-se que o desenvolvedor leia todas as seções na ordem apresentada.

O principal conceito do FTC é o canal de fluxo de dados. Através desta abstração o usuário consegue ofertar ou consumir um dado genérico em um ambiente distribuído. O usuário provedor abre um canal conforme a fonte do dado e fornece de uma forma externa ao protocolo a localização e a chave de acesso deste canal para o usuário consumidor, que por sua vez utiliza estas informações para abrir uma comunicação com o canal e realizar as devidas operações sob o dado em questão. Um canal pode suportar as seguintes operações:

  • OPEN_READ_ONLY: Abertura de um dado somente para leitura.
  • OPEN_READ_WRITE: Abertura de um dado para leitura e escrita.
  • CLOSE: Fechamento de um dado.
  • SET_SIZE: Definir um tamanho para um dado.
  • GET_SIZE: Obter o tamanho de um dado.
  • SET_POSITION: Definir uma posição de acesso dentro de um dado.
  • GET_POSITION: Obter a posição de acesso atual dentro de um dado.
  • READ: Leitura sob um dado.
  • WRITE: Escrita de dados.
  • KEEP_ALIVE: Manter a conexão ativa.

A abstração do canal provida pelo FTC é genérica com relação ao tipo do dado manipulado. O usuário pode estender esta abstração para contemplar tipos que não são fornecidos pela biblioteca FTC C++, como por exemplo uma especialização destinada a manipulação de dados do tipo streaming. Além da abstração genérica, a biblioteca fornece ao programador uma especialização do canal para dados representados através de arquivos.

O FTC utiliza a dupla de protocolos de comunicação TCP/IP, e portanto a localização de um canal é determinada através do nome ou endereço IP de uma máquina e uma porta TCP. A chave de acesso é uma sequência opaca de bytes que deve ser negociada entre o provedor e consumidor para uma determinada conexão que deve ser utilizada por um determinado espaço de tempo. A chave de acesso é invalidada e deve ser renegociada caso expire o intervalo de tempo ou uma desconexão ocorra.

O primeiro passo é realizar o download do pacote da biblioteca FCT C++ 1.4.1 através do link https://jira.tecgraf.puc-rio.br/confluence/display/FTC/Download. Esta versão depende da biblioteca Boost 1.51.0 ( http://www.boost.org). Os arquivos necessários do Boost , que são os headers e as bibliotecas, estão contidos no pacote em uma pasta chamada boost.

Os arquivos da biblioteca do FTC que são utilizados no build estão disponíveis nas pastas include e lib. A primeira armazena os arquivos do tipo header e a segunda o build da biblioteca nas versões estática e dinâmica.

Recomenda-se que usuário compile a demo contida no pacote e a execute seguindo o passo-a-passo apresentado abaixo. Devido as diversas ferramentas e metodologias de build existentes para C++, este tutorial somente apresenta o passo-a-passo para a compilação via Boost Build, que é a ferramenta de build utilizada no projeto do desenvolvimento do FTC C++.

A demo contida no pacote da biblioteca implementa um servidor e um cliente que utilizam o FTC para a transferência de arquivos. O servidor recebe como parâmetro o caminho para um arquivo e abre um canal de fluxo de dados em um determinado par de endereço e porta. O cliente recebe por parâmetro este par de endereço e porta, o caminho de um arquivo local, a chave de acesso disponibilizada pelo servidor e o tipo da operação a ser realizada, que pode ser uma leitura ou escrita. No modo leitura o cliente lê o conteúdo do arquivo disponibilizado pelo servidor e escreve no arquivo local. No modo de escrita o conteúdo do arquivo local é escrito no arquivo disponibilizado pelo servidor.

A próxima seção apresenta um passo-a-passo para construção e utilização dos arquivos necessários para se realizar o build da demo através do Boost Build. A seção posterior exemplifica a execução da demo e as duas últimas seções são dedicadas ao entendimento da implementação da demo.

  1. Obter o pacote do Boost Build V2 através do endereço http://www.boost.org/boost-build2. Exemplo usando o utilitário wget:

    $wget http://www.boost.org/boost-build2/boost-build.zip
    
  2. Extrair o pacote, entrar no diretório raiz do pacote e executar o script bootstrap.sh.

    $unzip boost-build.zip
    $cd boost-build
    $./bootstrap.sh
    
  3. Executar o comando de instalação substituindo a variável INSTALL_DIR pelo caminho desejado.

    $./b2 install --prefix=$INSTALL_DIR
    
  4. Criar um arquivo Jamroot na pasta demo do pacote FTC C++ com o seguinte conteúdo:

    exe demo_client
      : client/source/Config.cpp
        client/source/Client.cpp
        /ftc//ftc
        /boost//system
        /boost//chrono
        /boost//thread
        /boost//program_options
        /boost//filesystem
        /boost//date_time
      : <include>client/include
        <threading>multi
    ;
    
    exe demo_server
      : server/source/Config.cpp
        server/source/Server.cpp
        /ftc//ftc
        /boost//system
        /boost//chrono
        /boost//thread
        /boost//program_options
        /boost//filesystem
        /boost//date_time
      : <include>server/include
        <threading>multi
    ;
    
  5. Criar um arquivo project-config.jam na pasta demo do pacote FTC C++ com o seguinte conteúdo:

    project boost
      : requirements <include>../include/boost
    ;
    
    lib system
     :
     : <name>boost_system-mt-d
       <search>../lib
     ;
    
    lib chrono
     :
     : <name>boost_chrono-mt-d
       <search>../lib
     ;
    
    lib thread
     :
     : <name>boost_thread-mt-d
       <search>../lib
     ;
    
    lib program_options
     :
     : <name>boost_program_options-mt-d
       <search>../lib
     ;
    
    lib filesystem
     :
     : <name>boost_filesystem-mt-d
       <search>../lib
     ;
    
    lib date_time
     :
     : <name>boost_date_time-mt-d
       <search>../lib
     ;
    
    project ftc
      : requirements <include>../include
    ;
    
    lib ftc
      :
      : <name>ftc-1.4.1.1-mt-s-d
        <search>../lib
    ;
    
    [Important]Important

    A configuração acima considera o uso da versão 1.4.1.1 do FTC C++, verifique a sua versão e se necessário altere o nome da biblioteca FTC para a versão em uso na declaração lib ftc.

  6. Entrar no diretório demo que está na raiz do pacote FTC C++ e executar o Boost Build através do local de instalação definido acima com um parâmetro de depuração para o processo de compilação.

    $ $INSTALL_DIR/bin/b2 -d+2 link=static
    
  7. Os executáveis da demo são disponibilizados na pasta demo/bin seguindo uma estrutura de sub-diretórios adotada pelo Boost Build conforme o compilador e sua versão, e, as opções de build, como por exemplo se é o build é singlethread ou multithread. No caso do GCC versão 4.1.2, os executáveis estariam exatamente no diretório demo/bin/gcc-4.1.2/debug/link-static/threading-multi.
  1. Execução do processo servidor para ofertar o arquivo /path/to/myfile no endereço localhost e porta 25.555:

    $demo_server -a /path/to/myfile
    

    Exemplo de saída esperada:

    Gerando identificador único para o arquivo: /path/to/myfile
    Identificador único para arq. gerado (hex): 6A1B6D58146C4CD3802F70A528DDCF6E
    Servidor rodando em: 0.0.0.0:25555
    Digite Ctrl + C para terminar
    
    A sequência hexadecimal exibida corresponde a chave de acesso para o arquivo disponibilizado.
  2. Execução do processo cliente para consumir todo o conteúdo do arquivo disponibilizado pelo servidor e escrever os dados no arquivo de saída /path/to/outfile:

    $demo_client -f /path/to/outfile -k 6A1B6D58146C4CD3802F70A528DDCF6E -o READ
    

    O parâmetro -k informa a chave de acesso fornecida pelo servidor. Exemplo de saída esperada:

    Rodando em: localhost:25555
    Operacao: READ
    Transferindo 9 bytes do canal remoto
    Transferidos 9 bytes
    Fechando conexao com o servidor...
    
  3. Execução do processo cliente para escrever todo o conteúdo do arquivo local no arquivo disponibilizado pelo servidor:

    $demo_client -f /path/to/infile -k 6A1B6D58146C4CD3802F70A528DDCF6E -o WRITE
    

    O parâmetro -k informa a chave de acesso fornecida pelo servidor. Exemplo de saída esperada:

    Rodando em: localhost:25555
    Operacao: WRITE
    Transferindo 9 bytes do canal remoto
    Transferidos 9 bytes
    Fechando conexao com o servidor...
    
  1. Antes de se abrir canais de acesso para arquivos fornecidos pelo usuário, um servidor FTC precisa ser instanciado:

    FTCServer server(provider, config);
    

    A classe FTCServer, que representa um servidor FTC, é descrita em include/ftc/FTCServer.h. O construtor desta classe espera receber como primeiro parâmetro uma referência para DataChannelProvider e como segundo uma referência constante para FTCServerConfig. O primeiro é responsável por fornecer canais quando estes são requisitados. O segundo agrupa as configurações utilizadas pelo servidor FTC, como nome da máquina, porta, tempos de timeout, nível de log e número máximo de clientes. O parâmetro provider é uma instância de DefaultDataProvider, descrita em include/ftc/DefaultDataProvider.h. Esta classe é uma especialização de DataChannelProvider que utiliza o FileChannel como canal de dados. O FileChannel é a especialização de um canal de fluxo de dados específica para arquivos que é fornecida pela biblioteca.

    DefaultDataProvider provider;
    

    O segundo parâmetro é uma instância da classe Config que é fornecida pela demo. Esta classe herda de FTCServerConfig e possui um método parse para ingerir as opções de configuração através da linha de comando de execução do processo servidor:

    Config config;
    int error = config.parse(argc, argv, std::cerr);
    if (error)
      return error;
    
  2. Após a instanciação do servidor, uma thread é criada para ser responsável pela inicialização do servidor e atendimento das requisições do cliente, através de um método bloqueante chamado dispatch.

    boost::shared_ptr<boost::thread> thread(
      new boost::thread(boost::bind(&FTCServer::dispatch, &server)));
    

    A thread principal deve aguardar a inicialização do servidor para prosseguir adiante, o que é feito através do método wait_ready.

    server.wait_ready(); // aguarda o servidor comecar a ouvir o hostname:porta
    
    Os dois métodos acima estão descritos em include/ftc/BaseServer.h, que descreve a classe base de FTCServer.
  3. O retorno da chamada acima indica que o servidor já pode disponibilizar o arquivo que foi fornecido pelo usuário através da linha de comando.

    add_files_to_server(server, config.files());
    

    Esta função auxiliar é responsável por criar os canais de fluxo de dados para cada um dos arquivos fornecidos. Se o usuário fornecer um diretório, o servidor vai mapear cada arquivo, criar um canal e gerar as respectivas chaves de acesso.

    void add_files_to_server(FTCServer &server, const std::vector<std::string> &files)
    {
      for (std::vector<std::string>::const_iterator it = files.begin();
           it != files.end(); it++)
      {
        add_file_to_server(server, *it);
      }
    }
    
    void add_file_to_server(FTCServer &server, const std::string &file)
    {
      boost::filesystem::path path(
        boost::filesystem::system_complete(boost::filesystem::path(file)));
    
      if (boost::filesystem::is_directory(path))
      {
        boost::filesystem::directory_iterator end;
        for(boost::filesystem::directory_iterator dir(path); dir != end; dir++)
        {
          add_file_to_server(server, dir->path().string());
        }
        return;
      }
    
      std::cout << "Gerando identificador unico para o arquivo: " << path.string()
           << std::endl;
      DataChannelInfo_ptr info =
        server.register_data_channel_info(0, path.string()); 1
      std::cout << "Identificador unico para arq. gerado (hex): "
           << boost::algorithm::hex(
             std::string(info->access_key()->key(),
                         info->access_key()->key() + info->access_key()->size()))
           << std::endl; 2
    }
    

    1

    Cria uma descrição do canal através do caminho do arquivo.

    2

    Disponibiliza a chave de acesso.

  4. O penúltimo passo é permitir uma interrupção adequada através da captura de um sinal de interrupção do processo, como por exemplo Ctrl+C. O código abaixo utiliza o boost::asio para capturar o sinal e chamar o método BaseServer::stop para finalizar o servidor FTC.

    void stop_handler(
      const boost::system::error_code &error,
      int signal_number,
      FTCServer* server)
    {
      if (error)
        return;
    
      std::cout << "Finalizando o servidor..." << std::endl;
      server->stop();
    }
    
      boost::asio::io_service io_service;
      boost::asio::signal_set stop_signals(io_service, SIGINT, SIGTERM);
    #if defined(SIGQUIT)
      stop_signals.add(SIGQUIT);
    #endif // defined(SIGQUIT)
      stop_signals.async_wait(boost::bind(stop_handler, _1, _2, &server));
    
    io_service.run();
    
  5. Por último o servidor fica bloqueado na thread criada acima para atendimento das requisições realizadas pelo cliente:

    if (thread->joinable())
      thread->join();
    
  1. O primeiro passo é instanciar um objeto que represente o canal de dados disponibilizado pelo servidor. A classe RemoteDataChannel, declarada em RemoteDataChannel, representa um canal de dados remoto. Conforme apresentado anteriormente, o cliente precisa conhecer o endereço e porta do servidor, e, a chave de acesso para abrir um canal remotamente. Estas informações são passadas através do construtor de RemoteDataChannel:

    Config config;
    int error = config.parse(argc, argv, std::cerr);
    if (error)
    {
      return error;
    }
    RemoteDataChannel channel(config.operation() == Config::OP_WRITE,
                              config.hostname(), config.port(), config.key());
    
  2. O canal é aberto e uma conexão é estabelecida com o servidor através do método RemoteDataChannel::open. O usuário deve conferir na documentação do método as exceções que podem ser lançadas.

    try
    {
      channel.open();
    }
    
  3. No modo leitura, o cliente instancia um objeto para representar o arquivo local de saída. Este objeto é do tipo FileChannel, classe declarada em include/ftc/FileChannel.h que tem por objetivo representar um arquivo. A implementação obtêm o tamanho do arquivo remoto, ofertado pelo servidor, através do método RemoteDataChannel::size e realiza a transferência dos dados através do método RemoteDataChannel::transferTo, passandocomo parâmetro o objeto do tipo FileChannel que representa o arquivo local de saída.

    error = do_read(config, channel);
    
    int do_read(Config &config, RemoteDataChannel &channel)
    {
      boost::scoped_ptr<FileChannel> file;
      try
      {
        file.reset(new FileChannel(config.filename(), false)); 1
      }
      catch(const std::exception &e)
      {
        std::cerr << "Nao foi possivel abrir o arquivo local para escrita: "
                  << config.filename() << " (" << e.what() << ")" << std::endl;
        return 200;
      }
      catch(...)
      {
        std::cerr << "Excecao desconhecida foi lancada ao tentar abrir o arquivo "
                  << "local para escrita: " << config.filename() << std::endl;
        return 201;
      }
      int64_t size = config.size();
      if (size == -1)
      {
        try
        {
          size = channel.size(); 2
        }
        catch(const UnsupportedOperationException &e)
        {
          std::cerr << "O canal remoto nao suporta a aquisicao do tamanho: "
                    << e.what() << " [" << e.location() << "]" << std::endl;
          return 201;
        }
        catch(const FailureException &e)
        {
          std::cerr << "Falha na comunicacao ponto a ponto: "
                    << e.what() << " [" << e.location() << "]" << std::endl;
          return 202;
        }
        catch(const IllegalStateException &e)
        {
          std::cerr << "O canal nao esta aberto: "
                    << e.what() << " [" << e.location() << "]" << std::endl;
          return 203;
        }
        catch(const std::exception &e)
        {
          std::cerr << "Excecao foi lancada ao tentar adquirir o "
                    << "tamanho do canal remoto: " << e.what() << std::endl;
          return 204;
        }
        catch(...)
        {
          std::cerr << "Excecao desconhecida foi lancada ao tentar "
                    << "adquirir o tamanho do canal remoto" << std::endl;
          return 205;
        }
      }
    
      std::cout << "Transferindo " << size << " bytes do canal remoto" << std::endl;
    
      uint64_t bytes_transfered = 0;
      try
      {
        bytes_transfered = channel.transferTo(0, size, *file); 3
      }
      catch(const UnsupportedOperationException &e)
      {
        std::cerr << "O canal remoto nao suporta leitura: "
                  << e.what() << " [" << e.location() << "]" << std::endl;
        return 206;
      }
      catch(const FailureException &e)
      {
        std::cerr << "Falha na comunicacao ponto a ponto: "
                  << e.what() << " [" << e.location() << "]" << std::endl;
        return 207;
      }
      catch(const std::exception &e)
      {
        std::cerr << "Excecao foi lancada ao ler dados do canal remoto: "
                  << e.what() << std::endl;
        return 208;
      }
      catch(...)
      {
        std::cerr << "Excecao desconhecida foi lancada ao ler "
                  << "dados do canal remoto" << std::endl;
        return 209;
      }
    
      std::cout << "Transferidos " << bytes_transfered << " bytes" << std::endl;
      return 0;
    }
    

    1

    Representação do arquivo local de saída. O cliente vai escrever neste arquivo os dados lidos do arquivo remoto que é fornecido pelo servidor FTC.

    2

    Obtêm o tamanho do arquivo remoto.

    3

    Transferência dos dados do arquivo remoto para o arquivo local de saída através do canal de fluxo de dados (RemoteDataChannel).

  4. No modo escrita, o cliente instancia um objeto para representar o arquivo local de entrada. Este objeto é do tipo FileChannel, classe declarada em include/ftc/FileChannel.h que tem por objetivo representar um arquivo. A implementação obtêm o tamanho do arquivo local através do método RemoteDataChannel::size e realiza a transferência dos dados através do método RemoteDataChannel::transferFrom, passando como parâmetro o objeto do tipo FileChannel que representa o arquivo local em que os dados devem ser lidos e escritos no arquivo remoto disponibilizado pelo servidor..

    error = do_write(config, channel);
    
    int do_write(Config &config, RemoteDataChannel &channel)
    {
      boost::scoped_ptr<FileChannel> file;
      try
      {
        file.reset(new FileChannel(config.filename(), false)); 1
      }
      catch(const std::exception &e)
      {
        std::cerr << "Nao foi possivel abrir o arquivo local para escrita: "
                  << config.filename() << " (" << e.what() << ")" << std::endl;
        return 300;
      }
      catch(...)
      {
        std::cerr << "Excecao desconhecida foi lancada ao tentar abrir "
                  << "o arquivo local para escrita: " << config.filename() << std::endl;
        return 301;
      }
    
      int64_t size = config.size();  2
      if (size == -1)
      {
        boost::system::error_code ec;
        size = boost::filesystem::file_size(
          boost::filesystem::path(config.filename()), ec);
        if(ec)
        {
          std::cerr << "Nao foi possivel adquirir o tamanho do arquivo local: "
                    << config.filename() << std::endl;
          return 302;
        }
      }
    
      std::cout << "Transferindo " << size
                << " bytes para o canal remoto" << std::endl;
    
      uint64_t bytes_transfered = 0;
      try
      {
        bytes_transfered = channel.transferFrom(*file, 0, size); 3
      }
      catch(const UnsupportedOperationException &e)
      {
        std::cerr << "O canal remoto nao suporta escrita: "
              << e.what() << " [" << e.location() << "]" << std::endl;
        return 303;
      }
      catch(const FailureException &e)
      {
        std::cerr << "Falha na comunicacao ponto a ponto: "
              << e.what() << " [" << e.location() << "]" << std::endl;
        return 304;
      }
      catch(const std::exception &e)
      {
        std::cerr << "Excecao foi lancada ao escrever dados no canal remoto: "
              << e.what() << std::endl;
        return 305;
      }
      catch(...)
      {
        std::cerr << "Excecao desconhecida foi lancada ao escrever "
              << "dados no canal remoto" << std::endl;
        return 306;
      }
    
      std::cout << "Transferidos " << bytes_transfered << " bytes" << std::endl;
      return 0;
    }
    

    1

    Representação do arquivo local de entrada. O cliente vai transferir o conteúdo deste arquivo para o arquivo disponibilizado pelo servidor.

    2

    Obtêm o tamanho do arquivo local.

    3

    Transferência dos dados do arquivo local para o arquivo remoto através do canal de fluxo de dados (RemoteDataChannel).

  5. Por último o cliente deve fechar o canal de fluxo de dados.

    if (config.close())
    try
    {
      std::cout << "Fechando conexao com o servidor..." << std::endl;
      channel.close();
    }
    

Referencia do FTC C++

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class AccessKey;
      class key_less_comp;
    }
  }
}

Class AccessKey

tecgraf::ftc::v1_04_01::AccessKey — Representa uma chave de acesso a um canal de dados.

Synopsis

// In header: <include/ftc/AccessKey.h>


class AccessKey {
public:
  // construct/copy/destruct
  AccessKey();
  AccessKey(AccessKey const &);
  AccessKey(unsigned char *, uint8_t, bool);
  AccessKey(const std::vector< uint8_t > &);
  AccessKey& operator=(AccessKey const &);
  ~AccessKey();

  // public member functions
  const unsigned char * key() const;
  uint8_t size() const;
  bool operator==(AccessKey const &) const;
  bool operator<=(AccessKey const &) const;
  bool operator>=(AccessKey const &) const;
  bool operator<(AccessKey const &) const;
  bool operator>(AccessKey const &) const;

  // public data members
  static const uint8_t DEFAULT_SIZE;  // Tamanho padrão de uma chave de acesso. 
  static const uint8_t MAX_SIZE;  // Tamanho máximo que uma chave de acesso pode ter. 
};

Description

Tecgraf/PUC-Rio

A classe AccessKey contém a chave de acesso que identificará unicamente um canal de dados oferecido pelo servidor FTC. Um cliente FTC utiliza essa chave de acesso para abrir o canal de dados e assim então executar as operações no canal.

A chave de acesso pode ser gerada automaticamente. Neste caso, a mesma é preenchida com bytes aleatórios utilizando uma implementação de UUID - Universally Unique Identifiers). Para isso, crie uma instância de AccessKey sem passar nenhum parâmetro. Do contrário, é possível informar uma chave de acesso própria passando um array de bytes como parâmetro.

A chave de acesso pode ter um tamanho de no máximo MAX_SIZE bytes. Já a chave de acesso gerada automaticamente tem um tamanho fixo de DEFAULT_SIZE bytes.

AccessKey public construct/copy/destruct

  1. AccessKey();
    Construtor com geração automática da chave de acesso.

    Cria uma chave de acesso com um identificador gerado automaticamente com tamanho fixo de DEFAULT_SIZE bytes.

  2. AccessKey(AccessKey const & key);
    Construtor de cópia.

    Parameters:

    key

    Chave de Acesso

  3. AccessKey(unsigned char * new_key, uint8_t size, bool copy);
    Construtor com chave de acesso própria.

    Cria uma chave de acesso passando um identificador próprio. É possível manter uma referência para o array de bytes ou fazer uma cópia em memória do mesmo.

    Parameters:

    copy

    Indica se uma cópia do buffer dever ser realizada.

    new_key

    Chave de acesso como buffer.

    size

    Tamanho da chave de acesso.

  4. AccessKey(const std::vector< uint8_t > & new_key);
    Construtor com chave de acesso própria.

    Cria uma chave de acesso passando um identificador próprio.

    Parameters:

    new_key

    Chave de acesso como array de bytes.

  5. AccessKey& operator=(AccessKey const &);
  6. ~AccessKey();
    Destrutor.

AccessKey public member functions

  1. const unsigned char * key() const;
    Retorna o buffer da chave de acesso como um array de bytes.

    Returns:

    Retorna o buffer da chave de acesso como um array de bytes.

  2. uint8_t size() const;
    Retorna o tamanho da chave de acesso em bytes.

    Returns:

    Retorna o tamanho da chave de acesso em bytes

  3. bool operator==(AccessKey const &) const;
  4. bool operator<=(AccessKey const &) const;
  5. bool operator>=(AccessKey const &) const;
  6. bool operator<(AccessKey const &) const;
  7. bool operator>(AccessKey const &) const;

Class key_less_comp

tecgraf::ftc::v1_04_01::key_less_comp — Classe para fazer a comparação entre ponteiros de AccessKey's em FTCServer.

Synopsis

// In header: <include/ftc/AccessKey.h>


class key_less_comp {
public:

  // public member functions
  bool operator()(const AccessKey *, const AccessKey *) const;
};

Description

key_less_comp public member functions

  1. bool operator()(const AccessKey * lhs, const AccessKey * rhs) const;
namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class BaseServer;

      typedef boost::shared_ptr< Connection > Connection_ptr;
    }
  }
}

Class BaseServer

tecgraf::ftc::v1_04_01::BaseServer — Representa a classe base para um servidor TCP.

Synopsis

// In header: <include/ftc/BaseServer.h>


class BaseServer {
public:
  // construct/copy/destruct
  BaseServer(ServerConfig &);
  ~BaseServer();

  // public member functions
  const ServerConfig & config() const;
  void dispatch();
  void wait_ready();
  void timed_wait_ready(uint32_t);
  void stop();
  bool stopped() const;
  void exception_handler(ServerExceptionHandler *);
  ServerExceptionHandler * exception_handler() const;
  BaseSession * create_session(Connection &);
  void on_connection_stop(Connection_ptr);

  // protected member functions
  void start_timeout_timer();
  void check_timeout(const uint64_t &);

  // private member functions
  void connect();
  void start_accept();
  void handle_accept(const boost::system::error_code &, Connection_ptr);
  void handle_timeout(const boost::system::error_code &);
  void handle_stop();
  void run();
};

Description

Tecgraf/PUC-Rio

BaseServer public construct/copy/destruct

  1. BaseServer(ServerConfig & config);
    Construtor.

    Parameters:

    config

    Configurações utilizadas pelo servidor

  2. ~BaseServer();
    Destrutor.

BaseServer public member functions

  1. const ServerConfig & config() const;
    Retorna o objeto com as configurações utilizadas pelo servidor.
  2. void dispatch();
    Inicia o servidor.

    Este método é bloqueante.

    Para capturar a porta atribuída na inicialização é necessário perguntar para o método config().port().

  3. void wait_ready();
    Aguarda a inicialização do servidor até que o mesmo comece a aceitar conexões.

    Este método é útil, por exemplo, se o servidor é inicializado num thread à parte, e por vezes é necessário saber quando o mesmo está pronto para receber conexões.

  4. void timed_wait_ready(uint32_t timeout_ms);
    Aguarda a inicialização do servidor até que o mesmo comece a aceitar conexões passando um tempo máximo para esperar.

    Este método é útil, por exemplo, se o servidor é inicializado num thread à parte, e por vezes é necessário saber quando o mesmo está pronto para receber conexões.

    Parameters:

    timeout_ms

    Tempo máximo em milisegundos para aguardar a inicialização do servidor até que o mesmo comece a aceitar conexões.

  5. void stop();
    Sinaliza para o servidor interromper.

    Este método irá sinalizar o servidor para ser interrompido.

  6. bool stopped() const;
    Informa se o servidor está parado.

    Returns:

    true se o servidor está parado.

  7. void exception_handler(ServerExceptionHandler * exception_handler);
    Cadastra um manipulador de exceções.

    Parameters:

    exception_handler

    O novo manipulador de exceções.

  8. ServerExceptionHandler * exception_handler() const;
    Retorna o manipulador de exceções.

    Returns:

    O manipulador de exceções cadastrado

  9. BaseSession * create_session(Connection & conn);
    Cria uma sessão de uma conexão com um cliente.

    Parameters:

    conn

    Objeto com a referência para a conexão.

  10. void on_connection_stop(Connection_ptr conn);
    Notificação recebida quando uma conexão é terminada.

    Parameters:

    conn

    A conexão.

BaseServer protected member functions

  1. void start_timeout_timer();
    Inicia assincronamente o timer de timeout.
  2. void check_timeout(const uint64_t & timeout_ms);
    Verifica se ocorreu timeout.

BaseServer private member functions

  1. void connect();
  2. void start_accept();
  3. void handle_accept(const boost::system::error_code & e, Connection_ptr conn);
  4. void handle_timeout(const boost::system::error_code & ec);
  5. void handle_stop();
  6. void run();

Buffer API

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class Buffer;
    }
  }
}

Class Buffer

tecgraf::ftc::v1_04_01::Buffer — Implementação da classe Buffer do Java com mais a gravação padrão em BIG ENDIAN dos tipos short, int e long do protocolo FTC.

Synopsis

// In header: <include/ftc/Buffer.h>


class Buffer {
public:

  // A typesafe enumeration for byte orders. 
  enum ByteOrder { BIG_ENDIAN_ORDER, LITTLE_ENDIAN_ORDER };
  // construct/copy/destruct
  Buffer(size_t);
  Buffer(char *, size_t);
  ~Buffer();

  // public member functions
  void clear();
  void flip();
  size_t limit() const;
  void limit(size_t);
  void mark();
  size_t size() const;
  size_t position() const;
  void position(size_t);
  size_t remaining() const;
  bool hasRemaining() const;
  void reset();
  void rewind();
  void putLongInt(uint64_t);
  uint64_t getLongInt();
  void putInteger(uint32_t);
  uint32_t getInteger();
  void putShortInt(uint16_t);
  uint16_t getShortInt();
  void putByte(uint8_t);
  uint8_t getByte();
  uint8_t getByte(size_t) const;
  void putBytes(void *, size_t);
  void getBytes(void *, size_t);
  ByteOrder order() const;
  void order(ByteOrder);
  char * buffer();
};

Description

Tecgraf/Puc-Rio

Buffer public construct/copy/destruct

  1. Buffer(size_t capacity);
    The new buffer's position will be zero, its limit will be its capacity, and its mark will be undefined. It will have a backing array, and its array offset will be zero.

    Parameters:

    capacity

    The new buffer's capacity, in bytes

  2. Buffer(char * buffer, size_t size);
    Wraps a byte array into a buffer.

    The new buffer will be backed by the the given byte array; that is, modifications to the buffer will cause the array to be modified and vice versa. The new buffer's capacity and limit will be array.length, its position will be zero, and its mark will be undefined. Its backing array will be the given array, and its array offset will be zero.

    Parameters:

    buffer

    The array that will back this buffer

    size

    The size of array

  3. ~Buffer();
    Destrutor.

Buffer public member functions

  1. void clear();
    Clears this buffer. The position is set to zero, the limit is set to the capacity, and the mark is discarded.

    Invoke this method before using a sequence of channel-read or put operations to fill this buffer. For example:

         buf.clear();     // Prepare buffer for reading
         in.read(buf);    // Read data
    

    This method does not actually erase the data in the buffer, but it is named as if it did because it will most often be used in situations in which that might as well be the case.

  2. void flip();
    Flips this buffer. The limit is set to the current position and then the position is set to zero. If the mark is defined then it is discarded.

    After a sequence of channel-read or put operations, invoke this method to prepare for a sequence of channel-write or relative get operations. For example:

         buf.write(magic);  // Prepend header
         in.read(buf);      // Read data into rest of buffer
         buf.flip();        // Flip buffer
         out.write(buf);    // Write header + data to out
    

    This method is often used in conjunction with the compact method when transferring data from one place to another.

  3. size_t limit() const;
    Gets this buffer's limit.

    Returns:

    Return this buffer's limit.

  4. void limit(size_t limit);
    Sets this buffer's limit.

    If the position is larger than the new limit then it is set to the new limit. If the mark is defined and larger than the new limit then it is discarded. The new limit value must be non-negative and no larger than this buffer's capacity

    Throws:

    std::range_error If the preconditions on new limit do not hold
  5. void mark();
    Sets this buffer's mark at its position.
  6. size_t size() const;
    Buffer's capacity.

    Returns:

    Returns this buffer's capacity.

  7. size_t position() const;
    Gets this buffer's position.

    Returns:

    Returns this buffer's position.

  8. void position(size_t position);
    Sets this buffer's position.

    If the mark is defined and larger than the new position then it is discarded. The new position value must be non-negative and no larger than the current limit.

  9. size_t remaining() const;
    Returns the number of elements between the current position and the limit (remaining in this buffer).

    Returns:

  10. bool hasRemaining() const;
    Tells whether there are any elements between the current position and the limit.

    Returns:

    Returns true if, and only if, there is at least one element remaining in this buffer

  11. void reset();
    Resets this buffer's position to the previously-marked position.

    Invoking this method neither changes nor discards the mark's value.

    Throws:

    std:logic_error If the mark has not been set
  12. void rewind();
    Rewinds this buffer. The position is set to zero and the mark is discarded. Invoke this method before a sequence of channel-write or get operations, assuming that the limit has already been set appropriately. For example:.
         out.put(buf);    // Write remaining data
         buf.rewind();    // Rewind buffer
         buf.get(array);  // Copy data into array
    

  13. void putLongInt(uint64_t value);
    Writes eight bytes containing the given long value, in the current byte order, into this buffer at the current position, and then increments the position by eight.

    Parameters:

    value

    The long value to be written

    Throws:

    std::overflow_error If there are fewer than eight bytes remaining in this buffer
  14. uint64_t getLongInt();
    Reads the next eight bytes at this buffer's current position, composing them into a long value according to the current byte order, and then increments the position by eight.

    Returns:

    The long value at the buffer's current position

    Throws:

    std::underflow_error If there are fewer than eight bytes remaining in this buffer
  15. void putInteger(uint32_t value);
    Writes four bytes containing the given int value, in the current byte order, into this buffer at the current position, and then increments the position by four.

    Parameters:

    value

    The int value to be written

    Throws:

    std::overflow_error If there are fewer than four bytes remaining in this buffer
  16. uint32_t getInteger();
    Reads the next four bytes at this buffer's current position, composing them into an int value according to the current byte order, and then increments the position by four.

    Returns:

    The int value at the buffer's current position

    Throws:

    std::underflow_error If there are fewer than four bytes remaining in this buffer
  17. void putShortInt(uint16_t value);
    Writes two bytes containing the given short value, in the current byte order, into this buffer at the current position, and then increments the position by two.

    Parameters:

    value

    The short value to be written

    Throws:

    std::overflow_error If there are fewer than two bytes remaining in this buffer
  18. uint16_t getShortInt();
    Reads the next two bytes at this buffer's current position, composing them into a short value according to the current byte order, and then increments the position by two.

    Returns:

    The short value at the buffer's current position

    Throws:

    std::underflow_error If there are fewer than two bytes remaining in this buffer
  19. void putByte(uint8_t value);
    Writes the given byte into this buffer at the current position, and then increments the position.

    Parameters:

    value

    The byte to be written

    Throws:

    std::overflow_error If this buffer's current position is not smaller than its limit
  20. uint8_t getByte();
    Relative method. Reads the byte at this buffer's current position, and then increments the position.

    Returns:

    The byte at the buffer's current position

    Throws:

    std::underflow_error If the buffer's current position is not smaller than its limit
  21. uint8_t getByte(size_t index) const;
    Absolute get method. Reads the byte at the given index.

    Parameters:

    index

    The index from which the byte will be read

    Returns:

    The byte at the given index

    Throws:

    std::out_of_range If index is negative or not smaller than the buffer's limit
  22. void putBytes(void * source, size_t nbytes);
    Relative bulk put method (optional operation). This method transfers the entire content of the given source byte array into this buffer. An invocation of this method of the form dst.put(a) behaves in exactly the same way as the invocation:.
         dst.putBytes(a, 0, nbytes)
    

    Parameters:

    nbytes

    The size of array

    source

    The array from which bytes are to be read

    Throws:

    std::overflow_error If there is insufficient space in this buffer
  23. void getBytes(void * dest, size_t nbytes);
    Relative bulk get method.

    This method transfers bytes from this buffer into the given destination array. An invocation of this method of the form src.get(a) behaves in exactly the same way as the invocation:

         src.getBytes(a, 0, a.length)
    

    Parameters:

    dest

    The array into which bytes are to be written

    nbytes

    The size of array

    Throws:

    std::underflow_error If there are fewer than length bytes remaining in this buffer
  24. ByteOrder order() const;
    Gets this buffer's byte order.

    Returns:

    Returns this buffer's byte order.

  25. void order(ByteOrder order);
    Sets this buffer's byte order.

    Parameters:

    order

    The new byte order.

  26. char * buffer();
    Returns the byte array that backs this buffer (optional operation). Modifications to this buffer's content will cause the returned array's content to be modified, and vice versa.

    Returns:

    The array that backs this buffer

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      namespace ChannelClosedReasons {

        // Enumeração que indica as razoes do porque um canal foi fechado. 
        enum ChannelClosedReason { REQUESTED_BY_CLIENT, CLIENT_TIMEOUT, 
                                   PROTOCOL_ERROR, SERVER_SHUTDOWN, 
                                   CONNECTION_ERROR };
      }
    }
  }
}
namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class DataChannelInfo;

      typedef boost::shared_ptr< DataChannelInfo > DataChannelInfo_ptr;  // Smart pointer que mantém um contador de referência para destruir automaticamente um ponteiro para DataChannelInfo. 
    }
  }
}

Class DataChannelInfo

tecgraf::ftc::v1_04_01::DataChannelInfo — Representa informações sobre o acesso a um canal de dados.

Synopsis

// In header: <include/ftc/DataChannelInfo.h>


class DataChannelInfo {
public:
  // construct/copy/destruct
  DataChannelInfo(const AccessKey *const , void *, const std::string &, 
                  const std::string &, uint16_t, bool);
  ~DataChannelInfo();

  // public member functions
  const std::string & hostname() const;
  uint16_t port() const;
  const AccessKey * access_key() const;
  const std::string & data_id() const;
  void * requester() const;
  bool use_transfer_to() const;
  bool check_timeout(const uint64_t &) const;
};

Description

See Also:

DataChannelInfo_ptr

O servidor FTC retorna as informações de um registro de uma requisição para um canal de dados por essa classe. As informações contidas nessa classe devem de alguma maneira serem enviadas para o cliente FTC (Isto está fora do escopo do FTC).

DataChannelInfo public construct/copy/destruct

  1. DataChannelInfo(const AccessKey *const  access_key, void * requester, 
                    const std::string & data_id, const std::string & hostname, 
                    uint16_t port, bool use_transfer_to);
    Cria informações sobre o acesso a um canal de dados.

    O servidor FTC utiliza esse construtor no momento que é registrado uma requisição para um canal de dados.

    Parameters:

    access_key

    A chave de acesso.

    data_id

    O identificador do canal de dados.

    hostname

    O endereço da máquina do servidor.

    port

    A porta da máquina do servidor.

    requester

    Dado para utilização livre do usuário da API.

    use_transfer_to

    Informa a possibilidade de utilização do método TransferTo caso o canal suporte.

  2. ~DataChannelInfo();
    Destrutor.

DataChannelInfo public member functions

  1. const std::string & hostname() const;
    Obtém o endereço da máquina do servidor.

    Returns:

    O endereço da máquina do servidor.

  2. uint16_t port() const;
    Obtém a porta da máquina do servidor.

    Returns:

    A porta da máquina do servidor.

  3. const AccessKey * access_key() const;
    Obtém a chave de acesso.

    Returns:

    A chave de acesso.

  4. const std::string & data_id() const;
    Obtém o identificador do canal de dados.

    Returns:

    O identificador do canal de dados.

  5. void * requester() const;
    Obtém o dado de utilização livre para o usuário da API.

    Returns:

    O dado de utilização livre para o usuário da API.

  6. bool use_transfer_to() const;
    Informa a possibilidade de utilização do método TransferTo se o canal suportar.

    Returns:

    Se libera a utilização do método TransferTo caso o canal suporte.

  7. bool check_timeout(const uint64_t & timeout_ms) const;
    Informa se essa requisição já expirou passado o timeout.

    Parameters:

    timeout_ms

    Timeout em milisegundos.

    Returns:

    true se essa requisição já expirou.

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class DataChannelProvider;
    }
  }
}

Class DataChannelProvider

tecgraf::ftc::v1_04_01::DataChannelProvider — Classe responsável por fornecer os canais requisitados.

Synopsis

// In header: <include/ftc/DataChannelProvider.h>


class DataChannelProvider {
public:
  // construct/copy/destruct
  ~DataChannelProvider();

  // public member functions
  IDataChannel * create_data_channel(void *, const std::string &, bool);
  void data_channel_closed(void *, const std::string &, 
                           ChannelClosedReasons::ChannelClosedReason);
};

Description

É possível, por exemplo, ter um provider que cria canais de dados de arquivos físicos no disco. Ou então, canais de dados de uma fonte de dados com geração de dados constantes (streaming).

Tecgraf/PUC-Rio

DataChannelProvider public construct/copy/destruct

  1. ~DataChannelProvider();
    Destrutor.

DataChannelProvider public member functions

  1. IDataChannel * 
    create_data_channel(void * requester, const std::string & data_id, 
                        bool read_only);
    Cria um canal para um arquivo.

    Parameters:

    data_id

    O identificador do canal de dados.

    read_only

    Indica se o canal será somente para leitura ou não.

    requester

    O responsável pela requisição do canal.

    Returns:

    O canal de dados, ou null, caso o arquivo não exista.

  2. void data_channel_closed(void * requester, const std::string & data_id, 
                             ChannelClosedReasons::ChannelClosedReason reason);
    Indica que um canal foi fechado.

    Parameters:

    data_id

    O identificador do canal de dados.

    reason

    O motivo que o canal foi fechado;

    requester

    O responsável pela requisição do canal.

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class DefaultDataProvider;
    }
  }
}

Class DefaultDataProvider

tecgraf::ftc::v1_04_01::DefaultDataProvider — Classe responsável por fornecer os arquivos requisitados.

Synopsis

// In header: <include/ftc/DefaultDataProvider.h>


class DefaultDataProvider :
  public tecgraf::ftc::v1_04_01::DataChannelProvider
{
public:
  // construct/copy/destruct
  DefaultDataProvider();
  ~DefaultDataProvider();

  // public member functions
  IDataChannel * create_data_channel(void *, const std::string &, bool);
  void data_channel_closed(void *, const std::string &, 
                           ChannelClosedReasons::ChannelClosedReason);
  bool is_locked(void *, std::string const &);
};

Description

Implementação padrão de um DataChannelProvider que utiliza FileChannel como canal de dados. Onde o data_id neste caso é utilizado como o caminho para o arquivo.

Tecgraf/PUC-Rio

DefaultDataProvider public construct/copy/destruct

  1. DefaultDataProvider();
  2. ~DefaultDataProvider();

DefaultDataProvider public member functions

  1. IDataChannel * 
    create_data_channel(void * requester, const std::string & data_id, 
                        bool read_only);

    Cria um canal para um arquivo.

  2. void data_channel_closed(void * requester, const std::string & data_id, 
                             ChannelClosedReasons::ChannelClosedReason reason);

    Indica que um canal foi fechado.

  3. bool is_locked(void * requester, std::string const & data_id);
namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      namespace ErrorCodes {

        // Descreve o erros do protocolo. 
        enum ErrorCode { ok =  0, failure =  -1, invalid_key =  -2, 
                         file_not_found =  -3, no_permission =  -4, 
                         file_locked =  -5, max_clients_reached =  -6, 
                         file_not_open =  -7, read_only =  -8, 
                         invalid_version =  -9, end_of_file =  -10, 
                         unsupported_operation =  -11, unknown_error =  -12, 
                         invalid_protocol_message =  -13 };
      }
    }
  }
}
namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class FTCException;
      class FileNotOpenException;
      class MaxClientsReachedException;
      class FileLockedException;
      class NoPermissionException;
      class FileNotFoundException;
      class InvalidKeyException;
      class FailureException;
      class ReadOnlyException;
      class InvalidProtocolVersionException;
      class EndOfFileException;
      class UnsupportedOperationException;
      class IllegalStateException;
    }
  }
}

Class FTCException

tecgraf::ftc::v1_04_01::FTCException — Define a excecao base da biblioteca FTC.

Synopsis

// In header: <include/ftc/FTCException.h>


class FTCException {
public:
  // construct/copy/destruct
  FTCException(ErrorCodes::ErrorCode, const std::string &, 
               const std::string &);
  ~FTCException();

  // public member functions
  char const * what() const;
  const char * location() const;
  ErrorCodes::ErrorCode error_code();
};

Description

FTCException public construct/copy/destruct

  1. FTCException(ErrorCodes::ErrorCode code, const std::string & msg, 
                 const std::string & location);
    Construtor.

    Parameters:

    code

    Código de erro da exceção em ErrorCodes::ErrorCode

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro

  2. ~FTCException();
    Destrutor.

FTCException public member functions

  1. char const * what() const;
    Retorna a mensagem de erro associada a exceção.

    Returns:

    Mensagem de erro.

  2. const char * location() const;
    Retorna a informação adicional da localização do erro associado a exceção.

    Returns:

    Informação adicional da localização de erro.

  3. ErrorCodes::ErrorCode error_code();
    Retorna o código de erro da exceção.

    Returns:

    ErrorCodes::ErrorCode


Class FileNotOpenException

tecgraf::ftc::v1_04_01::FileNotOpenException — Essa exceção é lançada quando o metodo close é chamado sem que o arquivo remoto esteja aberto.

Synopsis

// In header: <include/ftc/FTCException.h>


class FileNotOpenException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit FileNotOpenException(const std::string &, const std::string &);
};

Description

FileNotOpenException public construct/copy/destruct

  1. explicit FileNotOpenException(const std::string & msg, 
                                  const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class MaxClientsReachedException

tecgraf::ftc::v1_04_01::MaxClientsReachedException — Essa exceção é lançada quando o servidor atingiu o número máximo de clientes.

Synopsis

// In header: <include/ftc/FTCException.h>


class MaxClientsReachedException :
  public tecgraf::ftc::v1_04_01::FTCException
{
public:
  // construct/copy/destruct
  explicit MaxClientsReachedException(const std::string &, 
                                      const std::string &);
};

Description

MaxClientsReachedException public construct/copy/destruct

  1. explicit MaxClientsReachedException(const std::string & msg, 
                                        const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class FileLockedException

tecgraf::ftc::v1_04_01::FileLockedException — Essa exceção é lançada quando o arquivo está reservado para acesso exclusivo.

Synopsis

// In header: <include/ftc/FTCException.h>


class FileLockedException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit FileLockedException(const std::string &, const std::string &);
};

Description

FileLockedException public construct/copy/destruct

  1. explicit FileLockedException(const std::string & msg, 
                                 const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class NoPermissionException

tecgraf::ftc::v1_04_01::NoPermissionException — Essa exceção é lançada quando uma operação falha por causa de falta de permissões para realizar-la.

Synopsis

// In header: <include/ftc/FTCException.h>


class NoPermissionException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit NoPermissionException(const std::string &, const std::string &);
};

Description

NoPermissionException public construct/copy/destruct

  1. explicit NoPermissionException(const std::string & msg, 
                                   const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class FileNotFoundException

tecgraf::ftc::v1_04_01::FileNotFoundException — Essa exceção é lançada quando o arquivo não é encontrado no servidor.

Synopsis

// In header: <include/ftc/FTCException.h>


class FileNotFoundException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit FileNotFoundException(const std::string &, const std::string &);
};

Description

FileNotFoundException public construct/copy/destruct

  1. explicit FileNotFoundException(const std::string & msg, 
                                   const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class InvalidKeyException

tecgraf::ftc::v1_04_01::InvalidKeyException — Essa exceção é lançada quando a chave de acesso utilizada na conexão é inválida.

Synopsis

// In header: <include/ftc/FTCException.h>


class InvalidKeyException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit InvalidKeyException(const std::string &, const std::string &);
};

Description

InvalidKeyException public construct/copy/destruct

  1. explicit InvalidKeyException(const std::string & msg, 
                                 const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class FailureException

tecgraf::ftc::v1_04_01::FailureException — Essa exceção é lançada quando uma falha desconhecida aconteceu.

Synopsis

// In header: <include/ftc/FTCException.h>


class FailureException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit FailureException(const std::string &, const std::string &);
};

Description

FailureException public construct/copy/destruct

  1. explicit FailureException(const std::string & msg, 
                              const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class ReadOnlyException

tecgraf::ftc::v1_04_01::ReadOnlyException — Essa exceção é lançada quando uma tentativa de escrita é realizada em um arquivo aberto somente para leitura.

Synopsis

// In header: <include/ftc/FTCException.h>


class ReadOnlyException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit ReadOnlyException(const std::string &, const std::string &);
};

Description

ReadOnlyException public construct/copy/destruct

  1. explicit ReadOnlyException(const std::string & msg, 
                               const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class InvalidProtocolVersionException

tecgraf::ftc::v1_04_01::InvalidProtocolVersionException — Essa exceção é lançada quando o servidor não suporta a versão do protocolo implementada por este cliente.

Synopsis

// In header: <include/ftc/FTCException.h>


class InvalidProtocolVersionException :
  public tecgraf::ftc::v1_04_01::FTCException
{
public:
  // construct/copy/destruct
  explicit InvalidProtocolVersionException(const std::string &, 
                                           const std::string &);
};

Description

InvalidProtocolVersionException public construct/copy/destruct

  1. explicit InvalidProtocolVersionException(const std::string & msg, 
                                             const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class EndOfFileException

tecgraf::ftc::v1_04_01::EndOfFileException — Essa exceção é lançada quando um comando de leitura que requisitou mas bytes do que existiam no arquivo atinge o final do arquivo.

Synopsis

// In header: <include/ftc/FTCException.h>


class EndOfFileException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit EndOfFileException(const std::string &, const std::string &);
};

Description

EndOfFileException public construct/copy/destruct

  1. explicit EndOfFileException(const std::string & msg, 
                                const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class UnsupportedOperationException

tecgraf::ftc::v1_04_01::UnsupportedOperationException — Essa exceção é lançada quando uma operacao nao suportada tenta ser executada.

Synopsis

// In header: <include/ftc/FTCException.h>


class UnsupportedOperationException :
  public tecgraf::ftc::v1_04_01::FTCException
{
public:
  // construct/copy/destruct
  explicit UnsupportedOperationException(const std::string &, 
                                         const std::string &);
};

Description

UnsupportedOperationException public construct/copy/destruct

  1. explicit UnsupportedOperationException(const std::string & msg, 
                                           const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro


Class IllegalStateException

tecgraf::ftc::v1_04_01::IllegalStateException — Representa uma exceção onde o objeto está num estado inconsistente.

Synopsis

// In header: <include/ftc/FTCException.h>


class IllegalStateException : public tecgraf::ftc::v1_04_01::FTCException {
public:
  // construct/copy/destruct
  explicit IllegalStateException(const std::string &, const std::string &);
};

Description

IllegalStateException public construct/copy/destruct

  1. explicit IllegalStateException(const std::string & msg, 
                                   const std::string & location);
    Construtor.

    Parameters:

    location

    Informação adicional de onde ocorreu o erro

    msg

    Mensagem de erro

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class IDataChannel;
      namespace Operations {

        // Enumeracao de operacoes suportadas pelo DataChannel. 
        enum Operation { no_operations =  0x00, get_size =  0x01, 
                         set_size =  0x02, get_position =  0x04, 
                         set_position =  0x08, read =  0x10, write =  0x20, 
                         transfer_from =  0x40, transfer_to =  0x80 };
      }
    }
  }
}

Class IDataChannel

tecgraf::ftc::v1_04_01::IDataChannel — Classe que representa um canal de acesso a dados.

Synopsis

// In header: <include/ftc/IDataChannel.h>


class IDataChannel {
public:
  // construct/copy/destruct
  ~IDataChannel();

  // public member functions
  uint16_t supportedOperations() const;
  bool isOpen() const;
  int64_t remaining() const;
  uint64_t skip(const uint64_t);
  uint64_t size() const;
  void size(const uint64_t);
  uint64_t position() const;
  void position(const uint64_t);
  int64_t read(Buffer &);
  int64_t read(Buffer &, const uint64_t);
  int64_t write(Buffer &);
  int64_t write(Buffer &, const uint64_t);
  int64_t transferTo(const uint64_t, const uint64_t, IDataChannel &);
  int64_t transferFrom(IDataChannel &, const uint64_t, const uint64_t);
};

Description

Dessa classe podem ser implementados especializações de um canal de dados para um servidor FTC trabalhar com arquivos, streaming, sockets etc.

IDataChannel public construct/copy/destruct

  1. ~IDataChannel();
    Destrutor.

IDataChannel public member functions

  1. uint16_t supportedOperations() const;
    Retorna os métodos/operações suportados pela implementação do canal de dados. Todas as implementações devem definir as operações suportadas.

    Implementação obrigatoria.

    See Also:

    Operations::Operation

    Returns:

    As operações suportadas (Flags de Operations::Operation)

  2. bool isOpen() const;
    Informa se o canal está aberto ou não.

    Implementação obrigatoria.

    Returns:

    true se, e somente se, o canal está aberto.

  3. int64_t remaining() const;
    Retorna a quantidade de bytes no canal a partir da posição atual e o limite.

    O valor -1 significa end-of-stream.

    O valor 0 significa que atualmente não há dados, mas pode vir a ter. Utilizado em live-streams

    Implementação obrigatoria.

    Returns:

    A quantidade de bytes existentes no canal.

  4. uint64_t skip(const uint64_t count);
    Metodo que pula/ignora uma quantidade de bytes a partir da posicao atual.

    Implementação obrigatoria.

    Parameters:

    count

    quantidade de bytes a serem pulados.

    Returns:

    Quantidade de bytes pulados

  5. uint64_t size() const;
    Obtém a quantidade de bytes no canal a partir da posição inicial.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Returns:

    O tamanho em bytes.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  6. void size(const uint64_t size);
    Define a quantidade de bytes para o canal.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    size

    O novo tamanho

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  7. uint64_t position() const;
    Obtém a posição atual do canal.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Returns:

    A posição atual do arquivo.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  8. void position(const uint64_t position);
    Define a nova posição do arquivo.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    position

    A nova posição

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  9. int64_t read(Buffer & dest);
    Lê uma sequência de bytes do arquivo.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    dest

    O buffer de destino dos bytes a serem lidos do canal

    Returns:

    A quantidade de bytes lidos, ou -1, caso chegue ao final do arquivo.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  10. int64_t read(Buffer & dest, const uint64_t remotePosition);
    Lê uma sequência de bytes do arquivo.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    dest

    O buffer de destino dos bytes a serem lidos do canal

    remotePosition

    A posição deste canal partir da qual a leitura vai ser iniciada.

    Returns:

    A quantidade de bytes lidos.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  11. int64_t write(Buffer & source);
    Escreve uma sequência de bytes no arquivo.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    source

    O buffer de origem dos bytes a serem escritos no canal

    Returns:

    A quantidade de bytes escritos.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  12. int64_t write(Buffer & source, const uint64_t remotePosition);
    Escreve uma sequência de bytes no arquivo.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    remotePosition

    A posição deste canal a partir da qual a escrita vai ser iniciada.

    source

    O buffer de origem dos bytes a serem escritos no canal

    Returns:

    A quantidade de bytes escritos.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  13. int64_t transferTo(const uint64_t remotePosition, const uint64_t nbytes, 
                       IDataChannel & dest);
    Transfere os dados do arquivo para um fluxo de saída.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    dest

    O fluxo de saída que receberá os dados do canal.

    nbytes

    A quantidade de bytes para serem transferidos.

    remotePosition

    A posição inicial a partir da qual este canal será lido.

    Returns:

    A quantidade de bytes efetivamente transferidos.

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
  14. int64_t transferFrom(IDataChannel & source, const uint64_t remotePosition, 
                         const uint64_t nbytes);
    Transfere os dados de um fluxo de entrada para o arquivo.

    Implementação opcional. No caso da operação não ser suportada deve ser lançada UnsupportedOperationException.

    Parameters:

    nbytes

    A quantidade de bytes para serem transferidos

    remotePosition

    A posição inicial a partir da qual este canal será escrito.

    source

    O fluxo de entrada.

    Returns:

    A quantidade de bytes efetivamente transferidos

    Throws:

    UnsupportedOperationException Caso a operação não seja suportada nesse canal.
namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class ServerConfig;
    }
  }
}

Class ServerConfig

tecgraf::ftc::v1_04_01::ServerConfig — Define as configurações utilizadas no BaseServer.

Synopsis

// In header: <include/ftc/ServerConfig.h>


class ServerConfig {
public:
  enum ServerLogLevel;
  // construct/copy/destruct
  ServerConfig();
  ~ServerConfig();

  // public member functions
  const std::string & hostname() const;
  void hostname(const std::string &);
  uint16_t port() const;
  void port(uint16_t);
  uint32_t channel_request_timeout() const;
  void channel_request_timeout(const uint32_t);
  uint32_t client_timeout() const;
  void client_timeout(const uint32_t);
  std::size_t max_clients() const;
  void max_clients(std::size_t);
  std::size_t max_channel_requests() const;
  void max_channel_requests(std::size_t);
  std::size_t client_buffer_size() const;
  void client_buffer_size(std::size_t);
  bool is_test_mode() const;
  void is_test_mode(bool);
  ServerLogLevel log_level() const;
  void log_level(ServerLogLevel);
  const std::string & log_filename() const;
  void log_filename(const std::string &);
  bool log_date_time() const;
  void log_date_time(bool);
  std::size_t thread_pool_size() const;
  void thread_pool_size(const std::size_t);
  void print(std::ostream &) const;

  // friend functions
  friend std::ostream & operator<<(std::ostream &, const ServerConfig &);
};

Description

O comportamento de várias variáveis internas do servidor é definido nas configurações. O valor para cada variável depende de cada utilização e pode ser refinado para atender melhor cada caso.

Tecgraf

ServerConfig public construct/copy/destruct

  1. ServerConfig();
    Construtor.
  2. ~ServerConfig();
    Destrutor.

ServerConfig public member functions

  1. const std::string & hostname() const;
    Retorna o endereço/IP para o servidor.

    Returns:

    O endereço/IP para o servidor.

  2. void hostname(const std::string & value);
    Define o endereço/IP para o servidor.

    Parameters:

    value

    O endereço/IP para o servidor.

  3. uint16_t port() const;
    Retorna a porta que o servidor irá escutar as conexões de novos clientes.

    Returns:

    A porta que o servidor irá escutar as conexões de novos clientes.

  4. void port(uint16_t value);
    Define a porta que o servidor irá escutar as conexões de novos clientes.

    É comum a utilização da porta 0 para conexão. A porta 0 é especial, pois obriga o servidor a utilizar uma porta que esteja disponível no sistema na hora da conexão.

    Parameters:

    value

    A porta que o servidor irá escutar as conexões de novos clientes. Caso seja 0, uma porta disponível será obtida.

  5. uint32_t channel_request_timeout() const;
    Retorna o tempo máximo para o consumo de uma requisição (DataChannelInfo).

    Após o registro de uma requisição para um canal de dados (DataChannelInfo), o cliente tem X milisegundos para se conectar ao servidor, se após esse tempo o cliente FTC não se conectar ao servidor e solicitar o canal de dados a requisição é removida.

    Returns:

    Retorna o tempo máximo em milisegundos de timeout para requisição de um canal

  6. void channel_request_timeout(const uint32_t value);
    Define o timeout para o consumo de uma requisição (DataChannelInfo).

    Após o registro de uma requisição para um canal de dados (DataChannelInfo), o cliente tem X milisegundos para se conectar ao servidor, se após esse tempo o cliente FTC não se conectar ao servidor e solicitar o canal de dados a requisição é removida.

    Parameters:

    value

    Tempo máximo em milisegundos que o servidor espera para remover uma requisição não consumida

  7. uint32_t client_timeout() const;
    Retorna o tempo máximo em milisegundos que um cliente é desconectado por inatividade.

    Caso um cliente conectado não efetue nenhuma operação no tempo máximo configurado, é forçado a desconexão do mesmo por timeout.

    Returns:

    Tempo máximo em milisegundos que um cliente é desconectado por inatividade.

  8. void client_timeout(const uint32_t value);
    Define o tempo máximo em milisegundos que um cliente é desconectado por inatividade.

    Caso um cliente conectado não efetue nenhuma operação no tempo máximo configurado, é forçado a desconexão do mesmo por timeout.

    Parameters:

    value

    Tempo máximo em milisegundos que um cliente é desconectado por inatividade.

  9. std::size_t max_clients() const;
    Retorna o número maximo de clientes que o servidor suporta.

    Caso o número de clientes conectados alcance o número máximo configurado, novos clientes que tentarem se conectar serão forçadamente desconectados.

    Returns:

    O número maximo de clientes que o servidor suporta.

  10. void max_clients(std::size_t value);
    Define o número maximo de clientes que o servidor suporta.

    Caso o número de clientes conectados alcance o número máximo configurado, novos clientes que tentarem se conectar serão forçadamente desconectados.

    Parameters:

    value

    O número maximo de clientes que o servidor suporta.

  11. std::size_t max_channel_requests() const;
    Retorna o número máximo permitido de possíveis registros à requisições de canais de dados (DataChannelInfo).

    Número máximo de registros à requisições de canais de dados que o servidor irá permitir.

    Returns:

    Número maximo de requisições.

  12. void max_channel_requests(std::size_t value);
    Número máximo permitido de possíveis registros à requisições de canais de dados (DataChannelInfo).

    Número máximo de registros à requisições de canais de dados que o servidor irá permitir.

    Parameters:

    value

    Número maximo de requisiçoes.

  13. std::size_t client_buffer_size() const;
    Retorna o tamanho do espaço de memória utilizado na comunicação com cada cliente.

    Esse espaço de memória é criado para cada nova conexão com um cliente. Sua função principal é a de armazenar a transmissão parcial de um dado cliente/servidor ou vice-versa. O mesmo é utilizado também quando o canal não suporta transferTo/transferFrom.

    Returns:

    O tamanho do espaço de memória utilizado na comunicação com cada cliente.

  14. void client_buffer_size(std::size_t value);
    Define o tamanho do espaço de memória utilizado na comunicação com cada cliente.

    Esse espaço de memória é criado para cada nova conexão com um cliente. Sua função principal é a de armazenar a transmissão parcial de um dado cliente/servidor ou vice-versa. O mesmo é utilizado também quando o canal não suporta transferTo/transferFrom.

    Parameters:

    value

    Retorna o tamanho do espaço de memória utilizado na comunicação com cada cliente.

  15. bool is_test_mode() const;
    Retorna true se o servidor deve executar em modo de teste.

    No modo teste, o servidor mantém todos os registros às possíveis requisições à canais de dados, mesmo que um cliente feche o canal. Permitindo assim um cliente se reconectar com a mesma chave de acesso.

    Returns:

    true se o servidor deve executar em modo de teste.

  16. void is_test_mode(bool value);
    Define se o servidor deve executar em modo de teste.

    No modo teste, o servidor mantém todos os registros às possíveis requisições à canais de dados, mesmo que um cliente feche o canal. Permitindo assim um cliente se reconectar com a mesma chave de acesso.

    Parameters:

    value

    Define se o servidor deve executar em modo de teste.

  17. ServerLogLevel log_level() const;
    Retorna o nível de logging.

    Returns:

    O nivel de logging.

  18. void log_level(ServerLogLevel value);
    Define o nível de logging.

    Parameters:

    value

    O nível de logging.

  19. const std::string & log_filename() const;
    Retorna o nome do arquivo de saída que será gravado o log.

    Returns:

    O nome do arquivo de saída que será gravado o log.

  20. void log_filename(const std::string & value);
    Define o nome do arquivo de saída que será gravado o log.

    Parameters:

    value

    O nome do arquivo de saída que será gravado o log.

  21. bool log_date_time() const;
    Retorna se faz o log da data e hora.

    Returns:

    Retorna se faz o log da data e hora.

  22. void log_date_time(bool value);
    Define se faz o log da data e hora.

    Parameters:

    value

    Informa se faz o log da data e hora.

  23. std::size_t thread_pool_size() const;
    Retorna o tamanho do pool de threads utilizado no servidor.

    O servidor implementa internamente um pool de threads para atender as mensagens cliente/servidor. Os threads são criados na instanciação do servidor. Por isso, deve ser levado em conta o custo para a máquina para a criação do número total configurado de threads.

    Deve ser levado em conta o caso em que uma requisição seja bloqueada num thread por uma implementação de um canal de dados (IDataChannel). Se isso for verdade, e todos os threads forem bloqueados, o servidor irá parar de responder. Assim, nesse caso onde a implementação do canal de dados tem operações é bloqueantes, uma boa prática seria limitar o número de clientes ao número de threads menos 1. Dessa maneira sempre vai existir um thread no mínimo para recusar novas conexões.

    Returns:

    O tamanho do pool de threads utilizado no servidor.

  24. void thread_pool_size(const std::size_t value);
    Define o tamanho do pool de threads utilizado no servidor.

    O servidor implementa internamente um pool de threads para atender as mensagens cliente/servidor. Os threads são criados na instanciação do servidor. Por isso, deve ser levado em conta o custo para a máquina para a criação do número total configurado de threads.

    Deve ser levado em conta o caso em que uma requisição seja bloqueada num thread por uma implementação de um canal de dados (IDataChannel). Se isso for verdade, e todos os threads forem bloqueados, o servidor irá parar de responder. Assim, nesse caso onde a implementação do canal de dados tem operações é bloqueantes, uma boa prática seria limitar o número de clientes ao número de threads menos 1. Dessa maneira sempre vai existir um thread no mínimo para recusar novas conexões.

    Parameters:

    value

    O tamanho do pool de threads utilizado no servidor.

  25. void print(std::ostream & out) const;
    Imprime as configuração para o stream de saída.

    Parameters:

    out

    Stream de saída.

ServerConfig friend functions

  1. friend std::ostream & 
    operator<<(std::ostream & out, const ServerConfig & config);
    Operador global para suportar stream.

    Parameters:

    config

    Objeto que implementa o ServerConfig

    out

    Stream de saída.

Type ServerLogLevel

tecgraf::ftc::v1_04_01::ServerConfig::ServerLogLevel — Níveis de log.

Synopsis

// In header: <include/ftc/ServerConfig.h>


enum ServerLogLevel { LOG_OFF, LOG_FATAL, LOG_ERROR, LOG_WARN, LOG_INFO, 
                      LOG_DEBUG, LOG_TRACE, LOG_ALL =  LOG_TRACE };

Description

Cada nível de log inclui o anterior na ordem crescente que se segue. Por exemplo, LOG_WARN tem um nível que irá incluir logs dos níveis inferiores LOG_ERROR e LOG_FATAL também no log. Logo, o último nível, LOG_ALL, irá incluir o log de todos os níveis anteriores.

namespace tecgraf {
  namespace ftc {
    namespace v1_04_01 {
      class ServerExceptionHandler;
    }
  }
}

Class ServerExceptionHandler

tecgraf::ftc::v1_04_01::ServerExceptionHandler — Define as operações de um objeto que recebe as exceções do servidor.

Synopsis

// In header: <include/ftc/ServerExceptionHandler.h>


class ServerExceptionHandler {
public:
  // construct/copy/destruct
  ServerExceptionHandler();
  ~ServerExceptionHandler();

  // public member functions
  void exception_raised(const std::string &);
  void exception_raised(const std::string &, const std::string &);
  void exception_raised(const std::exception &);
  void exception_raised(const std::exception &, const std::string &);
};

Description

Toda exceção lançada durante e execução do servidor é capturada e informada para uma implementação dessa classe. É possível assim o tratamento mais adequado da exceção ou simplesmente o log da mesma.

Tecgraf/PUC-Rio

ServerExceptionHandler public construct/copy/destruct

  1. ServerExceptionHandler();
    Construtor.
  2. ~ServerExceptionHandler();
    Destrutor.

ServerExceptionHandler public member functions

  1. void exception_raised(const std::string & msg);
    Chamado quando uma exceção é lançada no servidor.

    Parameters:

    msg

    Mensagem da exceção quando não específica - catch(...).

  2. void exception_raised(const std::string & msg, const std::string & data_id);
    Chamado quando uma exceção é lançada no servidor.

    Parameters:

    data_id

    Referência ao identificador do canal de dados

    msg

    Mensagem da exceção quando não específica - catch(...).

  3. void exception_raised(const std::exception & e);
    Chamado quando uma exceção é lançada no servidor.

    Parameters:

    e

    Objeto da exceção.

  4. void exception_raised(const std::exception & e, const std::string & data_id);
    Chamado quando uma exceção é lançada no servidor.

    Parameters:

    data_id

    Referência ao identificador do canal de dados

    e

    Objeto da exceção.