27.10. Processamento de notas

As mensagens de nota e advertência geradas pelo servidor não são retornadas pelas funções que executam os comandos, uma vez que não implicam em falha do comando. Em vez disso, são passadas para uma função tratadora, e a execução prossegue normalmente após o retorno do tratador. A função padrão para tratar notas envia a mensagem para stderr, mas o aplicativo pode mudar este comportamento fornecendo sua própria função tratadora.

Por motivos históricos existem dois níveis de tratamento de notas, chamados receptor de notas e processador de notas. O comportamento padrão é o receptor formatar a nota e passar a cadeia de caracteres para o processador de notas, para que este faça a exibição. Entretanto, um aplicativo que decida fornecer seu próprio receptor de notas, tipicamente ignora a camada do processador de notas e apenas realiza todo o trabalho no receptor de notas.

A função PQsetNoticeReceiver define ou consulta o receptor de notas corrente para o objeto de conexão. De maneira semelhante, a função PQsetNoticeProcessor define ou consulta o processador de notas corrente.

typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);

PQnoticeReceiver
PQsetNoticeReceiver(PGconn *conn,
                    PQnoticeReceiver proc,
                    void *arg);

typedef void (*PQnoticeProcessor) (void *arg, const char *message);

PQnoticeProcessor
PQsetNoticeProcessor(PGconn *conn,
                     PQnoticeProcessor proc,
                     void *arg);

Estas funções retornam o ponteiro para a função receptora de notas ou processadora de notas anterior, e definem o novo valor. Se for fornecido um ponteiro de função nulo nenhuma ação é realizada, mas é retornado o ponteiro corrente.

Quando é recebida uma mensagem de nota ou advertência vinda do servidor, ou gerada internamente pela libpq, a função receptora de notas é chamada. A mensagem é passada na forma de um PGresult PGRES_NONFATAL_ERROR (Permite ao receptor extrair os campos individualmente utilizando a função PQresultErrorField, ou a mensagem completa pré-formatada utilizando a função PQresultErrorMessage). O mesmo ponteiro vazio passado para a função PQsetNoticeReceiver também é passado (Este ponteiro pode ser utilizado para acessar estados específicos do aplicativo, caso haja necessidade).

O receptor padrão de notas simplesmente extrai a mensagem (utilizando a função PQresultErrorMessage), e passa para o processador de notas.

O processador de notas é responsável por tratar as mensagens de nota e advertência fornecidas na forma de texto. É passada a cadeia de caracteres do texto da mensagem (incluindo um caractere de nova-linha no final), mais um ponteiro vazio que é o mesmo passado para a função PQsetNoticeProcessor (Este ponteiro pode ser utilizado para acessar estados específicos do aplicativo, caso haja necessidade).

O processador de notas padrão é simplesmente

static void
defaultNoticeProcessor(void *arg, const char *message)
{
    fprintf(stderr, "%s", message);
}

Uma vez definido um receptor ou processador de notas, deve-se esperar que sejam chamados enquanto os objetos PGconn ou PGresult que acessam os mesmos existam. Na criação de um objeto PGresult, os ponteiros para o tratador de notas corrente de PGconn são copiados para PGresult, para um possível uso por parte de funções como PQgetvalue.

SourceForge.net Logo CSS válido!