Procedimento Geral para Gravar Programas de API

Antes de gravar os programas de plug-in do Caching Proxy, é necessário compreender como o Servidor Proxy funciona. O comportamento do Servidor Proxy pode ser dividido em diversas etapas diferentes de processamento. Para cada uma dessas etapas, é possível fornecer suas próprias funções customizadas usando a API. Por exemplo, deseja fazer alguma coisa antes de um pedido de cliente ser lido, mas antes de executar qualquer outro processamento? Ou talvez deseje executar rotinas especiais durante a autenticação e, então, novamente após o arquivo solicitado ser enviado.

Uma biblioteca de funções predefinidas é fornecida com a API. Os programas de plug-in podem chamar funções de API predefinidas a fim de interagir com o processo do Servidor Proxy (por exemplo, para manipular pedidos, para ler ou gravar cabeçalhos de pedidos ou para gravar nos logs do Servidor Proxy). Essas funções não devem ser confundidas com as funções de plug-in gravadas, que são chamadas pelo Servidor Proxy. As funções predefinidas estão descritas em Funções e Macros Predefinidas.

Você instrui o Servidor Proxy para chamar as funções de plug-in nas etapas apropriadas usando as diretivas de API do Caching Proxy, no arquivo de configuração do servidor. Essas diretivas estão descritas em Diretivas de Configuração do Caching Proxy para Etapas da API.

Esse documento contém o seguinte:

É possível usar esses componentes e procedimentos para gravar seus próprios programas de plug-in do Caching Proxy.

Etapas do Processo do Servidor

A operação básica do Servidor Proxy pode ser quebrada em etapas baseadas no tipo de processamento que o servidor executa durante essa fase. Cada etapa contém uma junção na qual uma parte específica do programa pode ser executada. Ao incluir diretivas da API no arquivo de configuração do Caching Proxy (ibmproxy.conf), você indica qual das funções de plug-in que deseja que seja chamada durante uma determinada etapa. É possível chamar diversas funções de plug-in durante uma etapa específica do processo ao incluir mais de uma diretiva nessa etapa.

Algumas etapas fazem parte do processo de pedido do servidor. Em outras palavras, o Servidor Proxy executa essas etapas a cada vez que processa um pedido. Outras etapas são executadas independentemente do processamento do pedido, ou seja, o servidor executa essas etapas independente de o pedido estar ou não sendo processado.

O programa compilado reside em um objeto compartilhado, por exemplo, em um arquivo DLL ou .so, dependendo do sistema operacional. À medida em que o servidor continua com as etapas do processo do pedido, ele chama as funções de plug-in associadas a cada etapa, até que uma das funções indique que tratou do pedido. Se especificar mais de uma função de plug-in específica, as funções serão chamadas na ordem em que suas diretivas aparecerem no arquivo de configuração.

Se o pedido não for tratado por uma função de plug-in (ou você não incluiu uma diretiva de API do Caching Proxy para essa etapa, ou a função de plug-in para essa etapa retornou HTTP_NOACTION), o servidor executará a ação padrão para essa etapa.

Nota: Isso é verdadeiro para todas as etapas, exceto para a etapa Serviço; a etapa Serviço não tem uma ação padrão.

O Figura 1 descreve as etapas do processo do Servidor Proxy e define a ordem de processamento para as etapas relacionadas ao processamento do pedido.

Figura 1. Fluxograma das etapas contidas no processo do Servidor Proxy

Quatro das etapas no diagrama são executadas independentemente do processamento de qualquer pedido do cliente. Essas etapas estão relacionadas à execução e manutenção do Servidor Proxy. Elas incluem o seguinte:

A seguinte lista explica o propósito de cada etapa representada no Figura 1. Observe que não há garantia de que todas as etapas serão chamadas para um pedido específico.

Inicialização do Servidor
Executa a inicialização quando o Servidor Proxy é iniciado e antes de qualquer pedido de cliente ser aceito.
Meia-noite
Executa um plug-in à meia-noite, sem nenhum contexto de pedido. Essa etapa é mostrada separadamente no diagrama, pois ela não faz parte do processo do pedido; em outras palavras, sua execução independe de qualquer pedido.
GC Advisor
Influencia as decisões de coleta de lixo para arquivos no cache. Essa etapa é mostrada separadamente no diagrama, pois ela não faz parte do processo do pedido; em outras palavras, sua execução independe de qualquer pedido. A coleta de lixo é feita quando o tamanho do cache atinge o valor máximo. (Informações sobre a configuração da coleta de lixo do cache estão incluídas no WebSphere Application Server Caching Proxy Administration Guide.)
PreExit

Executa o processamento após um pedido ser lido, mas antes de ser feita qualquer outra coisa.

Se essa etapa retornar uma indicação de que o pedido foi processado (HTTP_OK), o servidor contorna as outras etapas no processo do pedido e executa somente as etapas Transformador, Log e PostExit.

Conversão de Nome
Converte o caminho virtual (de uma URL) em um caminho físico.
Autorização

Usa tokens de segurança armazenados para verificar o caminho físico de proteções, ACLs e outros controles de acesso e gera os cabeçalhos WWW-Authenticate necessários para autenticação básica. Se gravar sua própria função de plug-in para substituir esta etapa, será necessário gerar esses cabeçalhos por si próprio.

Consulte Autenticação e Autorização para obter maiores informações.

Autenticação

Decodifica, verifica e armazena tokens de segurança.

Consulte Autenticação e Autorização para obter maiores informações.

Tipo de Objeto
Localiza o objeto do sistema de arquivos indicado pelo caminho.
Pós-autorização

Executa o processamento após a autorização e o local do objeto, mas antes de o pedido ser atendido.

Se essa etapa retornar uma indicação de que o pedido foi processado (HTTP_OK), o servidor contorna as outras etapas no processo do pedido e executa somente as etapas Transformador, Log e PostExit.

Serviço
Atende o pedido (ao enviar o arquivo, executando o CGI, etc.)
Proxy Advisor
Influencia nas decisões de proxy e de cache.
Transformador
Fornece acesso de gravação à parte dos dados da resposta enviada ao cliente.
Log
Permite a criação de log da transação customizada.
Error
Permite respostas customizadas para condições de erro.
PostExit
Limpa os recursos alocados ao processamento de pedidos.
Terminação do Servidor
Executa o processamento de limpeza quando ocorre um encerramento organizado.

Diretrizes

Funções de Plug-in

Siga a sintaxe apresentada no Protótipos da Função de Plug-in para gravar suas próprias funções do programa para as etapas definidas do processamento do pedido.

Cada uma das funções deve preencher o parâmetro do código de retorno com um valor que indique qual ação foi adotada:

Protótipos da Função de Plug-in

Os protótipos de função de cada etapa do Caching Proxy mostram o formato a ser usado e explica o tipo de processamento que podem executar. Observe que os nomes de funções não são predefinidos. É necessário fornecer nomes exclusivos às funções e é possível escolher as próprias convenções de nomenclatura. Para facilidade de associação, esse documento usa nomes que se relacionam às etapas de processamento do servidor.

Em cada uma dessas funções de plug-in, determinadas funções predefinidas da API são válidas. Algumas funções predefinidas não são válidas em todas as etapas. As seguintes funções predefinidas da API são válidas quando chamadas de todas essas funções de plug-in:

Funções válidas ou inválidas da API são observadas nas descrições do protótipo de função.

O valor do parâmetro handle enviado às funções pode ser passado como o primeiro argumento para as funções predefinidas. As funções predefinidas da API estão descritas em Funções e Macros Predefinidas.

Inicialização do Servidor

void HTTPD_LINKAGE ServerInitFunction (
     unsigned char *handle, 
     unsigned long *major_version,
     unsigned long *minor_version, 
     long *return_code
     )

Uma função definida para essa etapa é chamada uma vez, quando o módulo é carregado durante a inicialização do servidor. É a oportunidade de executar a inicialização antes de os pedidos terem sido aceitos.

Apesar de todas as funções de inicialização do servidor serem chamadas, um código de retorno de erro de uma função nesta etapa faz com que o servidor ignore todas as outras funções configuradas no mesmo módulo que a função que retornou o código de erro. (Ou seja, nenhuma outra função contida no mesmo objeto compartilhado que a função que retornou o erro é chamada.)

Os parâmetros da versão contêm o número da versão do Servidor Proxy; eles são fornecidos pelo Caching Proxy.

PreExit

void  HTTPD_LINKAGE  PreExitFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido após o pedido ter sido lido, mas antes de ter ocorrido qualquer processamento. Um plug-in nessa etapa pode ser usado para acessar o pedido do cliente antes que seja processado pelo Caching Proxy.

Os códigos de retorno válidos para a função preExit são os seguintes:

Outros códigos de retorno não devem ser usados.

Se essa função retorna HTTP_OK, o Servidor Proxy presume que o pedido foi tratado. Todas as etapas de processamento de pedido subsequentes são contornadas e somente as etapas de resposta (Transformador, Log e PostExit) são executadas.

Todas as funções de API predefinidas são válidas durante essa etapa.

Meia-noite

void  HTTPD_LINKAGE  MidnightFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é executada diariamente à meia-noite e não contém nenhum contexto de pedido. Por exemplo, ela pode ser usada para chamar um processo-filho para analisar logs. (Observe que o processamento extensivo durante essa etapa pode interferir na criação de log.)

Autenticação

void  HTTPD_LINKAGE  AuthenticationFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido baseado no esquema de autenticação do pedido. Essa função pode ser usada para customizar a verificação dos tokens de segurança que são enviados com um pedido.

Conversão de Nome

void  HTTPD_LINKAGE  NameTransFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido. Um modelo de URL pode ser especificado na diretiva do arquivo de configuração, se desejar que a função de plug-in seja chamada somente para pedidos que correspondam ao modelo. A etapa Conversão de Nome ocorre antes de o pedido ser processado e fornece um mecanismo para mapear URLs a objetos, tais como nomes de arquivos.

Autorização

void  HTTPD_LINKAGE  AuthorizationFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido. Um modelo de URL pode ser especificado na diretiva do arquivo de configuração, se desejar que a função de plug-in seja chamada somente para pedidos que correspondam ao modelo. A etapa Autorização ocorre antes de o pedido ser processado e pode ser usada para verificar se o objeto identificador pode ser retornado ao cliente. Se estiver executando autenticação básica, será necessário gerar os cabeçalhos WWW-Authenticate necessários.

Tipo de Objeto

void  HTTPD_LINKAGE  ObjTypeFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido. Um modelo de URL pode ser especificado na diretiva do arquivo de configuração, se desejar que a função de plug-in seja chamada somente para pedidos que correspondam ao modelo. A etapa Tipo de Objeto ocorre antes de o pedido ser processada e pode ser usada para verificar se o objeto existe e para executar o tipo de definição do objeto.

PostAuthorization

void  HTTPD_LINKAGE  PostAuthFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada após o pedido ter sido autorizado, mas antes de ter ocorrido qualquer processamento. Se essa função retorna HTTP_OK, o Servidor Proxy presume que o pedido foi tratado. Todas as etapas de pedido subsequentes são contornadas e somente as etapas de resposta (Transformador, Log e PostExit) são executadas.

Todas as funções predefinidas do servidor são válidas durante essa etapa.

Serviço

void  HTTPD_LINKAGE  ServiceFunction (
         unsigned char *handle, 
         long *return_code 
         )

Uma função definida para essa etapa é chamada para cada pedido. Um modelo de URL pode ser especificado na diretiva do arquivo de configuração, se desejar que a função de plug-in seja chamada somente para pedidos que correspondam ao modelo. A etapa Serviço atende o pedido, se não foi atendido nas etapas PreExit ou PostAuthorization.

Todas as funções predefinidas do servidor são válidas durante essa etapa.

Consulte a diretiva Ativar, no WebSphere Application Server Caching Proxy Administration Guide, para obter informações sobre a configuração da função Serviço a ser executada com base no método HTTP, em vez de URL.

Transformador
As funções chamadas nesta etapa do processo podem ser usadas para filtrar os dados de resposta como um fluxo. São chamadas em sequência quatro funções de plug-in para essa etapa e cada uma atua como um segmento do canal através do qual os dados fluem. Ou seja, as funções open, write, close e error fornecidas são chamadas, nessa ordem, para cada resposta. Cada função processa o mesmo fluxo de dados sucessivamente.

Para esta etapa, é necessário implementar as seguintes quatro funções. (Os nomes das funções não precisam corresponder a esses nomes.)

Notas:

GC Advisor

void  HTTPD_LINKAGE  GCAdvisorFunction (
         unsigned char *handle, 
         long *return_code
         )

A função definida para essa etapa é chamada para cada arquivo no cache durante a coleta de lixo. Essa função permite que influencie quais arquivos são mantidos e quais são descartados. Para obter mais informações, consulte as variáveis GC_*.

Proxy Advisor

void  HTTPD_LINKAGE  ProxyAdvisorFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada durante o serviço de cada pedido de proxy. Por exemplo, ela pode ser usada para configurar a variável USE_PROXY.

Log

void  HTTPD_LINKAGE  LogFunction (
         unsigned char *handle,
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido depois de o pedido ter sido processado e de a comunicação com o cliente ter sido fechada. Um modelo de URL pode ser especificado na diretiva do arquivo de configuração, se desejar que a função de plug-in seja chamada somente para pedidos que correspondam ao modelo. Essa função é chamada independentemente do sucesso ou falha do processamento do pedido. Se não desejar que o plug-in do log substitua o mecanismo de log padrão, configure o código de retorno como HTTP_NOACTION em vez de HTTP_OK.

Error

void  HTTPD_LINKAGE  ErrorFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada para cada pedido que falha. Um modelo de URL pode ser especificado na diretiva do arquivo de configuração, se desejar que a função de plug-in seja chamada somente para pedidos com falha que correspondam ao modelo. A etapa Erro fornece uma oportunidade de customizar a resposta de erro.

PostExit

void  HTTPD_LINKAGE  PostExitFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida nessa etapa é chamada para cada pedido, independentemente do sucesso ou falha do pedido. Essa etapa permite que limpe as tarefas de qualquer recurso alocado pelo plug-in para processar o pedido.

Terminação do Servidor

void  HTTPD_LINKAGE  ServerTermFunction (
         unsigned char *handle, 
         long *return_code
         )

Uma função definida para essa etapa é chamada quando ocorre um encerramento organizado do servidor. Ela permite que limpe os recursos alocados durante a etapa Inicialização do Servidor. Não chame nenhuma função HTTP_* nessa etapa (os resultados são imprevisíveis). Se tiver mais de uma diretiva da API do Caching Proxy no arquivo de configuração para a Terminação do Servidor, todas serão chamadas.

Nota:
Devido a uma limitação no código do Solaris, o plug-in de Terminação do Servidor não é executado quando o comando ibmproxy -stop é usado para encerrar o Caching Proxy nas plataformas Solaris. Consulte o WebSphere Application Server Caching Proxy Administration Guide para obter informações sobre como iniciar e parar o Caching Proxy.

Códigos de Retorno e Valores de HTTP

Esses códigos de retorno seguem a especificação de HTTP 1.1, RFC 2616, publicada pelo World Wide Web Consortium (www.w3.org/pub/WWW/Protocols/). As funções de plug-in devem retornar um desses valores.

Tabela 2. Códigos de retorno de HTTP para funções da API do Caching Proxy
Valor Código de retorno
0 HTTP_NOACTION
100 HTTP_CONTINUE
101 HTTP_SWITCHING_PROTOCOLS
200 HTTP_OK
201 HTTP_CREATED
202 HTTP_ACCEPTED
203 HTTP_NON_AUTHORITATIVE
204 HTTP_NO_CONTENT
205 HTTP_RESET_CONTENT
206 HTTP_PARTIAL_CONTENT
300 HTTP_MULTIPLE_CHOICES
301 HTTP_MOVED_PERMANENTLY
302 HTTP_MOVED_TEMPORARILY
302 HTTP_FOUND
303 HTTP_SEE_OTHER
304 HTTP_NOT_MODIFIED
305 HTTP_USE_PROXY
307 HTTP_TEMPORARY_REDIRECT
400 HTTP_BAD_REQUEST
401 HTTP_UNAUTHORIZED
403 HTTP_FORBIDDEN
404 HTTP_NOT_FOUND
405 HTTP_METHOD_NOT_ALLOWED
406 HTTP_NOT_ACCEPTABLE
407 HTTP_PROXY_UNAUTHORIZED
408 HTTP_REQUEST_TIMEOUT
409 HTTP_CONFLICT
410 HTTP_GONE
411 HTTP_LENGTH_REQUIRED
412 HTTP_PRECONDITION_FAILED
413 HTTP_ENTITY_TOO_LARGE
414 HTTP_URI_TOO_LONG
415 HTTP_BAD_MEDIA_TYPE
416 HTTP_BAD_RANGE
417 HTTP_EXPECTATION_FAILED
500 HTTP_SERVER_ERROR
501 HTTP_NOT_IMPLEMENTED
502 HTTP_BAD_GATEWAY
503 HTTP_SERVICE_UNAVAILABLE
504 HTTP_GATEWAY_TIMEOUT
505 HTTP_BAD_VERSION

Funções e Macros Predefinidas

É possível chamar as funções e macros predefinidas do servidor para suas próprias funções de plug-in. É necessário usar seus nomes predefinidos e seguir o formato descrito abaixo. Nas descrições do parâmetro, a letra i indica um parâmetro de entrada, a letra o indica um parâmetro de saída e a letra i/o indica que um parâmetro é usado tanto para entrada como para saída.

Cada uma dessas funções retorna um dos códigos de retorno de HTTPD, dependendo do sucesso do pedido. Esses códigos estão descritos em Códigos de Retorno de Funções e Macros Predefinidas.

Use o identificador fornecido para o plug-in como o primeiro parâmetro ao chamar essas funções. Do contrário, a função retorna um código de erro HTTPD_PARAMETER_ERROR. NULL não é aceito como um identificador válido.

HTTPD_authenticate()
Autentica um ID do usuário ou senha ou ambos. Válido somente nas etapas PreExit, Autenticação, Autorização e PostAuthorization.

void  HTTPD_LINKAGE  HTTPD_authenticate (
         unsigned char *handle,      /* i; identificador */
         long *return_code           /* o; código de retorno */
         )
HTTPD_cacheable_url()
Retorna se o conteúdo da URL especificada for armazenável em cache de acordo com os padrões do Caching Proxy.

void HTTPD_LINKAGE  HTTPD_cacheable_url ( 
        unsigned char *handle,      /* i; identificador */
        unsigned char *url,         /* i; URL a verificar */
        unsigned char *req_method,  /* i; método de pedido para a URL */
        long *retval                /* o; código de retorno */
        )

O valor de retorno HTTPD_SUCCESS indica se o conteúdo da URL é armazenável em cache; HTTPD_FAILURE indica que o conteúdo não é armazenável em cache. HTTPD_INTERNAL_ERROR também é um código de retorno possível para essa função.

HTTPD_close()
(Válido apenas na etapa Transformador.) Transfere o controle para a próxima rotina close na pilha de fluxos. Chame essa função a partir das funções open, write ou close do Transformador após qualquer processamento desejado ter sido feito. Essa função notifica o Servidor Proxy que a resposta foi processada e que a etapa Transformador está concluída.

void  HTTPD_LINKAGE  HTTPD_close (
         unsigned char *handle,      /* i; identificador */
         long *return_code           /* o; código de retorno */ 
         )
HTTPD_exec()
Executa um script para atender este pedido. Válido nas etapas PreExit, Serviço, PostAuthorization e Erro.

void  HTTPD_LINKAGE  HTTPD_exec (
         unsigned char *handle,         /* i; identificador */
         unsigned char *name,           /* i; nome do script a executar */
         unsigned long *name_length,    /* i; comprimento do nome */
         long *return_code              /* o; código de retorno */
         )
HTTPD_extract()
Extrai o valor de uma variável associada a esse pedido. As variáveis válidas para o parâmetro name são as mesmas que aquelas usadas no CGI. Consulte Variáveis para obter maiores informações. Observe que essa função é válida em todas as etapas. Entretanto, nem todas as variáveis são válidas em todas as etapas.

void  HTTPD_LINKAGE  HTTPD_extract (
      unsigned char *handle,       /* i; identificador */
      unsigned char *name,         /* i; nome da variável a extrair */
      unsigned long *name_length,  /* i; comprimento do nome */
      unsigned char *value,        /* o; buffer no qual colocar 
                                         o valor */
      unsigned long *value_length, /* i/o; tamanho do buffer */
      long *return_code            /* o; código de retorno */
      )

Se essa função retornar o código HTTPD_BUFFER_TOO_SMALL, o tamanho do buffer solicitado não era grande o suficiente para o valor extraído. Nesse caso, a função não usa o buffer, mas atualiza o parâmetro value_length com o tamanho do buffer necessário, a fim de extrair esse valor com êxito. Tente novamente a extração com um buffer que seja, ao menos, tão grande quanto o value_length retornado.

Nota:
Se a variável que está sendo extraída for para um cabeçalho de HTTP, a função HTTPD_extract() extrairá somente a primeira ocorrência correspondente, mesmo se o pedido contiver cabeçalhos múltiplos com o mesmo nome. A função httpd_getvar() pode ser usada em vez de HTTPD_extract() e também oferece outros benefícios. Consulte a seção no httpd_getvar() function para obter mais informações.
HTTPD_file()
Envia um arquivo para atender esse pedido. Válido somente nas etapas PreExit, Service, Error, PostAuthorization e Transformador.

void  HTTPD_LINKAGE  HTTPD_file (
         unsigned char *handle,          /* i; identificador */
         unsigned char *name,            /* i; nome do arquivo a enviar */
         unsigned long *name_length,     /* i; comprimento do nome */
         long *return_code               /* o; código de retorno */
         )
httpd_getvar()
O mesmo que HTTPD_extract(), exceto ser mais fácil de usar, pois o usuário não precisa especificar comprimentos para os argumentos.

const  unsigned char *          /* o; valor da variável */
HTTPD_LINKAGE
httpd_getvar(
   unsigned char *handle,       /* i; identificador */
   unsigned char *name,         /* i; nome da variável */
   unsigned long *n             /* i; número de índice da matriz que 
                                      contém o cabeçalho */
   )

O índice da matriz que contém o cabeçalho começa com 0. Para obter o primeiro item na matriz, use o valor 0 para n; para obter o quinto item, use o valor 4 para n.

Nota:
Não descarte nem altere o conteúdo do valor retornado. A cadeia retornada é terminada como nula.
HTTPD_log_access()
Grava uma cadeia no log de acesso do servidor.

void  HTTPD_LINKAGE  HTTPD_log_access (
         unsigned char *handle,           /* i; identificador */
         unsigned char *value,            /* i; dados a gravar */
         unsigned long *value_length,     /* i; comprimento dos dados */
         long *return_code                /* o; código de retorno */
         )  

Observe que símbolos de de escape não são necessários ao gravar o símbolo de percentual (%) nos logs de acesso do servidor.

HTTPD_log_error()
Grava uma cadeia no log de erros do servidor.

void  HTTPD_LINKAGE  HTTPD_log_error (
         unsigned char *handle,          /* i; identificador */
         unsigned char *value,           /* i; dados a gravar */
         unsigned long *value_length,    /* i; comprimento dos dados */
         long *return_code               /* o; código de retorno */
         )

Observe que os símbolos de escape não são necessários ao gravar o símbolo de percentual (%) nos logs de erros do servidor.

HTTPD_log_event()
Grava uma cadeia no log de eventos do servidor.

void  HTTPD_LINKAGE  HTTPD_log_event (
         unsigned char *handle,          /* i; identificador */
         unsigned char *value,           /* i; dados a gravar */
         unsigned long *value_length,    /* i; comprimento dos dados */
         long *return_code               /* o; código de retorno */
         )

Observe que símbolos de de escape não são necessários ao gravar o símbolo de percentual (%) nos logs de eventos do servidor.

HTTPD_log_trace()
Grava uma cadeia no log de rastreio do servidor.

void  HTTPD_LINKAGE  HTTPD_log_trace (
         unsigned char *handle,          /* i; identificador */
         unsigned char *value,           /* i; dados a gravar */
         unsigned long *value_length,    /* i; comprimento dos dados */
         long *return_code               /* o; código de retorno */
         )

Observe que símbolos de de escape não são necessários ao gravar o símbolo de percentual (%) nos logs de rastreio do servidor.

HTTPD_open()
(Válido apenas na etapa Transformador.) Transfere o controle para a rotina seguinte na pilha de fluxos. Chame isso a partir das funções open, write ou close do Transformador, após qualquer cabeçalho desejado ser configurado e você estar pronto para começar a gravar a rotina.

void  HTTPD_LINKAGE  HTTPD_open (
         unsigned char *handle,      /* i; identificador */
         long *return_code           /* o; código de retorno */ 
         )	
HTTPD_proxy()
Faz um pedido de proxy. Válido nas etapas PreExit, Service e PostAuthorization.
Nota:
Essa é uma função de conclusão; o pedido estará completo depois dessa função.

void  HTTPD_LINKAGE  HTTPD_proxy (
         unsigned char *handle,        /* i; identificador */
         unsigned char *url_name,      /* i; URL para o   
                                             pedido de proxy */
         unsigned long *name_length,   /* i; comprimento da URL */
         void *request_body,           /* i; corpo do pedido */
         unsigned long *body_length,   /* i; comprimento do corpo */
         long *return_code             /* o; código de retorno */
         ) 
HTTPD_read()
Lê o corpo do pedido do cliente. Usa HTTPD_extract() para cabeçalhos. Válido somente nas etapas PreExit, Autorização, PostAuthorization e Serviço e é útil somente se um pedido PUT ou POST ter sido feito. Chame essa função um loop até que HTTPD_EOF seja retornado. Se não houver nenhum corpo para esse pedido, essa função falhará.

void  HTTPD_LINKAGE  HTTPD_read (
         unsigned char *handle,          /* i; identificador */
         unsigned char *value,           /* i; buffer para dados */
         unsigned long *value_length,    /* i/o; tamanho do buffer 
                                                 (comprimento de dados) */
         long *return_code               /* o; código de retorno */
         )
HTTPD_restart()
Reinicia o servidor após todos os pedidos ativos terem sido processados. Válido em todas as etapas, exceto para Inicialização do Servidor, Terminação do Servidor e Transformador

void  HTTPD_LINKAGE  HTTPD_restart ( 
         long *return_code    /* o; código de retorno */
         )
HTTPD_set()
Configura o valor de uma variável associada a este pedido. As variáveis que são válidas para o parâmetro name são as mesmas daquelas usadas no CGI. Consulte Variáveis para obter maiores informações.

Observe que também é possível criar variáveis com essa função. As variáveis criadas estão sujeitas às convenções de prefixos HTTP_ e PROXY_, descritas em Variáveis. Se criar uma variável que começa com HTTP_, ela será enviada como um cabeçalho na resposta ao cliente, sem o prefixo HTTP_. Por exemplo, para configurar um cabeçalho de Local, use HTTPD_set() com o nome de variável HTTP_LOCATION. As variáveis criadas com um prefixo PROXY_ são enviadas como cabeçalhos no pedido para o servidor de conteúdo. As variáveis criadas com um prefixo CGI_ são passadas aos programas CGI.

Essa função é válida em todas as etapas. Entretanto, nem todas as variáveis são válidas em todas as etapas.

void  HTTPD_LINKAGE  HTTPD_set (
         unsigned char *handle,        /* i; identificador */
         unsigned char *name,          /* i; nome do valor a configurar */
         unsigned long *name_length,   /* i; comprimento do nome */
         unsigned char *value,         /* i; buffer com valor */
         unsigned long *value_length,  /* i; comprimento do valor */
         long *return_code             /* o; código de retorno */
         ) 
Nota:
É possível usar a função httpd_setvar() para configurar um valor da variável sem ter de especificar um buffer e comprimento. Consulte a seção em httpd_setvar() function para obter informações.
httpd_setvar()
O mesmo que HTTPD_set(), exceto ser mais fácil de usar, pois o usuário não precisa especificar comprimentos para os argumentos.

long             /* o; código de retorno */
HTTPD_LINKAGE   httpd_setvar (
       unsigned char *handle,       /* i; identificador */
       unsigned char *name,         /* i; nome da variável */
       unsigned char *value,        /* i; novo valor */ 
       unsigned long *addHdr        /* i; inclua cabeçalho ou exclua-o */
       )

O parâmetro addHdr tem quatro valores possíveis:

Esses valores estão definidos em HTAPI.h.

httpd_variant_insert()
Insere uma variante no cache.

void  HTTPD_LINKAGE  httpd_variant_insert (
         unsigned char *handle,    /* i; identificador */
         unsigned char *URI,       /* i; URI deste objeto */
         unsigned char *dimension, /* i; dimensão de variação */
         unsigned char *variant,   /* i; valor da variante */
         unsigned char *filename,  /* i; arquivo que contém o objeto */
         long *return_code         /* o; código de retorno */
         )

Notas:

  1. O argumento de dimensão refere-se ao cabeçalho pelo qual esse objeto varia da URI. Por exemplo, no exemplo acima um valor de dimensão possível é Usuário-Agente.
  2. O argumento da variante refere-se ao valor do cabeçalho para o cabeçalho fornecido no argumento de dimensão. Isso varia conforme a URI. Por exemplo, no exemplo acima, um valor possível para o argumento da variante é o seguinte:
    Mozilla 4.0 (compatível; BatBrowser 94.1.2; Bat OS)
  3. O argumento do nome do arquivo deve indicar uma cópia terminada como nula do nome do arquivo no qual o usuário salvou o conteúdo modificado. O usuário é responsável por remover o arquivo; essa ação é segura após o retorno dessa função. O arquivo contém somente o corpo sem nenhum cabeçalho.
  4. Ao armazenar variantes em cache, o servidor atualiza o cabeçalho de comprimento do conteúdo e inclui um Aviso: cabeçalho 214. As tags fortes de entidade são removidas.
httpd_variant_lookup()
Determina se uma variante fornecida existe no cache.

void  HTTPD_LINKAGE  httpd_variant_lookup (
    unsigned char *handle,             /* i; identificador */
    unsigned char *URI,                /* URI deste objeto */
    unsigned char *dimension,          /* i; dimensão da variação */
    unsigned char *variant,            /* i; valor da variante */
             long *return_code);       /* o; código de retorno */      
HTTPD_write()
Grava o corpo da resposta. Válido nas etapas PreExit, Serviço, Erro e Transformador.

Se não configurar o tipo de conteúdo antes de chamar essa função pela primeira vez, o servidor supõe que esteja enviando um fluxo de dados de CGI.

void  HTTPD_LINKAGE  HTTPD_write (
    unsigned char *handle,             /* i; identificador */
    unsigned char *value,              /* i; data a enviar */
    unsigned char *value_length,       /* i; comprimento dos dados */
             long *return_code);       /* o; código de retorno */
Nota:
Para configurar cabeçalhos de resposta, consulte a seção no HTTPD_set() function.
Nota:
Após uma função HTTPD_* retornar, será seguro liberar qualquer memória passada com ela.

Códigos de Retorno de Funções e Macros Predefinidas

O servidor configurará o parâmetro do código de retorno com um desses valores, dependendo do sucesso do pedido:

Tabela 3. Códigos de Retorno
Valor Código do status Explicação
-1 HTTPD_UNSUPPORTED A função não é suportada.
0 HTTPD_SUCCESS A função obteve êxito e os campos de saída são válidos.
1 HTTPD_FAILURE A função falhou.
2 HTTPD_INTERNAL_ERROR Um erro interno foi encontrado e o processamento desse pedido não pode continuar.
3 HTTPD_PARAMETER_ERROR Um ou mais parâmetros inválidos foram passados.
4 HTTPD_STATE_CHECK A função não é válida nesta etapa do processo.
5 HTTPD_READ_ONLY (Retornado somente por HTTPD_set e httpd_setvar.) A variável é somente leitura e não pode ser configurada pelo plug-in.
6 HTTPD_BUFFER_TOO_SMALL (Retornado pelo HTTPD_set, httpd_setvar e HTTPD_read.) O buffer fornecido é muito pequeno.
7 HTTPD_AUTHENTICATE_FAILED (Retornado somente por HTTPD_authenticate.) A autenticação falhou. Examine as variáveis HTTP_RESPONSE e HTTP_REASON para obter mais informações.
8 HTTPD_EOF (Retornado somente por HTTPD_read.) Indica o final do corpo do pedido.
9 HTTPD_ABORT_REQUEST O pedido foi interrompido, pois o cliente forneceu uma tag de entidade que não correspondia à condição especificada pelo pedido.
10 HTTPD_REQUEST_SERVICED (Retornado por HTTPD_proxy.) A função que foi chamada completou a resposta para este pedido.
11 HTTPD_RESPONSE_ALREADY_COMPLETED A função falhou, pois a resposta para esse pedido já estava concluída.
12 HTTPD_WRITE_ONLY A variável é somente gravação e não pode ser lida pelo plug-in.

Diretivas de Configuração do Caching Proxy para Etapas da API

Cada etapa no processo do pedido tem uma configuração de diretiva usada para indicar qual das funções de plug-in deseja chamar e executar durante essa etapa. É possível incluir essas diretivas no arquivo de configuração do servidor (ibmproxy.conf) ao editá-lo e atualizá-lo manualmente ou ao usar o formulário de Processamento de Pedido da API nos formulários de Configuração e Administração do Caching Proxy.

Notas de Uso da API

Diretivas e Sintaxe da API

Essas diretivas do arquivo de configuração devem aparecer no arquivo ibmproxy.conf como uma linha, sem nenhum espaço além daqueles explicitamente especificados aqui. Apesar de aparecer quebras de linhas para fins de capacidade de leitura, em alguns exemplos de sintaxe, não deve haver nenhum espaço nesses pontos na diretiva atual.

Tabela 4. diretivas da API de plug-in do Caching Proxy
ServerInit /path/file:function_name init_string
PreExit /path/file:function_name
Autenticação tipo /path/file:function_name
NameTrans /URL /path/file:function_name
Autorização /URL /path/file:function_name
Tipo de Objeto /URL /path/file:function_name
PostAuth /path/file:function_name
Serviço /URL /path/file:function_name
Meia-noite /path/file:function_name
Transformador /path/file:open_function_name: write_function_name: close_function_name:error_function
Log /URL /path/file:function_name
Erro /URL /path/file:function_name
PostExit /path/file:function_name
ServerTerm /path/file:function_name
ProxyAdvisor /path/file:function_name
GCAdvisor /path/file:function_name

Variáveis da Diretiva da API

As variáveis nessas diretivas têm os seguintes significados:

tipo
Usado apenas com a diretiva Autenticação para especificar se a função de plug-in foi ou não chamada. Os valores válidos são os seguintes:
URL
Especifica os pedidos para os quais a função de plug-in é chamada. Os pedidos com URLs que correspondem a esse modelo farão com que a função de plug-in seja usada. As especificações de URL nessas diretivas são virtuais (elas não incluem o protocolo), mas são precedidas por uma barra (/). Por exemplo, /www.ics.raleigh.ibm.com está correto, mas http://www.ics.raleigh.ibm.com não está. É possível especificar esse valor como uma URL específica ou como um modelo.
path/file
o nome qualificado do arquivo completo do programa compilado.
function_name
O nome que forneceu à função do plug-in no programa.

A diretiva Serviço requer um asterisco (*) após o nome da função, se desejar ter acesso às informações do caminho.

init_string
Essa parte opcional da diretiva ServerInit pode conter qualquer texto que deseje passar à função de plug-in. Use httpd_getvar() para extrair o texto da variável INIT_STRING.

Para obter informações adicionais, incluindo a sintaxe, sobre essas diretivas, consulte o WebSphere Application Server Caching Proxy Administration Guide.