Sm_AgentApi_GetConfig()
Retrieves configuration information for an agent.
casso10
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. |
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 inlpszAgentName, and Sm_AgentApi_GetConfig() cannot get the default agent name
- An agent name is specified inlpszAgentName, but Sm_AgentApi_GetConfig() cannot find that agent name
- Sm_AgentApi_GetConfig() cannot find at least oneCA Single Sign-OnPolicy Server configuration
- There is no path specified inlpszPath, 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 inlpszPath, but Sm_AgentApi_GetConfig() cannot open and read the configuration file named inlpszPath.
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’slpszPathparameter 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 thelpszAgentNameparameter.
- A v4.x WebAgent.conf file is referenced inlpszPath.
Sm_AgentApi_GetConfig() checks the value of
lpszPath
to find the path and name of a configuration file:- IflpszPathis empty and the agent is written for a Microsoft Windows platform, Sm_AgentApi_GetConfig() searches the Windows Registry for the configuration information.
- IflpszPathis 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.