Sm_AgentApi_GetConfig()

Retrieves configuration information for an agent.
sm1252sp1
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 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
      CA Single Sign-On
      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.