The following functions operate on entities (objects):
Returns the number of entities found by the last query command.
Returns an entity handle of type LCA_QENT_H for the Nth entity.
Returns an entity handle of type LCA_QENT_H for the first entity in a list.
Returns an entity handle of type LCA_QENT_H for the next entity in a list.
Returns an entity handle of type LCA_QENT_H for the specified object in the entity list.
Returns the name of the object pointed to by an entity handle.
Returns the class name of the object pointed to by an entity handle.
The following functions operate on properties:
Returns the number of properties available for an entity.
Returns a property handle of type LCA_QPROP_H for the Nth property of an entity.
Returns a property handle of type LCA_QPROP_H for the first property of an entity.
Returns a property handle of type LCA_QPROP_H for the next property of an entity.
Returns a property handle of type LCA_QPROP_H for the specified property of an entity.
Returns the name of a property pointed to by a property handle.
Returns the size (in bytes) of a property.
Returns the type of a property.
Returns the number of values of a property.
Returns the property value list of a property.
Returns the Nth value for a single property.
Returns the first value in a list of property values.
Returns the next value in a list of property values.
Converts a property value to string format and copies it to a buffer.
Translates an indexed property value into a string and copies it to a buffer.
The following functions control remote authorization operations.
Logs in the remote authorization server.
Determines whether a user is allowed access to a resource.
The lca_Init function initializes the LCA. You must call lca_Init before using any other LCA function. This function also assigns a global variable with the value specified in the szModuleName parameter, a character string that identifies the calling module.
This function returns zero on success and nonzero on failure. If a failure occurs, ppOutput generally points to an error message.
int lca_Init (const char *szModuleName, char **ppOutput);
A string that identifies the module using this API.
Note: This parameter cannot be null or an empty string.
In case of failure, a pointer to a string that contains an error message.
The lca_Terminate function exits the LCA. It closes any open file descriptors, frees allocated buffers, resets the module name that was set by the lca_Init function, and unloads dynamically linked libraries.
This function does not return a value.
void lca_Terminate (void);
Note: Use this function only after processing the database with the lca_ParseLine function.
The lca_ParseLine function executes the command specified by the szLine parameter. After executing the command, the lca_ParseLine function sets the ppOutput parameter to point to a character string buffer returned by CA ControlMinder. The caller does not need to allocate any memory. This buffer is handled internally by the LCA and freed when you call the lca_Terminate function.
This function performs the following sequence of actions:
The lca_ParseLine function is state‑sensitive; that is, it changes the behavior of the commands that follow. For example, the following sequence lists the properties of user jan from host a:
lca_ParseLine(“hosts a”, output); lca_ParseLine(“showusr jan”, output);
A simple application that issues commands and displays the output may not need any function except lca_ParseLine. A more complex application may need more information, and, therefore, will probably need to use the other LCA functions.
This function returns zero on success and a nonzero value on error.
int lca_ParseLine (char *szLine, char **ppOutput);
A null‑terminated character string containing the command to be executed.
A pointer to a null‑terminated string containing the result returned by CA ControlMinder after it executes the command.
The lca_ParseMBLine function works in the same way as the lca_ParseLine function except that it:
This additional functionality support product localization and lets you input multibyte format strings.
The lca_CheckPasswordQuality function checks new passwords for users without changing them in the CA ControlMinder database or the native operating system through the sepass utility (for UNIX), selang, or Policy Manager. You can check passwords for adherence to CA ControlMinder password rules. A password is accepted or rejected based on the rules.
If the password is acceptable the function returns zero. If the password is denied, the function returns that the password is denied and gives the rule it failed.
int lca_CheckPasswordQuality (char *szUNAME, char *szPassword, CHECK_RSULT **res, int domain);
The user requesting the password change.
The password that the user wants to change to.
Specifies the handle for the result of the access request.
Specifies the domain to check the password in.
Note: This variable is for future use. It is implemented only in SEOS_DOMAIN.
The lca_ErrsGetNum function returns the number of errors, warnings, and information messages returned by CA ControlMinder after executing the last command sent to it by the lca_ParseLine function.
If there are no errors, warnings, or information messages, the function returns zero. Otherwise, it returns the total number of errors, warnings, and information messages returned.
int lca_ErrsGetNum (void);
The lca_ErrGetByIdx function returns an error handle of type LCA_ERR_H for the error with index idx. The idx parameter is the index in the list of errors and messages returned by CA ControlMinder after it executes the last command sent by the lca_ParseLine function.
The index ranges from 0 for the first error, to n_errors‑1 for the last error.
You can extract information about the error or message later with this handle, by using the lca_ErrSeverity and lca_ErrStage functions.
This function returns an error handle of type LCA_ERR_H on success, and returns NULL on failure.
LCA_ERR_H lca_ErrGetByIdx (int idx);
The index of the error in the error list of the last command.
The lca_ErrGetFirst function returns an error handle of type LCA_ERR_H for the first error that occurred in the last command sent to the lca_ParseLine function.
You can extract information about the error or message later with this handle, by using the lca_ErrSeverity and lca_ErrStage functions.
Note: This function acts like the lca_ErrGetNext function when you invoke the latter with a NULL handle.
This function returns an error handle of type LCA_ERR_H for the first error record and returns NULL on failure.
LCA_ERR_H lca_ErrGetFirst (void);
The lca_ErrGetNext function returns an error handle of type LCA_ERR_H for the next error that occurred in the last command sent to the lca_ParseLine function.
You can extract information about the error or message later with this handle, by using the lca_ErrSeverity and lca_ErrStage functions.
This function returns an error handle of type LCA_ERR_H for the next error record and returns NULL on failure.
LCA_ERR_H lca_ErrGetNext (const LCA_ERR_H errhPrev);
The handle of the previously returned error. If the value is NULL, the first error is returned.
The lca_ErrSeverity function returns the severity of an error, as represented by the error handle errh. The possible severity values are:
A fatal OS internal error (for example, memory allocation) occurred.
An error in the execution of a command occurred.
A command executed successfully, but a non‑fatal error occurred.
Not an error-the error string contains an information message or a warning.
This function returns the severity of the error and ‑1 on failure.
int lca_ErrSeverity (const LCA_ERR_H errh);
The handle of the error record.
The lca_ErrStage function returns the stage in which an error, represented by the error handle errh, occurred. The possible stage values are:
An error occurred while updating the database, such as an attempt to add an existing object, or an attempt to delete a nonexistent object.
The authorization process prevented the execution of the command; for example, the user did not have the authority to execute the command.
An error occurred in communication. This usually indicates that communication with the seagent or seosd daemon failed.
The connection to the remote host failed.
An error occurred that does not belong to any of the preceding categories. Usually this indicates a syntax error or an error in the command attributes.
Not an error-the error string contains an information message or a warning.
This function returns the stage of the error and ‑1 on failure.
int lca_ErrStage (const LCA_ERR_H errh);
The handle of the error record.
The lca_Err2Str function translates an error record into a string, and copies the string into szBuff. If the string is longer than iBuffLen, the lca_Err2Str function truncates it to the length specified in iBuffLen.
This function returns the number of printed characters on success and ‑1 on failure.
int lca_Err2Str (const LCA_ERR_H errh, char *szBuff, int iBuffLen);
The handle of the error record.
A buffer into which the function copies the output string.
The size of szBuff.
The lca_QEntsGetNum function returns the number of entities (objects) that were found by the last command sent to the lca_ParseLine function. If the last command was not a query, lca_QEntsGetNum returns zero. Otherwise, it returns the number of entities found that match the query criteria.
This function returns the number of entities (objects) fetched by the last query. If an error occurs, the function returns ‑1.
int lca_QEntsGetNum (void);
The lca_QEntGetByIdx function returns an entity handle for the entity with the index idx. The idx parameter is the index in the list of entities for the last command sent to the lca_ParseLine function.
The index ranges from zero for the first entity to n_entities‑1 for the last entity. For example, if the query returned three entities, idx can have a value of 0, 1, or 2. You can use this handle later to extract information about the entity.
For a query on a single object, such as showusr jan, the function returns an entity handle only if idx = 0; otherwise, it returns NULL. For a query on multiple objects, such as showusr jan*, it returns the entity handle specified by the idx parameter.
This function returns an entity handle of type LCA_QENT_H and returns NULL on failure.
LCA_QENT_H lca_QEntGetByIdx (int idx);
The index of the entity in the list of entities (objects) returned by the last query command.
The lca_QEntGetFirst function returns an entity handle of type LCA_QENT_H for the first entity in the list of entities returned by the last command sent to the lca_ParseLine function.
If you call the lca_QEntGetNext function with an attribute of NULL, you get the same results.
You can use this handle later to extract information about the entity.
This function returns only the first entity handle, regardless of how many entities the query returned. To return subsequent entity handles sequentially, use the lca_QEntGetNext function; to return a specific entity handle, use the lca_QEntGetByIdx function.
This function returns an entity handle of type LCA_QENT_H on success, and returns NULL on failure.
LCA_QENT_H lca_QEntGetFirst (void);
The lca_QEntGetNext function returns an entity handle of type LCA_QENT_H for the next entity in the list of entities for the last command sent to the lca_ParseLine function.
If the qenthPrev parameter is NULL, the function returns the first entity in the list. You can use this handle later to extract information about the entity.
This function returns an entity handle of type LCA_QENT_H on success and a NULL on failure.
LCA_QENT_H lca_QEntGetNext (const LCA_QENT_H qenthPrev);
The handle of the previous entity in the query's entity list.
The lca_QEntGetByName function returns an entity handle of type LCA_QENT_H for one entity in the list of entities for the last command sent to the lca_ParseLine function.
The function searches the entity list for an entity with a class name identical to szCName and an object name identical to szOName. (If szCName is empty, it searches only for a matching object name.) The function returns an entity handle for the matching entity. You can use the returned handle later to extract information about the entity.
This function returns an entity handle of type LCA_QENT_H on success and NULL on failure.
LCA_QENT_H lca_QEntGetByName (const char *szCName, const char *szOName);
A character string with the entity's class name.
A character string with the entity's object name.
The lca_QEntObjName function returns the name of the object to which the entity handle qenth points. The return value of the object name is empty (NULL) if the result of the query does not contain object names. For example, after executing the find command, which lists all the classes in the database, the returned string is empty because the query's result is class names and not object names. In this case, use the function lca_QEntClassName.
This function returns a pointer to a character string that contains the object name or NULL if the object name is empty.
char *lca_QEntObjName (const LCA_QENT_H qenth);
An entity handle.
The lca_QEntClassName function returns the name of the class of the entity to which the handle qenth points. The return value of the class name is empty (NULL) if the result of the query does not contain class names. For example, the find classname command returns only the object name for the specified class.
This function returns a pointer to a character string that contains the class name on success, or NULL on failure.
char *lca_QEntClassName (const LCA_QENT_H qenth);
An entity handle.
The lca_QPropsGetNum function returns the number of queried properties for the entity to which the handle qenth points. The assumption is that the entity was retrieved by the last command executed by the function lca_ParseLine.
The number of properties available for an object depends on the query. Exception: If the query was a find command, no properties are available because only object or class names are returned.
If the query was a showusr, showgrp , or showres command, this function counts all the properties that are set for the entity pointed to by qenth, and that can be displayed.
Note: The number of properties returned by this function is not necessarily the same as the total number of properties that exist in the database for the entity. Instead, the returned number represents the results of the last query for the entity. The entity handle is a handle that points to the data of the entity in the query, used only to access the query data using this API.
This function returns the number of properties available for the entity on success and ‑1 on failure.
int lca_QPropsGetNum (const LCA_QENT_H qenth);
An entity handle.
The lca_QPropGetByIdx function returns the property handle for the property whose index idx is in the property list of this entity. The index ranges from 0 for the first property, to n_props‑1 for the last one.
You can use the returned handle later to extract data about the property, when using the lca_QPropVal2StrEx, lca_QPropValGetFirst, lca_QPropValGetNext, and lca_QPropValList functions.
This function returns a property handle for the requested property. If no property with the specified index exists for this entity, the function returns NULL.
LCA_QPROP_H lca_QPropGetByIdx (const LCA_QENT_H qenth, int idx);
An entity handle that identifies an entity in the query.
The index of the requested property in the entity's property list.
The lca_QPropGetFirst function returns a property handle for the first property of the entity pointed to by the qenth parameter. You can use the returned handle later to extract data about the property, when using the lca_QPropVal2StrEx, lca_QPropValGetFirst, lca_QPropValGetNext, and lca_QPropValList functions.
This function returns a property handle. If there are no properties available in the query result of this entity, the function returns NULL.
LCA_QPROP_H lca_QPropGetFirst (const LCA_QENT_H qenth);
An entity handle that identifies an entity in the query.
The lca_QPropGetNext function returns the property handle of the property after the one in the qprophPrev parameter, for the entity pointed to by the qenth parameter. If the qprophPrev function is NULL, it returns the first property in the list.
You can use the returned handle later to extract data about the property, when using the lca_QPropVal2StrEx, lca_QPropValGetFirst, lca_QPropValGetNext, and lca_QPropValList functions.
This function returns a property handle. If there are no more properties available in the query result of this entity, the function returns NULL.
LCA_QPROP_H lca_QPropGetNext (const LCA_QENT_H qenth, \ const LCA_QPROP_H qprophPrev);
An entity handle that identifies an entity in the query.
Property handle of the last retrieved property.
The lca_QPropGetByName function returns a property handle-for the property whose name is in the szPName parameter-of the entity to which the qenth parameter points. You can use the returned handle later to extract data about the property, when using the lca_QPropVal2StrEx, lca_QPropValGetFirst, lca_QPropValGetNext, and lca_QPropValList functions.
This function returns a property handle. If there are no properties with this name, the function returns NULL.
LCA_QPROP_H lca_QPropGetByName (const LCA_QENT_H qenth const char szPName);
An entity handle that identifies an entity in the query.
A character string representing a property name.
The lca_QPropName function receives a property handle that identifies one property of an entity, and returns the property's name. This function belongs to a group of functions that retrieve information about a single property. The property name is the name defined in the database or, for UNIX queries, the symbolic name CA ControlMinder gives to UNIX properties.
This function returns a character string representing the property name on success and NULL on failure.
char *lca_QPropName (const LCA_QPROP_H qproph);
A property handle.
The lca_QPropSize function receives a property handle that identifies one property of an entity, and returns the property's size in bytes. This function belongs to a group of functions that retrieve information about a single property. The size is returned for a single value of the property. If it is a list property-such as an access control list (ACL)-the size of a single element is returned. To determine the size of the whole list, multiply the size of a single value by the number of values in the list. You can retrieve the number of values in the list by using the lca_QPropValsNum function.
This function returns the size of the property on success and ‑1 on failure.
unsigned short lca_QPropSize (const LCA_QPROP_H qproph);
A property handle.
The lca_QPropType function receives a property handle that identifies one property of an entity and returns the property's type. This function belongs to a group of functions that retrieve information about a single property. The possible property types are listed in the seostype.h header file.
This function returns a single character representing the property type on success and ‑1 on failure.
char lca_QPropType (const LCA_QPROP_H qproph);
A property handle.
The lca_QPropValsNum function receives a property handle identifying one property of an entity and returns the number of values for the property. This function belongs to a group of functions that retrieve information about a single property. For most properties, the number is always one. However, there are properties composed of lists that may have more than one value. Some examples of properties composed of lists are ACL, PACL, INetACL, UserList, and GroupList.
This function returns the number of values for the property on success. If the function fails, it returns ‑l.
unsigned int lca_QPropValsNum (const LCA_QPROP_H qproph);
A property handle.
The lca_QPropValList function returns the property value list for a single property identified by the qproph parameter. The returned value is an array of pointers to the values. If the property has a single value, only the first pointer is valid. To determine the number of valid pointers in the list, call the lca_QPropValsNum function.
This function returns a pointer to an array of pointers to the property values on success and NULL on failure.
void **lca_QPropValList (const LCA_QPROP_H qproph);
A property handle.
The lca_QPropGetByIdx_r function receives a property handle that identifies one property of an entity and returns a property value. The idx parameter identifies the property whose value the function will return.
This function identifies the value by its index in the value list for the property. The index ranges from 0 to one less than the value returned by the lca_QPropValsNum function.
To determine the number of values in the list, call lca_QPropValsNum. If necessary, use the lca_QPropVal2StrEx function to convert this value to a string.
This function returns a pointer to a single property value on success and NULL on failure.
void *lca_QPropValGetByIdx (const LCA_QPROP_H qproph, int idx);
A property handle.
An index to a value in the property (in case of a list property).
The lca_QPropValGetFirst function returns the first value in the list of values for the property identified by the parameter qproph. If necessary, use the lca_QPropVal2StrEx function to convert the value to a string.
This function returns a pointer to a single property value on success and a NULL on failure.
void *lca_QPropValGetFirst (const LCA_QPROP_H qproph);
A property handle.
The lca_QPropValGetNext function returns the next property value in the list of values for the property identified by the parameter qproph. The pPrevVal parameter identifies the previous value in the list. The function returns the value following pPrevVal. If pPrevVal is NULL, the function returns the first value in the list.
You can convert the value returned to a string later, using the function lca_QPropVal2StrEx.
This function returns a pointer to a single property value on success and a NULL on failure.
void *lca_QPropValGetNext (const LCA_QPROP_H qproph, const void *pPrevVal);
A property handle.
The previous value in the list.
The lca_QPropVal2Str function translates a property value into a string and copies the string into szBuff. If the string is longer than iBuffLen, the lca_QPropVal2Str function truncates it to the length specified in iBuffLen.
Important! This function is obsolete and is available for backward comparability purposes only. You should use the lca_QPropVal2StrEx function instead.
This function returns the number of printed characters on success and ‑1 on failure.
int lca_QPropVal2Str (const LCA_QPROP_H qproph, \ const void *pVal, char *szBuff, int iBuffLen);
A property handle.
A pointer to the property value to be translated.
A buffer into which the function copies the output string.
The size of szBuff.
The lca_rmtauth_Init function attempts to log in to the remote authorization server specified by the szHost parameter. This establishes a connection to the server checks whether the password passed by the szPasswd parameter matches the password of the user running the application. If it matches, the login process continues.
This function returns zero if login is successful, and a nonzero on failure. If login fails, the ppOutput parameter points to an error message.
int lca_rmtauth_Init (const char *szModuleName, \ char **ppOutput, char *szHost, char *szPasswd);
The name of the application.
Note: This parameter cannot be null or an empty string.
In case of failure, a pointer to an error message string.
The name of the server to connect to.
The password of the user accessing the server.
The lca_rmtauth_CheckAccess function queries the CA ControlMinder remote authorization server to determine whether the user-specified by szAccessor-is permitted to access the specified resource (szOName) when using the specified access type (szAccs). The function sends the request to the remote authorization server, which then performs the check using the SEOSROUTE_RequestAuth function.
This function returns zero if login is successful and a nonzero value on failure.
int lca_rmtauth_CheckAccess (const char *szAccessor, \ char *szClass, char *szOName, char *szAccs, API_AUTH_RES *result);
The name of the accessor (user) requesting authorization.
The resource whose access authorization is to be checked.
The resource object to which the user is requesting access.
The type of access requested. The valid access types are listed in the seostype.h header file.
The server's result of the access request.
Copyright © 2013 CA Technologies.
All rights reserved.
|
|