PingAccess Agent SDK for C
Public Attributes | List of all members
paa_client_request_struct Struct Reference

#include <paa-http-server-facade.h>

Public Attributes

void * impl
 
const char *(* get_method )(const paa_client_request *req)
 
const char *(* get_normalized_uri )(const paa_client_request *req)
 
const char *(* get_raw_uri )(const paa_client_request *req)
 
const char *(* get_remote_ip )(const paa_client_request *req)
 
const char *(* get_scheme )(const paa_client_request *req)
 
const char *(* get_scope )(const paa_client_request *req)
 
apr_status_t(* enumerate_headers )(const paa_client_request *req, paa_header_cb cb, void *userdata)
 
apr_status_t(* get_header_values )(const paa_client_request *req, const char *name, paa_header_cb cb, void *userdata)
 
apr_status_t(* set_header )(const paa_client_request *req, const char *name, const char *value)
 
apr_status_t(* add_header )(const paa_client_request *req, const char *name, const char *value)
 
apr_status_t(* remove_header )(const paa_client_request *req, const char *name)
 
apr_status_t(* set_req_var )(const paa_client_request *req, const char *name, const char *value)
 
apr_status_t(* remove_req_var )(const paa_client_request *req, const char *name)
 
apr_status_t(* set_user )(const paa_client_request *req, const char *user)
 
const char *(* get_user )(const paa_client_request *req)
 
paa_client_request_read_cb(* get_read_cb )(const paa_client_request *req)
 
void *(* get_read_data )(const paa_client_request *req)
 

Detailed Description

The client request interface. This interface is implemented by a HTTP server/proxy to provide access to the content of a HTTP request being processed by the server.

Member Data Documentation

apr_status_t(* paa_client_request_struct::add_header) (const paa_client_request *req, const char *name, const char *value)

Adds a header to the client request.

The following algorithm should be used to add the header value to the client request:

  • If the header does not exist in the client request, add a new header field to the request with the specified name and value.
  • If the header does exist in the client request:
    • If the header is not named Cookie, the implementation of this function is free to add a new header field with the specified name and value or append the value to the existing header field, separating the values with a comma.
    • If the header is named Cookie, the value should be appended to the existing Cookie header field, separating the values with a semicolon.
Parameters
reqthe request handle
namethe name of the header
valuethe value of the header
Returns
APR_SUCCESS on success
apr_status_t(* paa_client_request_struct::enumerate_headers) (const paa_client_request *req, paa_header_cb cb, void *userdata)

Enumerates all headers in the request, invoking the callback for each header value. Headers with multiple values can be passed to the callback in any acceptable format. For example, consider the following request header:

X-Custom-Header: value1, value2 X-Custom-Header: value3

Any of the following of sequences of invocations of the header callback would be acceptable:

cb("X-Custom-Header", "value1"); cb("X-Custom-Header", "value2"); cb("X-Custom-Header", "value3");

cb("X-Custom-Header", "value1, value2"); cb("X-Custom-Header", "value3");

cb("X-Custom-Header", "value1, value2, value3");

Note: this function will only be invoked on a modified client request (i.e., one in which add, set or remove header has been invoked) when the SDK log level is set to DEBUG.

Parameters
reqthe request handle
cbthe callback used to enumerate the headers
userdatathe userdata passed to the callback
Returns
APR_SUCCESS on success
apr_status_t(* paa_client_request_struct::get_header_values) (const paa_client_request *req, const char *name, paa_header_cb cb, void *userdata)

Get all header values for the named header. Headers with multiple values can be passed to the callback in any acceptable format.

For example, consider the following response header:

X-Custom-1: value1, value2
X-Custom-1: value3
X-Custom-2: value1

When the name of the header is X-Custom-1, any of the following of sequences of invocations of the header callback would be acceptable:

cb("X-Custom-1", "value1"); cb("X-Custom-1", "value2"); cb("X-Custom-1", "value3");

cb("X-Custom-1", "value1, value2"); cb("X-Custom-1", "value3");

cb("X-Custom-1", "value1, value2, value3");

When the name of the header is X-Custom-2, the following invocation of the header callback would be expected:

cb("X-Custom-2", "value1");

If the named header does not exist in the request, the callback should not be invoked and this function should still return APR_SUCCESS.

Parameters
reqthe handle
namethe name of the header
cbthe callback used to enumerate the headers
userdatathe userdata passed to the callback
Returns
APR_SUCCESS on success
error otherwise
const char*(* paa_client_request_struct::get_method) (const paa_client_request *req)
Parameters
reqthe request handle
Returns
the method from the request
const char*(* paa_client_request_struct::get_normalized_uri) (const paa_client_request *req)
Remarks
this function is required to normalize the URI provided in the request received by the web server. This is necessary to avoid path traversal attacks in the caching implementation.
Parameters
reqthe request handle
Returns
the uri from the request – this must be the full, normalized URI NOT including the query. The URI should use UTF-8 encoding if the normalized URI contains characters outside the ASCII character set.
const char*(* paa_client_request_struct::get_raw_uri) (const paa_client_request *req)
Parameters
reqthe request handle
Returns
the uri from the request – this must be the full, raw URI INCLUDING the query as it would appear in the original HTTP request.
paa_client_request_read_cb(* paa_client_request_struct::get_read_cb) (const paa_client_request *req)

Note: this field can be safely set to NULL if the paa_http_client interface is not being utilized.

Parameters
reqthe request handle
Returns
the function used to obtain the request body
void*(* paa_client_request_struct::get_read_data) (const paa_client_request *req)

Note: this field can be safely set to NULL if the paa_http_client interface is not being utilized.

Parameters
reqthe request handle
Returns
the user data that will be passed to the read callback
const char*(* paa_client_request_struct::get_remote_ip) (const paa_client_request *req)
Parameters
reqthe request handle
Returns
a string representation of the remote ip from which the request was sent
const char*(* paa_client_request_struct::get_scheme) (const paa_client_request *req)
Parameters
reqthe handle
Returns
the URI scheme used to received the request, either "http" or "https"
const char*(* paa_client_request_struct::get_scope) (const paa_client_request *req)

A Client Request's scope is used to map a request to its policy cache. This can be used to isolate policy caches for distinct management domains/tenants.

Parameters
reqthe handle
Returns
the scope, a null-terminated character string. Must not be NULL but can be the empty string.
const char*(* paa_client_request_struct::get_user) (const paa_client_request *req)

Gets the user of the client request.

If the SDK consumer does not have a notion of a user for a request, the function can safely always return NULL.

Parameters
reqthe request handle
Returns
the user value or NULL if no user is set
void* paa_client_request_struct::impl

opaque implementation handle

apr_status_t(* paa_client_request_struct::remove_header) (const paa_client_request *req, const char *name)

Removes a header from the client request. All header values for the specified header name should be removed from the headers.

Parameters
reqthe req handle
namethe name of the header
Returns
APR_SUCCESS on success
apr_status_t(* paa_client_request_struct::remove_req_var) (const paa_client_request *req, const char *name)

Removes a request-scoped variable or attribute from the client request.

Examples include environment variables for a CGI application or request attributes in a servlet container.

If the environment of the SDK consumer has no notion of a request-scoped variable or attribute, this function can safely be a no-op.

Parameters
reqthe request handle
namethe name of the request variable
Returns
APR_SUCCESS on success
apr_status_t(* paa_client_request_struct::set_header) (const paa_client_request *req, const char *name, const char *value)

Sets a header in the client request. The following algorithm should be used to set the header in the request:

1) Remove all headers in the request with name (case-insensitive comparison) 2) Set a single header in the request with name and value

For example, consider the following request header:

X-Custom: value1, value2
X-Custom: value3

If set_header is called with a name of "X-Custom" and a value of "value4", the following request header should result:

X-Custom: value4

Specifically, the values of value1, value2 and value3 are overridden in the request.

Additionally, an empty string for value should NOT be ignored. For example, consider the following request header:

X-User: user1

If set_header is called with a name of "X-User" and a value of "", the following request header should result:

X-User: 

The SDK invokes set_header in this way to clobber headers used to identify the user for a request to the protected application, preventing header injection.

Parameters
reqthe request handle
namethe name of the header
valuethe value of the header
Returns
APR_SUCCESS on success
apr_status_t(* paa_client_request_struct::set_req_var) (const paa_client_request *req, const char *name, const char *value)

Sets a request-scoped variable or attribute in the client request.

Examples include environment variables for a CGI application or request attributes in a servlet container.

If the environment of the SDK consumer has no notion of a request-scoped variable or attribute, this function can safely be a no-op.

Parameters
reqthe request handle
namethe name of the variable
valuethe value of the variable
Returns
APR_SUCCESS on success
apr_status_t(* paa_client_request_struct::set_user) (const paa_client_request *req, const char *user)

Sets the user of the client request.

If the SDK consumer does not have a notion of a user for a request, this function can safely be a no-op.

Parameters
reqthe request handle
userthe user value to set
Returns
APR_SUCCESS on success

The documentation for this struct was generated from the following file: