ILS Object

An IIlsMain object is created from CoCreateInstance with a predefined class identifier (CLSID_UserLocationServices) and interface (IID_IIlsMain).

IIlsMain Interface
IConnectionPointContainer
IConnectionPoint—IIlsNotify Interface

Back to ILS Reference

IIlsMain Interface

The IIlsMain object provides the IIlsMain interface, which is instantiated from IID_IIlsMain. The interface provides the methods described in this section.

Abort
CreateAttributes
CreateFilter
CreateServer
CreateUser
EnumUserNames
EnumUsers
GetUser
Initialize
StringToFilter
Uninitialize

Back to ILS Object

IIlsMain::Abort

HRESULT IIlsMain::Abort(
    ULONG  uReqID);

Aborts the asynchronous request for the specified unique request identifier.

Returns one of the following values:

S_OK	Success.
ILS_E_PARAMETER	Request identifier doesn't match any currently in the queue.
ILS_E_FAIL	Not able to abort this type of request (register and unregister).
ILS_E_NOT_INITIALIZED	IIlsMain interface is not initialized.

uReqID: Identifier of the request being canceled.

This method will not abort a register or unregister process.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::CreateAttributes

HRESULT IIlsMain::CreateAttributes(
    ILS_ATTR_TYPE  AttrType,
    IIlsAttributes  ** ppAttributes);

Instantiates an Attributes object that can be used with an extended attribute request to the ILS server.

Returns one of the following values:

S_OK Success.
ILS_E_POINTER ppAttributes is NULL.
ILS_E_PARAMETER AttrType is incorrect.
ILS_E_MEMORY Unable to allocate enough memory for this request.

AttrType: Purpose of the Attributes object.
ppAttributes: Pointer to receive an empty Attributes object.

The Attributes object is currently overloaded to be used in two ways. The AttrType parameter enables the application to specify how the attribute is to be used:

ILS_ATTRTYPE_NAME_VALUE: First type/usage of the Attributes object is for the storage of attribute name/value pairs. This type is used for setting arbitrary attributes with IIlsUser. IIlsAttributes::GetAttribute also returns these Attributes object types.
ILS_ATTRTYPE_NAME_ONLY: Second type/usage of the Attributes object is to specify a list of attribute names. The attribute specifier is supplied as a parameter to IIlsMain::EnumUsers and IIlsMain::GetUser. It specifies the arbitrary attributes to be retrieved from the server.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::CreateFilter

HRESULT IIlsMain::CreateFilter(
    ILS_FILTER_TYPE  FilterType,
    ILS_FILTER_OP  FilterOp,
    IIlsFilter **ppFilter);

Creates a Filter object that can be used or manipulated.

Returns one of the following values:

S_OK	Success.
ILS_S_SERVER_MAY_NOT_SUPPORT	LDAP server might not support these types of filter operations.
ILS_E_POINTER	ppFilter is NULL.
ILS_E_PARAMETER	Filter operation and filter type are incompatible.
ILS_E_FILTER_TYPE	Filter type is invalid.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

FilterType

Type of the filter; can be either simple (ILS_FILTERTYPE_SIMPLE) or composite (ILS_FILTERTYPE_COMPOSITE).

FilterOp

Operator of the Filter object. The following options are available:

FilterOp must be one of the following if FilterType is ILS_FILTERTYPE_SIMPLE.

ILS_FILTEROP_EQUAL

ILS_FILTEROP_APPROX

ILS_FILTEROP_LESS_THAN

ILS_FILTEROP_GREATER_THAN

ILS_FILTEROP_EXIST

FilterOp must be one of the following if FilterType is ILS_FILTERTYPE_COMPOSITE.

ILS_FILTEROP_AND

ILS_FILTEROP_OR

ILS_FILTEROP_NOT

ppFilter

Address where the Filter object pointer is held.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::CreateServer

HRESULT IIlsMain::CreateServer(
    BSTR  bstrServerName,
    IIlsServer  **ppServer);

Creates an ILS Server object. The application can set the various parameters associated with a server, such as authentication credentials.

Returns one of the following values:

S_OK Success.
ILS_E_MEMORY Unable to allocate enough memory for this request.
ILS_E_POINTER Either or both parameters are NULL, thus invalid.

bstrServerName: Name of the server.
ppServer: Pointer to receive the ILS Server object.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::CreateUser

HRESULT IIlsMain::CreateUser(
    BSTR  bstrUserID,
    BSTR  bstrAppName,
    IlsUser  **ppUser);

Creates an ILS User object, which the client application can modify and register with a server.

Returns one of the following values:

S_OK Success.
ILS_E_MEMORY Unable to allocate enough memory for this request.
ILS_E_POINTER User pointer is NULL.
ILS_E_PARAMETER User name or application name is NULL.

bstrUserID: Unique identifier of the user.
bstrAppName: Name of the application to be registered.
ppUser: Pointer to receive the ILS User object.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::EnumUserNames

HRESULT IIlsMain::EnumUserNames(
    IIlsServer  *pServer,
    IIlsFilter  *pFilter,
    IEnumIlsNames  **ppEnumUserNames,
    ULONG  *puReqID);

Enumerates the names of the users currently registered on the specified ILS server.

Returns one of the following values:

S_OK	Success.
ILS_E_NOT_IMPL	User enumerator pointer is not NULL; synchronous interface is not yet implemented.
ILS_E_POINTER	Address of the server object, filter, or request identifier is NULL.
ILS_E_NOT_INITIALIZED	IIlsMain interface is not initialized.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

pServer: ILS Server object that specifies the server to enumerate.
pFilter: Filter object. If this parameter is NULL, the enumeration is performed without any filtering.
ppEnumUserNames: If the method is called synchronously, a pointer to receive the Enumerator object. (Unused pending implementation of synchronous operation of this method.) Must be NULL.
puReqID: Address of a ULONG buffer to receive the request identifier.

This method is currently an asynchronous operation, but the interface is defined to enable future implementation of synchronous operation. When called asynchronously, the application receives the IIlsNotify::EnumUserNamesResult notification for the enumeration result.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::EnumUsers

HRESULT IIlsMain::EnumUsers(
    IIlsServer  *pServer,
    IIlsFilter  *pFilter,
    IIlsAttributes  *pAttrib,
    IEnumIlsUser  **ppEnumUsers,
    ULONG  *puReqID);

Enumerates the list of User objects representing the users currently registered on the specified ILS server.

Returns one of the following values:

S_OK	Success.
ILS_E_NOT_IMPL	User enumerator pointer is not NULL; synchronous interface is not yet implemented.
ILS_E_POINTER	Address of the server object, filter, or request identifier is NULL.
ILS_E_NOT_INITIALIZED	IIlsMain interface is not initialized.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

pServer: ILS Server object that specifies the server to enumerate.
pFilter: Filter object. If this parameter is NULL, the enumeration is performed without any filtering.
pAttrib: Attributes object that contains the names of the extended attributes to retrieve from the server. If this parameter is NULL, the enumeration is performed without retrieving any extended attributes.
ppEnumUsers: If the method is called synchronously, a pointer to receive the Enumerator object. (Unused pending implementation of synchronous operation of this method.) Must be NULL.
puReqID: Address of a ULONG buffer to receive the request identifier.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::GetUser

HRESULT IIlsMain::GetUser(
    [in] IIlsServer  *pServer,
    [in] BSTR  bstrUserID,
    [in] BSTR bstrAppID,
    [in] BSTR  bstrProtID,
    [in] IIlsAttributes  *pAttrib,
    [out] IIlsUser  **ppILSUser,
    [out] ULONG  *puReqID);

Retrieves the detailed information for the specified user from the specified server.

Returns one of the following values:

S_OK	Success.
ILS_E_NOT_IMPL	User pointer is not NULL; synchronous interface is not yet implemented.
ILS_E_POINTER	Pointer parameters are NULL.
ILS_E_FAIL	IIlsMain interface is not initialized.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

pServer: Address of the ILS Server object.
bstrUserID: Null-terminated string for the user's unique identifier. The identifier is returned from the user enumeration.
bstrAppID: Null-terminated string for the user's application identifier.
bstrProtID: Null-terminated string for the user's protocol identifier.
pAttrib: Attributes object that contains the names of the extended attributes to retrieve from the server. If this parameter is NULL, the enumeration is performed without retrieving any extended attributes.
ppILSUser: If the method is called synchronously, a pointer to receive the User object. (Unused pending implementation of synchronous operation of this method.)
puReqID: Address of a ULONG buffer to receive the request identifier.

This method is currently an asynchronous operation, but the interface is defined to enable future implementation of synchronous operation. When called asynchronously, the application will receive the IIlsNotify::GetUserResult notification for the request result.

If bstrAppID is NULL, the globally unique identifier (GUID) returned from IIlsUser::GetGuid is all zeros.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::Initialize

HRESULT IIlsMain::Initialize(void);

Initializes the ILS for the application.

Returns one of the following values:

S_OK	Success.
ILS_E_FAIL	Interface is already initialized.
ILS_E_MEMORY	Unable to allocate enough memory for this request.
ILS_E_WINSOCK	WSA (Windows Socket API) services could not be started.
ILS_E_THREAD	Request thread could not be created.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::StringToFilter

HRESULT IIlsMain::StringToFilter(
    BSTR  bstrFilterString,
    IIlsFilter  **ppFilter);

Creates a Filter object that can be used or manipulated by supplying a syntactical description of the filter desired.

Returns one of the following values:

S_OK	Success.
ILS_E_POINTER	Filter string is NULL.
ILS_E_FAIL	Could not convert the string.
ILS_E_MEMORY	Unable to allocate enough memory for this request.
ILS_E_FILTER_STRING	Incorrect filter string.

bstrFilterString: Null-terminated string describing the construction of the filter.
ppFilter: Address where the Filter object pointer is held.

The full filter string definition will be specified in the next draft of the ILS interface. Following is a brief description:

The filter string takes the form ((Attribute=Value) & (Attribute=Value)).
The attributes are specified as $#, where # is the ordinal number in the ILS_STD_ATTR_NAME enumerator type (for example, "$1", "$4", and so on).
Value is the value that you want the attribute to match (for example, "john", "Washington", and so on).
The only supported logical concatenation operator for ILS version 1.x is AND, specified by "&".
An example filter string: (($1=jfk) & ($4=kennedy))

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IIlsMain::Uninitialize

HRESULT IIlsMain::Uninitialize(void);

Frees all the resources used by the current application.

Returns S_OK if successful, or ILS_E_FAIL if IIlsMain is not initialized.

Back to IIlsMain Interface

Back to ILS Object

Back to ILS Object Listing

IConnectionPointContainer

The IConnectionPointContainer_IIlsMain interface is instantiated from IID_IConnectionPointContainer to identify ILS as a connectable object. The interface contains the standard set of methods for IConnectionPointContainer_IIlsMain.

IConnectionPoint

The IConnectionPoint_IIlsMain interface is instantiated from IConnectionPointContainer_IIlsMain. The ILS object provides only one connection point—IID_IIlsNotify—for a client's sink object to receive the callback notification. The client must provide the IIlsNotify interface methods described in this section in the sink object.

IIlsNotify Interface

This interface is implemented by a client application that will receive notifications from an ILS object.

GetUserResult
EnumUserNamesResult
EnumUsersResult

Back to ILS Object

IIlsNotify::EnumUserNamesResult

HRESULT IIlsNotify::EnumUserNamesResult(
    ULONG  uReqID,
    IEnumIlsNames  *pEnumUserName,
    HRESULT  hResult);

Notifies the application of the result of the user name enumeration from an ILS server.

Returns S_OK if successful, or S_FALSE if an error occurred.

uReqID

Request identifier matching the IIlsMain::EnumUserNames method.

pEnumUserName

User's unique name enumerator. The user's unique name is a null-terminated string that the application can use to request the actual User object from the IIlsMain::GetUser method.

hResult

Enumeration result:

S_OK if the enumerator is valid and more users will be available. More users will be provided through the subsequent IIlsNotify::EnumUserNamesResult notification.
S_FALSE if the enumerator is NULL and no more users will be available.
An error code otherwise.

Back to IIlsNotify Interface

Back to ILS Object

Back to ILS Object Listing

IIlsNotify::EnumUsersResult

HRESULT IIlsNotify::EnumUsersResult(
    ULONG  uReqID,
    IEnumIlsUser  *pEnumUser,
    HRESULT  hResult);

Notifies the application of the result of the user enumeration from an ILS server.

Returns S_OK if successful, or S_FALSE if an error occurred.

uReqID

Request identifier matching the IIlsMain::EnumUsers method.

pEnumUser

User object enumerator.

hResult

Enumeration result:

S_OK if the enumerator is valid and more users will be available. More users will be provided through the subsequent IIlsNotify::EnumUsersResult notification.
S_FALSE if the enumerator is NULL and no more users will be available.
An error code otherwise.

Back to IIlsNotify Interface

Back to ILS Object

Back to ILS Object Listing

IIlsNotify::GetUserResult

HRESULT IIlsNotify::GetUserResult(
    ULONG  uReqID,
    IIlsUser  *pUser,
    HRESULT  hResult);

Notifies the application of the result of the user information request from an ILS server.

Returns S_OK if successful, or ILS_E_MEMORY if unable to allocate enough memory for this request.

uReqID: Request identifier matching the IIlsMain::GetUser method.
pUser: User object from which the application can retrieve the user information.
hResult: Resolution result: S_OK if the User object is valid, or an error code otherwise.

Back to IIlsNotify Interface

Back to ILS Object

Back to ILS Object Listing