Sun Java System Access Manager 7.1 C API Reference

Web Agent Functions

The web agent functions defined in <am_web.h> are:

`am_web_build_advice_response()`

Builds an advice response.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_build_advice_response(const am_policy_result_t *policy_result,
                             const char *redirect_url,
                             char **advice_response);

Parameters

This function takes the following parameter:

policy_result

Pointer to an am_policy_result_t data type.

Note –

See am_policy_result_t for information.

redirect_url

Pointer to a redirect URL.

advice_response

Pointer to a pointer to the location of the advice response.

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 query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_check_cookie_in_post()`

Retrieves a user's SSOToken.

Details

In cases of cross domain single sign-on, Access Manager sends out a user's SSOToken using POST. This method uses POST to retrieve the SSOToken and set it in the foreign domain.

Syntax

#include "am_web.h"
M_WEB_EXPORT am_status_t 
am_web_check_cookie_in_post(void ** args, 
                            char ** dpro_cookie,
                            char ** request_url,
                            char **orig_req, 
                            char *method,
                            char *response,
                            boolean_t responseIsCookie,
               am_status_t (*set_cookie)(const char *, void **),
                      void (*set_method)(void **, char *)
);

Parameters

This function takes the following parameter:

args

Pointer to a pointer to agent defined parameters.

dpro_cookie

Pointer to a pointer to the Access Manager cookie.

request_url

Pointer to a pointer to the CDSSO URL.

orig_req

Pointer to a pointer to the original request method.

method

Pointer to the changed method name.

response

Pointer to the response which will hold the POST data.

responseIsCookie

Returns one of the following values of the boolean_t enumeration (defined in the <am_types.h> header file):

B_TRUE: If using Liberty Alliance Project specifications.
B_FALSE: If Access Manager POST data.

set_cookie

Function pointer used to set the cookie in the foreign domain.

set_method

Function pointer used to reset the original method in the request.

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 query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_check_cookie_in_query()`

Retrieves the cookie from a query string.

Details

In older versions of Access Manager, when performing CDSSO, the cookie was part of the query string.

Syntax

AM_WEB_EXPORT am_status_t 
am_web_check_cookie_in_query(void **args, 
                             char **dpro_cookie,
                             const char *query,
                             char **request_url,
                             char ** orig_req, 
                             char *method,
                am_status_t (*set_cookie)(const char *, void **),
                       void (*set_method)(void **, char *)
);

Parameters

This function takes the following parameter:

args: Pointer to a pointer to agent defined parameters.
dpro_cookie: Pointer to a pointer to the Access Manager cookie.
query: Pointer to the query.
request_url: Pointer to a pointer to the CDSSO URL.
orig_req: Pointer to a pointer to the original request method.
method: Pointer to a pointer to the changed method name.
set_cookie: Function pointer used to set the cookie in the foreign domain.
set_method: Function pointer used to reset the original method in the request.

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 query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_clean_post_urls()`

Cleans up a post_urls_t data type.

Details

See post_urls_t for more information.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void 
am_web_clean_post_urls(post_urls_t *posturl_struct);

Parameters

This function takes the following parameter:

posturl_struct: Pointer to post_urls_t data type.

Returns

This function returns no values.

`am_web_cleanup()`

Cleans up any memory called by the am_web_* functions.

Details

This should be called before a web agent exits.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_cleanup();

Parameters

This function does not take any 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 cleanup was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

`am_web_create_post_page()`

Creates an HTML form that submits the POST data with invisible name/value pairs.

Syntax

#include "am_web.h"
AM_WEB_EXPORT char * 
am_web_create_post_page(const char *key,
                        const char *postdata,
                        const char *actionurl);

Parameters

This function takes the following parameters:

key: Pointer to the unique key identifying a POST data entry. It is used to remove post data once the page is re-posted.
postdata: Pointer to a browser encoded string representing the POST data entry.
actionurl: Pointer to the POST destination URL.

Returns

This function returns char * as the POST form to be submitted.

`am_web_create_post_preserve_urls()`

Constructs a post_urls_t data type during preservation of POST data.

Details

A post_urls_t data type contains a dummy POST URL, an action URL and a unique key. The dummy URL is filtered by the Server Application Function (SAF) to identify POST preservation redirects from general redirects. All three of these variables are required for POST preservation.

Syntax

#include "am_web.h"
AM_WEB_EXPORT post_urls_t *
am_web_create_post_preserve_urls(const char *request_url);

Parameters

This function takes the following parameter:

request_url: Pointer to the request URL for POST in the HTTP request.

Returns

This function returns a post_urls_t data type. See post_urls_t for information.

`am_web_do_cookie_domain_set()`

Sets the Access Manager cookie (called iPlanetDirectoryPro) for each domain configured in the com.sun.am.policy.agents.config.cookie.domain.list property in AMAgent.properties.

Details

am_web_do_cookie_domain_set() builds the set-cookie header for each domain, and calls the callback function declared in setFunc to set the cookie. In CDSSO, the callback function is called by am_web_check_cookie_in_query() and am_web_check_cookie_in_post() to set the cookie in the response.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_do_cookie_domain_set(am_status_t (*setFunc)(
                                         const char *, 
                                         void **),
                                         void **args, 
                                         const char *cookie);

Parameters

This function takes the following parameters:

setFunc: Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
args: Pointer to a pointer to agent defined parameters.
cookie: Pointer to the cookie.

Returns

This function returns a value of the am_status_t enumeration (defined in the <am_types.h> header file).

`am_web_do_cookies_reset()`

Resets the cookies in a response before redirecting it for authentication to the Access Manager login page.

Details

This function resets the cookies specified in AMAgent.properties and invokes the set action that the agent passes in for each of them. It is enabled by setting the following properties:

com.sun.am.policy.agents.config.cookie.reset.enable: This property must be set to true if the web agent needs to reset cookies in the response before redirecting them to Access Manager for Authentication. By default it is set to false.
com.sun.am.policy.agents.config.cookie.reset.list: This property (used only if com.sun.am.policy.agents.config.cookie.reset.enable is enabled) contains a comma-separated list of cookies that need to be included in the response redirected to Access Manager.

See the AMAgent.properties file for more information.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_do_cookies_reset(am_status_t (*setFunc)(
                                     const char *,
                                     void **),
                                     void **args);

Parameters

This function takes the following parameters:

setFunc: Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
args: Pointer to a pointer to agent defined parameters.

Returns

This function returns a value of the am_status_t enumeration (defined in the <am_types.h> header file).

`am_web_free_memory()`

Frees memory previously allocated by a am_web_* routine.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_free_memory(void *memory);

Parameters

This function takes the following parameter:

memory: Pointer to the memory.

Returns

This function returns no value.

`am_web_get_agent_server_host()`

Retrieves the name of the server host for the agent.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_agent_server_host();

Parameters

This function takes no parameters.

Returns

This function returns then name of the server host.

`am_web_get_agent_server_port()`

Retrieves the port used by the agent on the server host.

Syntax

#include "am_web.h"
AM_WEB_EXPORT int
am_web_get_agent_server_port();

Parameters

This function takes no parameters.

Returns

This function returns a port number.

`am_web_get_authType()`

Determines if the auth-type value DSAME should be replaced by Basic in the Sun Java System Access Manager Policy Agent 2.2 for Microsoft IIS 6.0.

Details

The Sun Java System Access Manager Policy Agent 2.2 for Microsoft IIS 6.0 is defined in <am_web.h> as having auth-type value equal to DSAME.

#define     AM_WEB_AUTH_TYPE_VALUE     "DSAME"

DSAME is a hard-coded value representing all Access Manager authentication types other than Basic.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_authType();

Parameters

This function takes no parameters.

Returns

This function returns either DSAME or Basic.

`am_web_get_cookie_name()`

Retrieves the name of the Access Manager cookie.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_cookie_name();

Parameters

This function takes no parameters.

Returns

This function returns the name of the Access Manager cookie.

`am_web_get_notification_url()`

Retrieves the URL of the Access Manager Notification Service.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_get_notification_url();

Parameters

This function does not take any parameters.

Returns

This function returns the URL of the Access Manager Notification Service.

`am_web_get_parameter_value()`

Gets the value of the specified parameter from the specified request URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_get_parameter_value(const char *inpQuery,
                           const char *param_name,
                           char **param_value);

Parameters

This function takes the following parameters:

inpQuery: Pointer to the request URL that holds the parameter.
param_name: Pointer to the name of the parameter.
param_value: Pointer to a pointer to be filled with the value of the param_name parameter, if found.

Returns

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

AM_SUCCESS: If the query parameter was found in the URL.
AM_*: If any other error occurred.

Memory Concerns

The returned parameter value should be freed by the caller using am_web_free().

`am_web_get_request_url()`

Parses the host request header field for a server host name, port, protocol, query parameter, and URI to return the requested URL to the web agent.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_get_request_url(const char *host_hdr,
                       const char *protocol,
                       const char *hostname,
                       size_t port,
                       const char *uri,
                       const char *query,
                       char **req_url);

Parameters

This function takes the following parameters:

host_hdr

Pointer to the host header string of the HTTP request as passed from the browser.

protocol

Pointer to the protocol used by the web container of the resource being requested.

hostname

Pointer to the name of the host on which the resource being requested.

port

Value based on the size_t defined in the standard <stddef.h> header file that reflects the port number of the resource being requested.

uri

Pointer to the URI of the HTTP request.

Note –

Most URLs have this basic form: protocol://server:port/request-URI. The request-URI portion of the URL is used by the web server to identify the document.

query

The query string appended to the request URL, if any. For example, if the URL is http://www.example.com?a=b&c=d, the value of this parameter would be a=b&c=d.

req_url

Pointer to a pointer to the OUT parameter to be populated with the value of the URL string to be used by the agent.

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 query parameter was found in the URL.
AM_*: If any other error occurred.

`am_web_get_url_to_redirect()`

Returns a string representing a login URL or access denied URL to which the web agent should redirect.

Caution –

am_web_get_redirect_url() has been deprecated and must not be used. It is supported for backward compatibility only.

Details

am_web_get_url_to_redirect() may redirect the user to the login URL or the access denied URL. The URL is appropriate to the provided status code and advice map returned by the Policy SDK. If redirecting to the login URL, the URL will include existing information specified in the URL from the configuration file (for example, the organization name) as well as the specified goto parameter value which will be used by Access Manager after the user has successfully authenticated. The last parameter reserved must be passed with NULL.

Note –

If the URL returned is not NULL, the caller of this function must call am_web_free_memory(void *) to free the pointer.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t 
am_web_get_url_to_redirect(am_status_t status,
                           const am_map_t advice_map,
                           const char *goto_url,
                           const char* method,
                           void *reserved,
                           char ** redirect_url);

Parameters

This function takes the following parameters:

status

The status from am_web_is_access_allowed().

Note –

See am_web_is_access_allowed().

advice_map

Any advice map from policy evaluation results.

goto_url

Pointer to the original URL which the user attempted to access.

method

Pointer to the original HTTP method: GET or POST.

reserved

This parameter is not currently used.

redirect_url

Pointer to a pointer containing the resulting Access Manager redirect URL.

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 successful.
AM_*: Otherwise.

`am_web_get_token_from_assertion()`

Returns the single sign-on token from the specified Security Assertion Markup Language (SAML) assertion.

Details

am_web_get_token_from_assertion() is used to retrieve the cookie sent by Access Manager in a SAML assertion.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_get_token_from_assertion(char *assertion,
                                char **token);

Parameters

This function takes the following parameters:

assertion: Pointer to the SAML assertion as an XML string.
token: Pointer to a pointer containing the single sign-on token identifier.

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 successful.
AM_*: Otherwise.

Memory Concerns

The returned identifier should be freed using am_web_free().

`am_web_handle_notification()`

Handles notification data received by a web agent.

Details

am_web_handle_notification() generates logging messages for the event and any error that may occur during the processing of the notification.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_handle_notification(const char *data,
                           size_t data_length);

Parameters

This function takes the following parameters:

data: Pointer to the notification message as an XML string.
data_length: Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the notification message.

Returns

This function returns no value.

`am_web_http_decode()`

URL decodes the specified URL encoded string.

Syntax

#include "am_web.h"
AM_WEB_EXPORT char *
am_web_http_decode(const char *string, 
                   size_t len);

Parameters

This function takes the following parameters:

string: Pointer to the URL encoded string.
len: Value based on the size_t defined in the standard <stddef.h> header file that reflects the length of the string.

Returns

This function returns the URL decoded value of the URL encoded string, or NULL if an error occurred.

Memory Concerns

The returned value should be freed by calling am_web_free().

`am_web_init()`

Initializes the web agent.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_init(const char *config_file);

Parameters

This function takes the following parameter:

config_file: Pointer to the agent configuration file as in/etc/opt/AMAgent.properties.

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 call was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

`am_web_is_access_allowed()`

Evaluates the access control policies for a specified web resource and action against those for a specified user.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t 
am_web_is_access_allowed(const char *sso_token,
                         const char *url,
                         const char *path_info,
                         const char *action_name,
                         const char *client_ip,
                         const am_map_t env_parameter_map,
                         am_policy_result_t *result);

Parameters

This function takes the following parameters:

sso_token: Pointer to the session token from the Access Manager cookie. This parameter may be NULL if there is no cookie present.
url: Pointer to the web resource URL. This parameter may not be NULL.
path_info: Pointer to the path information in the web resource URL, if any.
action_name: Pointer to the action (GET, POST, etc.) being performed on the specified resource URL. This parameter may not be NULL.
client_ip: Pointer to the IP address of the client attempting to access the specified resource URL. If client IP validation is turned on, this parameter may not be NULL.
env_parameter_map: A map object containing additional information about the user attempting to access the specified resource URL. This parameter may not be NULL.
advices_map_ptr: An output parameter where the am_map_t can be stored if the policy evaluation produces any advice information. This parameter may not be NULL. See am_map_t for more information.
result: Pointer to a policy result object.

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 evaluation was performed successfully and access is allowed.
AM_NO_MEMORY: If the evaluation was not successfully completed due to insufficient memory being available.
AM_INVALID_ARGUMENT: If any of the url, action_name, env_parameter_map, or advices_map_ptr parameters is NULL or if client IP validation is enabled and the client_ip parameter is NULL.
AM_INVALID_SESSION: If the specified session token does not refer to a currently valid session
AM_ACCESS_DENIED: If the policy information indicates that the user does not have permission to access the specified resource or any error is detected other than the ones listed above.

`am_web_is_cdsso_enabled()`

Returns a boolean specifying whether cross domain single sign-on is enabled in the agent’s configuration file.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_cdsso_enabled();

Parameters

This function takes no parameters.

Returns

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

B_TRUE: If cross domain single sign-on is enabled.
B_FALSE: Otherwise.

`am_web_is_cookie_present()`

Detects whether a cookie is present.

Details

This function will most probably be invoked in a loop. A cookie name and value is passed and the implementation checks whether the cookie is already listed. If not, the new cookie name and value are appended. If present, the value of the cookie name is updated.

Syntax

#include "am_web.h"
AM_WEB_EXPORT int 
am_web_is_cookie_present(const char *cookie,
                         const char *value,
                         char **new_cookie);

Parameters

This function takes the following parameters:

cookie: Pointer to a cookie.
value: Pointer to a value.
new_cookie: Pointer to a pointer to the location of the new cookie.

Returns

This function returns one of the following integers as defined in <am_web.h>:

#define AM_WEB_COOKIE_EXIST             2
#define AM_WEB_COOKIE_MODIFIED          1
#define AM_WEB_COOKIE_ABSENT            0
#define AM_WEB_COOKIE_ERROR            -1

`am_web_is_debug_on()`

Returns a boolean specifying whether debug is enabled.

Details

am_web_is_debug_on() specifies whether the log level is set to anything greater than 0.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_debug_on();

Parameters

This function takes no parameters.

Returns

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

B_TRUE: If the log level is set to anything greater than 0.
B_FALSE: Otherwise.

`am_web_is_in_not_enforced_ip_list()`

Returns a boolean specifying whether the given IP address is defined as one where no authentication or authorization is required.

Details

IP addresses that are not enforced are defined in the com.sun.am.policy.agents.config.notenforced_client_ip_list property in AMAgent.properties. If the IP address from where the request was issued is not enforced, the request goes through without authentication or authorization.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_in_not_enforced_ip_list(const char *ip);

Parameters

This function takes the following parameter:

ip: Pointer to the IP address.

Returns

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

B_TRUE: If the IP is in the not enforced IP address list.
B_FALSE: Otherwise.

`am_web_is_in_not_enforced_list()`

Returns a boolean specifying whether the URL being accessed by the user is in the not enforced list.

Details

URLs that are not enforced are defined in the com.sun.am.policy.agents.config.notenforced_list property in AMAgent.properties. If the URL is not enforced, the request goes through without authentication or authorization.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t 
am_web_is_in_not_enforced_list(const char *url,
                               const char *path_info);

Parameters

This function takes the following parameters:

url: Pointer to the URL being accessed.
path_info: Pointer to the path information in the URL being accessed, if any.

Returns

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

B_TRUE: If the URL is in the not enforced list.
B_FALSE: Otherwise.

`am_web_is_logut_url()`

Returns a boolean specifying whether the specified URL is a logout URL.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_logut_url(const char *url);

Parameters

This function takes the following parameter:

url: Pointer to a URL.

Returns

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

B_TRUE: If the specified URL is a logout URL.
B_FALSE: Otherwise.

`am_web_is_max_debug_on()`

Returns a boolean specifying whether the log level is set to 5.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_max_debug_on();

Parameters

This function takes no parameters.

Returns

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

B_TRUE: If the log level is set to 5.
B_FALSE: Otherwise.

`am_web_is_notification()`

Returns a boolean specifying whether the given URL is the Notification Service URL for the web agent as configured in AMAgent.properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_notification(const char *request_url);

Parameters

This function takes the following parameter:

request_url: Pointer to the Notification Service URL

Returns

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

B_TRUE: If the URL is the Notification Service URL of the agent as set in AMAgent.Properties.
B_FALSE: Otherwise.

`am_web_is_postpreserve_enabled()`

Returns a boolean specifying whether POST data preservation is enabled for clients in AMAgent.Properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_postpreserve_enabled();

Parameters

This function takes no parameters

Returns

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

B_TRUE: If POST data preservation is on.
B_FALSE: If POST data preservation is off.

`am_web_is_proxy_override_host_port_set()`

Determines if the com.sun.am.policy.agents.config.override_host and the com.sun.am.policy.agents.config.override_port properties are set for the proxy agent.

Details

These properties are defined in AMAgent.properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t am_web_is_proxy_override_host_port_set();

Parameters

This function takes no parameters.

Returns

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

B_TRUE: If set.
B_FALSE: Otherwise.

`am_web_is_valid_fqdn_url()`

Returns a boolean specifying whether the requested URL is a valid fully qualified domain name (FQDN) resource as configured in AMAgent.properties. For example, myhost.mydomain.com.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_is_valid_fqdn_url(const char *url);

Parameters

This function takes no parameters.

Returns

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

B_TRUE: If the URL is using a fully qualified domain name.
B_FALSE: Otherwise.

`am_web_log_always()`

Log the given message regardless of the log level set in AMAgent.properties.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void 
am_web_log_always(const char *fmt, ...);

Parameters

This function takes the following parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_log_auth()`

Log the given access allowed or denied message to the Access Manager logs.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_log_auth(am_web_access_t access_type,
                const char *fmt, ...);

Parameters

This function takes the following parameters:

access_type

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

#include "am_web.h"
typedef enum {
    AM_ACCESS_DENY = 0,
    AM_ACCESS_ALLOW
} am_web_access_t;

fmt

Pointer to a formatted string message as in printf.

Returns

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

B_TRUE: If the call was successful.
B_FALSE: Otherwise.

`am_web_log_debug()`

Log the given message at the debug level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_debug(const char *fmt, ...);

Parameters

This function takes the following parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_log_error()`

Log the given message at the debug log level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_error(const char *fmt, ...);

Parameters

This function takes the following parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_log_info()`

Log the given message at the info log level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_info(const char *fmt, ...);

Parameters

This function takes the following parameter:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_log_max_debug()`

Log the given message at maximum debug level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_max_debug(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_log_warning()`

Log the given message at the warning log level.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_log_warning(const char *fmt, ...);

Parameters

This function takes the following parameters:

fmt: Pointer to a formatted string message as in printf.

Returns

This function returns no values.

`am_web_logout_cookies_reset()`

Resets cookie configured for reset on user logout.

Details

The reset function passed in is called for each cookie configured for reset. If the function failed for any cookie, the last failed status is returned.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_logout_cookies_reset(am_status_t (*setFunc)(
                                         const char *, 
                                         void **),
                                         void **args);

Parameters

This function takes the following parameters:

setFunc: Function pointer with which the user can define their own function for setting the cookie in the foreign domain. The implementation defines the parameters.
args: Pointer to a pointer to agent defined parameters.

Returns

This function returns no values.

`am_web_method_num_to_str()`

Converts a am_web_req_method_t number to a string.

Details

This function is used for logging the method in the local debug logs. It takes in a method name and returns a string value (such as GET, or POST).

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_method_num_to_str(am_web_req_method_t method);

Parameters

This function takes the following parameter:

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 a pointer to the string. If the number passed is not recognized, UNKNOWN is returned.

`am_web_method_str_to_num()`

Converts a am_web_req_method_t string to a number.

Details

This function does the opposite of the previously defined am_web_method_num_to_str(). See am_web_method_num_to_str() for details.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_method_num_to_str(am_web_req_method_t method);

Parameters

This function takes the following parameter:

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 a pointer to the number If the string is not recognized, AM_WEB_REQUEST_UNKNOWN is returned.

`am_web_postcache_data_cleanup()`

Cleans up am_web_postcache_data_t data type.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_postcache_data_cleanup(am_web_postcache_data_t * const postentry_struct);

Parameters

This function takes the following parameter:

postentry_struct: Pointer to am_web_postcache_data_t data type.

Returns

This function returns no value.

`am_web_postcache_insert()`

Inserts POST data entry in the POST cache.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t 
am_web_postcache_insert(const char *key,
                        const am_web_postcache_data_t *value);

Parameters

This function takes the following parameters:

key: Pointer to the POST data preservation key for every entry.
value: Pointer to the am_web_postcache_data_t data type.

Returns

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

B_TRUE: If the insertion was successful.
B_FALSE: Otherwise.

`am_web_postcache_lookup()`

Looks up data in the POST cache.

Syntax

#include "am_web.h"
AM_WEB_EXPORT boolean_t
am_web_postcache_lookup(const char *key,
                        am_web_postcache_data_t *postdata_entry);

Parameters

This function takes the following parameters:

key: Pointer to the key to search POST data entry in POST data structure.
postdata_entry: Pointer to the am_web_postcache_data_t data type storing the POST data.

Returns

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

B_TRUE: If the search was successful.
B_FALSE: Otherwise.

`am_web_postcache_remove()`

Removes data from the POST cache.

Syntax

#include "am_web.h"
AM_WEB_EXPORT void
am_web_postcache_remove(const char *key);

Parameters

This function takes the following parameter:

key: Pointer to the key of the entry to be removed.

Returns

This function returns no value.

`am_web_process_request()`

Processes a request access check and returns a HTTP result to be rendered by the agent.

Details

The render status is returned in the render_sts argument.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_web_result_t
am_web_process_request(am_web_request_params_t *req_params,
                       am_web_request_func_t *req_func,
                       am_status_t *render_sts);

Parameters

This function takes the following parameters:

req_params: Pointer to a am_web_request_params_t data type.
req_func: Pointer to a am_web_request_func_t data type.
render_sts: Pointer to one of the values of the am_status_t enumeration as defined in the <am_types.h> header file.

Returns

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;

`am_web_remove_authnrequest()`

Removes those extra parameters from an authenticated request.

Details

When a user returns from CDSSO authentication, the request contains a list of parameters that were added when the user was authenticated. am_web_remove_authnrequest() removes these extra parameters so the request is forwarded to applications as it originally came from the browser.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_remove_authnrequest(char* inpString,
                           char **outString );

Parameters

This function takes the following parameters:

inpString: Pointer to the URL received after CDSSO authentication.
outString: Pointer to a pointer to the location of the new URL without the 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 successful.
AM_*: The type of error indicated by the status value.

Memory Concerns

The value returned should be freed using am_web_free().

`am_web_remove_parameter_from_query()`

Removes the given query parameter from the URL, if present.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_remove_parameter_from_query(const char* inpString,
                                   const char *remove_str,
                                   char **outString );

Parameters

This function takes the following parameters:

inpString: Pointer to the original URL.
remove_str: Pointer to the query parameter to be removed
outString: Pointer to a pointer to the location of the new URL without the query parameter.

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 call was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

Memory Concerns

The value returned should be freed using am_web_free().

`am_web_result_attr_map_set()`

Processes attr_response_map from a am_policy_result_t data type and performs the set action.

Details

This function replaces am_web_do_result_attr_map_set() which is deprecated. It needs to be explicitly declare to use it. See <am_web.h> for more information.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_result_attr_map_set(am_policy_result_t *result,
                           am_web_result_set_header_func_t setHeaderFunc,
                           am_web_result_set_header_attr_in_response_func_t setCookieRespFunc,
                           am_web_result_set_header_attr_in_request_func_t setCookieReqFunc,
                           am_web_get_cookie_sync_func_t getCookieSyncFunc,
                           void **args);

Parameters

This function takes the following parameters:

result

Pointer to the am_policy_result_t.

Note –

See am_policy_result_t for more information.

setHeaderFunc

Pointer to the am_web_result_set_header_func_t.

setCookieRespFunc

Pointer to the am_web_result_set_header_attr_in_response_func_t.

setCookieReqFunc

Pointer to the am_web_result_set_header_attr_in_request_func_t.

getCookieSyncFunc

Pointer to the am_web_get_cookie_sync_func_t.

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 call was successful.
AM_*: If any error occurs, the type of error indicated by the status value.

Memory Concerns

The value returned should be freed using am_web_free().

`am_web_result_num_to_str()`

Returns the name of a am_web_result_t as a string.

Syntax

#include "am_web.h"
AM_WEB_EXPORT const char *
am_web_result_num_to_str(am_web_result_t result);

Parameters

This function takes the following parameter:

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;

Returns

This function returns a pointer to the string. For example, AM_WEB_RESULT_OK returns AM_WEB_RESULT_OK. If the result code passed is not recognized, Unknown result code is returned.

`am_web_set_cookie()`

Sets the specified cookie in the cookie header of the request.

Syntax

#include "am_web.h"
AM_WEB_EXPORT am_status_t
am_web_set_cookie(char *cookie_header,
                  const char *set_cookie_value, 
                  char **new_cookie_header);

Parameters

This function takes the following parameters:

cookie_header: Pointer to the cookie header.
set_cookie_value: Pointer to the cookie name and value in the set-cookie response header form. This value should be the same as that of the cookieValues parameter of the am_web_result_set_header_attr_in_request_func_t function.
new_cookie_header: Pointer to a pointer to the original cookie header, or a new cookie header value which needs to be freed by the caller. This value can be NULL.

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 successful.
AM_*: The type of error indicated by the status value.