Web Agent Function Pointers

The web agent function pointers must be written before calling the am_web_process_request() function to process a request. The function pointers defined in <am_web.h> are:

• am_web_add_header_in_response_func_t

• am_web_free_post_data_func_t

• am_web_get_cookie_sync_func_t

• am_web_get_post_data_func_t

• am_web_render_result_func_t

• am_web_result_set_header_func_t

• am_web_result_set_header_attr_in_request_func_t

• am_web_result_set_header_attr_in_response_func_t

• am_web_set_header_in_request_func_t

• am_web_set_method_func_t

• am_web_set_user_func_t

am_web_add_header_in_response_func_t

Adds (or sets) an HTTP header in a response.

Details

If a header of the same name already exists, it should be replaced with this header.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_add_header_in_response_func_t)
                               (void **args,
                                const char *name,
                                const char *val);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

name

Pointer to the name of the header.

val

Pointer to the value of the header.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the header was successfully added.

Appropriate am_status_t code

Otherwise.

am_web_free_post_data_func_t

Frees the data retrieved by am_web_get_post_data_func_t.

Details

The POST data can be NULL if it is not needed.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_free_post_data_func_t)
                               (void **args,
                                char *data);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

data

Pointer to the data.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the data was successfully freed.

Warning

If not successfully freed, the status will be logged as a warning but ignored.

am_web_get_cookie_sync_func_t

Synchronizes two cookies.

Details

Currently, this is a dummy function. Do not use.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_get_cookie_sync_func_t)(
                                const char *cookieName,
                                char **dproCookie,
                                void **args); 

Parameters

This function takes the following parameter:

cookieName

Pointer to the cookie with which the OpenSSO Enterprise cookie will be synchronized.

dproCookie

Pointer to a pointer to the OpenSSO Enterprise cookie.

args

Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the data was successfully freed.

Warning

If not successfully freed, the status will be logged as a warning but ignored.

am_web_get_post_data_func_t

Retrieves post data.

Details

The returned POST data must be NULL terminated and will be freed by calling am_web_free_post_data_func_t.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_get_post_data_func_t)
                               (void **args,
                                char **data);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

data

Pointer to a pointer to the data.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the data was successfully retrieved.

HTTP internal error

Otherwise

am_web_render_result_func_t

Renders an HTML page based on the result of a web agent's enforcement.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_render_result_func_t)
                               (void **args,
                                am_web_result_t http_result,
                                char *data);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

http_result

One of the following values of the am_web_result_t enumeration as defined:

#include "am_web.h"
typedef enum {
    AM_WEB_RESULT_OK,               /* access check was OK */
    AM_WEB_RESULT_OK_DONE,          /* OK and handled (for ex. notification) */
    AM_WEB_RESULT_FORBIDDEN,        /* access forbidden */
    AM_WEB_RESULT_REDIRECT,         /* redirected */
    AM_WEB_RESULT_ERROR             /* internal error */
} am_web_result_t;

For AM_WEB_RESULT_OK_DONE, the web agent should return an HTTP status code 200 OK and the body of the HTTP response should be set to the string in the data parameter. For AM_WEB_RESULT_REDIRECT, the web agent should return an HTTP status code 302 and the Location header should be set to the redirect URL in the data argument. More information on these request methods can be found in http://www.faqs.org/rfcs/rfc2068.html.

data

Pointer to a string defining user data, a URL, or other data.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If page was successfully rendered.

Warning

If not successfully freed, the status will be logged as a warning but ignored.

am_web_result_set_header_func_t

Sets LDAP attributes in an HTTP header.

Details

This function will be called when com.sun.am.policy.agents.config.profile.attribute.fetch.mode in the agent configuration properties is set to HTTP_HEADER. This property specifies if additional user profile attributes should be introduced into the request. Possible values are:

• NONE

• HTTP_HEADER

• HTTP_COOKIE

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_result_set_header_func_t)(
                                 const char *key,
                                 const char *attrValues, 
                                 void **args);

Parameters

This function takes the following parameter:

key

Pointer to the key to which the value will be set.

attrValues

Pointer to a string representing the values to be set.

args

Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file) including:

AM_SUCCESS

If the header was successfully set.

am_web_result_set_header_attr_in_request_func_t

Sets LDAP attributes defined in the request's HTTP cookie header.

Details

This function will be called when com.sun.am.policy.agents.config.profile.attribute.fetch.mode in the agent configuration properties is set to HTTP_COOKIE. This property specifies if additional user profile attributes should be introduced into the request. Possible values are:

• NONE

• HTTP_HEADER

• HTTP_COOKIE

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_result_set_header_attr_in_request_func_t)(
                                const char *cookieValues,
                                void **args);

Parameters

This function takes the following parameter:

cookieValues

Pointer to string representing the values in the cookie.

args

Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file) including:

AM_SUCCESS

If the header was successfully set.

am_web_result_set_header_attr_in_response_func_t

Sets LDAP attributes defined in the response's HTTP cookie header.

Details

This function will be called when com.sun.am.policy.agents.config.profile.attribute.fetch.mode in the agent configuration properties is set to HTTP_COOKIE. This property specifies if additional user profile attributes should be introduced into the request. Possible values are:

• NONE

• HTTP_HEADER

• HTTP_COOKIE

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_result_set_header_attr_in_response_func_t)(
                     const char *cookieValues,
                     void **args);

Parameters

This function takes the following parameter:

cookieValues

Pointer to string representing the values in the cookie.

args

Pointer to a pointer to agent defined parameters.

Returns

This function returns one of the values of the am_status_t enumeration (defined in the <am_types.h> header file) including:

AM_SUCCESS

If the header was successfully set.

am_web_set_header_in_request_func_t

Sets an HTTP header in a request.

Details

If a header of the same name already exists it should be replaced with this header.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_set_header_in_request_func_t)(
                     void **args, 
                     const char *name, 
                     const char *val);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

name

Pointer to the name of the header.

val

Pointer to the value of the header.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If header was successfully added.

Warning

If not successfully freed, the status will be logged as a warning but ignored.

am_web_set_method_func_t

Sets the request method to be used by a web agent during cross domain single sign-on (CDSSO).

Details

In cases of CDSSO actions between OpenSSO Enterprise and web agents, the POST request method is used by the web agent. am_web_set_method_func_t is required to change the request method to POST, if necessary, from the method defined in the original HTTP request. See Cross-Domain Single Sign-On Session in Sun OpenSSO Enterprise 8.0 Technical Overview for additional information.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_set_method_func_t)(
                                void **args, 
                                am_web_req_method_t method);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

method

One of the following values of the am_web_req_method_t enumeration as defined:

#include "am_web.h"
typedef enum {
    AM_WEB_REQUEST_UNKNOWN,
    AM_WEB_REQUEST_GET,
    AM_WEB_REQUEST_POST,
    AM_WEB_REQUEST_HEAD,
    AM_WEB_REQUEST_PUT,
    AM_WEB_REQUEST_DELETE,
    AM_WEB_REQUEST_TRACE,
    AM_WEB_REQUEST_OPTIONS
} am_web_req_method_t;

More information on these request methods can be found in http://www.faqs.org/rfcs/rfc2068.html.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If the method was successfully set.

HTTP forbidden result

Otherwise.

am_web_set_user_func_t

Sets the user.

Details

The implementation code sets the user.

Syntax

#include "am_web.h"
typedef am_status_t (*am_web_set_user_func_t)(
                     void **args, 
                     const char *user);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

user

Pointer to the user login.

Returns

This function returns one of the following values of the am_status_t enumeration (defined in the <am_types.h> header file):

AM_SUCCESS

If user was successfully set.

HTTP forbidden result

Otherwise.