Sm_AgentApi_GetConfig()

Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Agent API Function Declarations (C) › Sm_AgentApi_GetConfig()

Sm_AgentApi_GetConfig()

Retrieves configuration information for an agent.

This function requires an Agent API version of v5.0 or later.

This function can read configuration information either from a configuration file or, on a Microsoft Windows platform, from the Windows Registry.

Syntax

int SM_EXTERN Sm_AgentApi_GetConfig (
   Sm_AgentApi_Init_t*   pInit, 
   const char*           lpszAgentName, 
   const char*           lpszPath
);

Parameter	I/O	Description
pInit	O	A pointer to an Sm_AgentApi_Init_t structure. Sm_AgentApi_GetConfig() retrieves agent configuration information and copies each setting to a field of pInit. To free the array of server structures that may be placed in Sm_AgentApi_Init_t, call Sm_AgentApi_FreeServers().
lpszAgentName	I	Name of the target agent. The function Sm_AgentApi_GetConfig() searches the agentname list for the agent name specified in lpszAgentName. If lpszAgentName is empty, Sm_AgentApi_GetConfig() searches for the default agent name. In the case of a v5.x or v6.x custom agent that is configured through central host configuration, this parameter is ignored.
lpszPath	I	Full path and name of the configuration file that contains the agent configuration information. Set this parameter as an empty string ("") only for the 4QMRx web agent on IIS. If lpszPath is an empty string, Sm_AgentApi_GetConfig() checks whether the agent is written for a WIN32 platform. If it is, the function searches the Windows Registry for configuration information. If it is not, the function returns SM_AGENTAPI_FAILURE.

Parameter

I/O

Description

pInit

A pointer to an Sm_AgentApi_Init_t structure. Sm_AgentApi_GetConfig() retrieves agent configuration information and copies each setting to a field of pInit.

To free the array of server structures that may be placed in Sm_AgentApi_Init_t, call Sm_AgentApi_FreeServers().

lpszAgentName

Name of the target agent. The function Sm_AgentApi_GetConfig() searches the agentname list for the agent name specified in lpszAgentName. If lpszAgentName is empty, Sm_AgentApi_GetConfig() searches for the default agent name.

In the case of a v5.x or v6.x custom agent that is configured through central host configuration, this parameter is ignored.

lpszPath

Full path and name of the configuration file that contains the agent configuration information. Set this parameter as an empty string ("") only for the 4QMRx web agent on IIS.

If lpszPath is an empty string, Sm_AgentApi_GetConfig() checks whether the agent is written for a WIN32 platform. If it is, the function searches the Windows Registry for configuration information. If it is not, the function returns SM_AGENTAPI_FAILURE.

Return Values

SM_AGENTAPI_SUCCESS. Configuration retrieval succeeded.
SM_AGENTAPI_FAILURE. Configuration retrieval failed.
SM_AGENTAPI_FAILURE is returned under any of these conditions:
- No agent name is specified in lpszAgentName, and Sm_AgentApi_GetConfig() cannot get the default agent name
- An agent name is specified in lpszAgentName, but Sm_AgentApi_GetConfig() cannot find that agent name
- Sm_AgentApi_GetConfig() cannot find at least one SiteMinder Policy Server configuration
- There is no path specified in lpszPath, and one of the following occurs:
  - The platform is not WIN32, so there are no Registry settings to retrieve.
  - Sm_AgentApi_GetConfig() cannot retrieve one of the required settings from the Registry. For example, it cannot open the Registry key that holds the shared secret.
  - There is a path specified in lpszPath, but Sm_AgentApi_GetConfig() cannot open and read the configuration file named in lpszPath.

Remarks

This function must be called by custom agents that are configured through central host configuration.

With v5.x or later agent connectivity:

The function’s lpszPath parameter references the SmHost.conf file created when the trusted host was registered with the Policy Server, or a WebAgent.conf file that references SmHost.conf.
The lpszAgentName parameter is ignored.

With 4.x agent connectivity:

The agent name is specified in the lpszAgentName parameter.
A v4.x WebAgent.conf file is referenced in lpszPath.

Sm_AgentApi_GetConfig() checks the value of lpszPath to find the path and name of a configuration file:

If lpszPath is empty and the agent is written for a Microsoft Windows platform, Sm_AgentApi_GetConfig() searches the Windows Registry for the configuration information.
If lpszPath is empty and the agent is running on a UNIX system, Sm_AgentApi_GetConfig() returns SM_AGENTAPI_FAILURE.

If Sm_AgentApi_GetConfig() cannot find the agent name, it uses the default agent name. If the default agent name cannot be retrieved, the function returns SM_AGENTAPI_FAILURE.

When Sm_AgentApi_GetConfig() locates the configuration information for the correct agent, it copies the information into the fields of an initialization structure (Sm_AgentApi_Init_t). The parameter pInit points to this initialization structure. For example, suppose the agent name parameter contains the string Agent1 and the agentname list of the configuration file is set as follows:

agentname="Agent1,123.112.12.12"

In this circumstance, Sm_AgentApi_GetConfig() sets the lpszHostName field of initialization structure pInit to Agent1. The IP Address is ignored. Sm_AgentApi_GetConfig() then retrieves the information for the other fields of the initialization structure.