User Object

IIlsUser::AddProtocol

HRESULT IIlsUser::AddProtocol(
    IIlsProtocol  *pProtocol,
    ULONG  *puReqID);

Adds a new protocol for the user's application.

Returns one of the following values:

S_OK	Success.
ILS_E_POINTER	Address of the protocol interface is NULL, or the address request identifier is NULL.
ILS_E_PARAMETER	A protocol by this name already exists.
ILS_E_FAIL	Could not add protocol; user is in the middle of registration or unregistration.
ILS_E_NOT_INITIALIZED	IIlsMain interface is not initialized.

pProtocol: Protocol object.
puReqID: Address of a ULONG buffer to receive the request identifier.

Depending on the User object registration state, this method can be either synchronous or asynchronous. If the User object is unregistered when the AddProtocol method is called to add a protocol object to the User object, this method returns synchronously and requires no interaction with the server. The protocol object will be added when the User object registers with the server. If the user object is already registered at the time of calling AddProtocol, the call is asynchronous and will involve sending an update to the server to add the Protocol object to the User object. If asynchronous, the application receives the IIlsUserNotify::ProtocolChangeResult notification for the request result.

IIlsUser::Clone

HRESULT IIlsUser::Clone(
    [out] IIlsUser **ppUser);

Returns a cloned version of the User object, with the identical set of standard and extended attributes set before this method is called.

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

ppUser: User object from which the application can clone user information.

A cloned object can be used to register the same user to different servers. There is no synchronization between the cloned and the original User object.

To ensure that all attributes are written correctly, the User object to be cloned should be registered on a server and updated before calling Clone.

IIlsUser::CreateProtocol

HRESULT IIlsUser::CreateProtocol(
    BSTR  bstrProtocolID,
    ULONG  uPortNumber,
    BSTR  bstrMimeType,
    IIlsProtocol  **ppProtocol);

Creates a Protocol object that represents a protocol the user's application can use to establish the communication channel.

Returns one of the following values:

S_OK Success.
ILS_E_POINTER Pointer to hold the protocol interface is NULL.
ILS_E_MEMORY Unable to allocate enough memory for this request.

bstrProtocolID: Null-terminated string for the protocol's unique identifier.
uPortNumber: Port number that is used by the protocol.
bstrMimeType: Null-terminated string for the protocol's MIME type.
ppProtocol: Pointer to receive the Protocol object.

IIlsUser::EnumProtocols

HRESULT IIlsUser::EnumProtocols(
    IIlsFilter  *pFilter,
    IIlsAttributes  *pAttributes,
    IEnumIlsProtocol  **ppEnumProtocol,
    ULONG  *puReqID);

Returns a protocol enumerator for the user's application, with an option to apply an enumeration filter and an option to retrieve extended protocol attributes.

Returns one of the following values:

S_OK	Success.
ILS_E_POINTER	Address request identifier is NULL.
ILS_E_ACCESS_DENIED	User object is not read-only.
ILS_E_NOT_INITIALIZED	IIlsMain interface is not initialized.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

pFilter: Filter object. This parameter is currently ignored.
pAttributes: Attributes object that contains the extended attributes to retrieve from the server. This parameter is currently ignored.
ppEnumProtocol: If the method is called synchronously, a pointer to receive the Enumerator 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 receives the IIlsUserNotify::EnumProtocolsResult notification for the enumeration result.

IIlsUser::GetAllExtendedAttributes

HRESULT IIlsUser::GetAllExtendedAttributes(
    IIlsAttributes  **ppAttributes);

Returns all extended attributes, in the form of an Attributes object, from the User object. This is an alternative to getting each extended attribute individually through IIlsUser::GetExtendedAttribute.

Returns one of the following values:

S_OK Success.
ILS_E_PARAMETER Return buffer pointer is NULL.
ILS_E_MEMORY Unable to allocate enough memory for this request.
ILS_E_ACCESS_CONTROL Attribute type is ILS_ATTRTYPE_NAME_ONLY.

ppAttributes: Buffer to receive the address of the Attributes object.

IIlsUser::GetExtendedAttribute

HRESULT IIlsUser::GetExtendedAttribute(
    BSTR  bstrName,
    BSTR  *pbstrValue);

Retrieves an extended attribute from a User object that was previously retrieved from the server.

Returns one of the following values:

S_OK	Success.
ILS_E_ACCESS_CONTROL	Attribute type is ILS_ATTRTYPE_NAME_ONLY.
ILS_E_POINTER	Address of the return buffer is NULL or attribute name is NULL.
ILS_E_PARAMETER	Attribute name is empty.
ILS_E_MEMORY	Unable to allocate enough memory for this request.
ILS_E_FAIL	Attribute not found.

bstrName: Name of the extended attribute.
pbstrValue: Address of the buffer to receive the value of the extended attribute.

IIlsUser::GetGuid

HRESULT IIlsUser::GetGuid(
    GUID  *pGuid);

Returns the GUID (globally unique identifier) of the retrieved User object.

Returns S_OK if successful, or ILS_E_POINTER if the address of the return buffer is invalid.

pGuid: Pointer to receive the GUID associated with this User object.

IIlsUser::GetProtocol

HRESULT IIlsUser::GetProtocol(
    BSTR  bstrProtocolID,
    IIlsAttributes  *pAttributes,
    IIlsProtocol  **ppProtocol,
    ULONG  *puReqID);

Requests a specific Protocol object that belongs to the user.

Returns one of the following values:

S_OK	Success.
ILS_E_POINTER	Address of the protocol identifier is NULL, or address request identifier is NULL.
ILS_E_ACCESS_DENIED	User object is not read-only.
ILS_E_FAIL	An error has occurred.
ILS_E_MEMORY	Unable to allocate enough memory for this request.
ILS_E_NOT_INITIALIZED	IIlsMain interface is not initialized.

bstrProtocolID: Specified protocol to retrieve.
pAttributes: 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.
ppProtocol: 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 IIlsUserNotify::GetProtocolResult notification for the request. The Protocol object can be used to retrieve information about the protocol.

IIlsUser::GetStandardAttribute

HRESULT IIlsUser::GetStandardAttribute(
    ILS_STD_ATTR_NAME  StdAttr,
    BSTR  *pbstrValue);

Returns a standard attribute belonging to the user.

Returns one of the following values:

S_OK Success.
ILS_E_POINTER Invalid address of an attribute variable.
ILS_E_MEMORY Unable to allocate enough memory for this request.
ILS_E_PARAMETER Attribute name is invalid.

StdAttr

Standard attribute of the User object. Can be one of the following:

ILS_STDATTR_USER_ID	Unique identifier of the user.
ILS_STDATTR_IP_ADDRESS	IP address of the user.
ILS_STDATTR_EMAIL_NAME	E-mail name of the user.
ILS_STDATTR_FIRST_NAME	First name of the user.
ILS_STDATTR_LAST_NAME	Last name of the user.
ILS_STDATTR_CITY_NAME	Name of the city in which the user is located.
ILS_STDATTR_COUNTRY_NAME	Name of the country in which the user is located.
ILS_STDATTR_COMMENT	General textual comment.
ILS_STDATTR_FLAGS	Flags need to be set to "1" for the User object to be visible in enumeration.
ILS_STDATTR_APP_NAME	Unique string identifying the application.
ILS_STDATTR_APP_MIME_TYPE	MIME type used by the application.
ILS_STDATTR_APP_GUID	GUID (globally unique identifier) of the application.

pbstrValue

Pointer to receive a null-terminated string for the user's standard attribute.

NetMeeting uses two-letter country codes for ILS_STDATTR_COUNTRY_NAME.

IIlsUser::GetState

HRESULT IIlsUser::GetState(
    ILS_STATE  *pState);

Returns the registration state on the specified ILS server.

Returns S_OK if successful, or ILS_E_POINTER if there is an invalid address of the state variable.

pState

Address of a buffer to receive the current ILS state. Can be one of the following:

ILS_REGISTERING	The user is being registered with the ILS server.
ILS_REGISTERED	The user is registered with the ILS server.
ILS_UNREGISTERING	The user is unregistered with the ILS server.
ILS_UNREGISTERED	The user is not registered with the ILS server.
ILS_REGISTERED_BUT_INVALID	Server does not recognize the current user.
ILS_NETWORK_DOWN	Cannot connect to the server.

IIlsUser::GetVisible

HRESULT IIlsUser::GetVisible(
    DWORD  *pdwVisible);

Returns the visible state of the user.

Returns S_OK if successful, or ILS_E_POINTER if the address of the return buffer is invalid.

pdwVisible: Pointer to receive a DWORD for the user's visible state.

IIlsUser::IsWritable

HRESULT IIlsUser::IsWritable(
    BOOL *pValue);

Returns whether the User object can be written to.

Returns S_OK if successful, or ILS_E_POINTER if the return buffer pointer is NULL.

pValue: Address of the buffer to receive the Boolean variable.

User objects returned from enumeration or IIlsMain::GetUser cannot be written to, but those created through IIlsMain::CreateUser can.

IIlsUser::Register

HRESULT IIlsUser::Register(
    IIlsServer  *pServer,
    ULONG  *puReqID);

Publishes the user information to the ILS server.

Returns one of the following values:

S_OK	Success.
ILS_E_ALREADY_REGISTERED	This user is already registered on a server.
ILS_E_POINTER	Server pointer or request identifier is NULL.
ILS_E_ACCESS_DENIED	User object is read-only.
ILS_E_MEMORY	Unable to allocate enough memory for this request.
ILS_E_FAIL	Could not register; server or user is not in correct state.

pServer: Address of the ILS Server object.
puReqID: Address of a ULONG buffer to receive the request identifier.

This method is an asynchronous operation. The application receives the IIlsUserNotify::RegisterResult notification for the registration result.

IIlsUser::RemoveExtendedAttribute

HRESULT IIlsUser::RemoveExtendedAttribute(
    BSTR  bstrName);

Removes an extended attribute from the User object. The modification will not be reflected on the ILS server until the IIlsUser::Register or IIlsUser::Update method is called.

Returns one of the following values:

S_OK	Success.
ILS_E_ACCESS_DENIED	User object is not writable.
ILS_E_ACCESS_CONTROL	Attribute type is ILS_ATTRTYPE_NAME_ONLY.
ILS_E_POINTER	Attribute name is NULL.
ILS_E_PARAMETER	Attribute name is empty.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

bstrName: Name of the extended attribute to remove.

IIlsUser::RemoveProtocol

HRESULT IIlsUser::RemoveProtocol(
    IIlsProtocol  *pProtocol,
    ULONG  *puReqID);

Removes a protocol for the user's application.

Returns one of the following values:

S_OK	Success.
ILS_E_POINTER	Address of the protocol interface is NULL, or the address request identifier is NULL.
ILS_E_PARAMETER	No protocol by this name exists.
ILS_E_FAIL	Could not remove protocol; user is in the middle of registration or unregistration.

pProtocol: Protocol object.
puReqID: Address of a ULONG buffer to receive the request identifier.

This method is an asynchronous operation. The application receives the IIlsUserNotify::ProtocolChangeResult notification for the request result.

IIlsUser::SetExtendedAttribute

HRESULT IIlsUser::SetExtendedAttribute(
    BSTR  bstrName,
    BSTR  bstrValue);

Adds or modifies an extended attribute of the user. The modification will not be reflected on the ILS server until the IIlsUser::Register or IIlsUser::Update method is called.

Returns one of the following values:

S_OK	Success.
ILS_E_ACCESS_DENIED	User object is not writable.
ILS_E_ACCESS_CONTROL	Attribute type is ILS_ATTRTYPE_NAME_ONLY.
ILS_E_POINTER	Attribute name is NULL.
ILS_E_PARAMETER	Attribute name is empty.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

bstrName: Name of the extended attribute.
bstrValue: Value of the extended attribute.

IIlsUser::SetGuid

HRESULT IIlsUser::SetGuid(
    *pGuid);

Sets the GUID (globally unique identifier) of the User object. An application that creates the User object should insert its GUID in this property.

Returns S_OK if successful, or ILS_E_ACCESS_DENIED if the User object is read-only.

pGuid: Pointer that contains the GUID to be set for this User object.

IIlsUser::SetStandardAttribute

HRESULT IIlsUser::SetStandardAttribute(
    ILS_STD_ATTR_NAME  StdAttr,
    BSTR  bstrValue);

Allows the application to modify a standard attribute of the user. The modification will not be reflected on the ILS server until the IIlsUser::Register or IIlsUser::Update method is called.

Returns one of the following values:

S_OK Success.
ILS_E_ACCESS_DENIED User object is not writable.
ILS_E_MEMORY Unable to allocate enough memory for this request.
ILS_E_PARAMETER Attribute name is invalid.

StdAttr

Standard attribute of the User object. Can be one of the following:

ILS_STDATTR_USER_ID	Unique identifier of the user. Must be specified at the time of User object creation.
ILS_STDATTR_IP_ADDRESS	IP address of the user, specified as four octets specified in decimal; for example, "123.255.0.123". If this attribute is not set, the ILS interface automatically detects the network address and uses the found IP address.
ILS_STDATTR_EMAIL_NAME	E-mail name of the user.
ILS_STDATTR_FIRST_NAME	First name of the user.
ILS_STDATTR_LAST_NAME	Last name of the user.
ILS_STDATTR_CITY_NAME	Name of the city in which the user is located.
ILS_STDATTR_COUNTRY_NAME	Name of the country in which the user is located.
ILS_STDATTR_COMMENT	General textual comment.
ILS_STDATTR_FLAGS	Flags to indicate the visibility of the User object on the server. Use IIlsUser::SetVisible to modify this flag.
ILS_STDATTR_APP_NAME	Unique string identifying the application. Cannot set this attribute. Must be specified at the time of User object creation.
ILS_STDATTR_APP_MIME_TYPE	MIME type used by the application.
ILS_STDATTR_APP_GUID	GUID (globally unique identifier) of the application.
ILS_STDATTR_PROTOCOL_NAME	Applies to the protocol object.
ILS_STDATTR_PROTOCOL_MIME_TYPE	Applies to the protocol object.
ILS_STDATTR_PROTOCOL_PORT	Applies to the protocol object.

bstrValue

Null-terminated string for the user's standard attribute.

A user's email name is used his/her default user id (ILS_STDATTR_USER_ID) on the server. The ILS server enforces the uniqueness of this attribute.

NetMeeting uses two-letter country codes for ILS_STDATTR_COUNTRY_NAME.

ILS servers use Email name (ILS_STDATTR_EMAIL_NAME) and Country code (ILS_STDATTR_COUNTRY_NAME) as part of the full LDAP path on the server. As a result, these attributes cannot be modified using this method while the user is registered on the server. To modify these attributes, log off the server and create a new user object with the desired changes.

IIlsUser::SetVisible

HRESULT IIlsUser::SetVisible(
    DWORD  fVisible);

Allows the application to modify the visibility state for the user. The modification will not be reflected on the ILS server until the IIlsUser::Register or IIlsUser::Update method is called.

Returns S_OK if successful, or ILS_E_ACCESS_DENIED if the User object is read-only.

fVisible: DWORD containing the user's visible state. A value of 0x01 indicates this User object is to be made visible to enumeration. A value of 0x00 indicates this User object is not visible for enumeration, but will succeed if the matching user identifier is requested in IIlsMain::GetUser operations.

IIlsUser::Unregister

HRESULT IIlsUser::Unregister(
    ULONG  *puReqID);

Removes the User object from the specified ILS server.

Returns one of the following values:

S_OK Success.
ILS_E_NOT_REGISTERED This user is not registered on a server.
ILS_E_ACCESS_DENIED User object is read-only.
ILS_E_MEMORY Unable to allocate enough memory for this request.

puReqID: Address of a ULONG buffer to receive the request identifier.

This method is an asynchronous operation. The application receives the IIlsUserNotify::RegisterResult notification for the unregistration result.

It is not recommended to use this method if the registration is in progress (that is, the IIlsUser state is ILS_REGISTERING).

IIlsUser::Update

HRESULT IIlsUser::Update(
    ULONG  *puReqID);

Reflects updated user information to the ILS server.

Returns one of the following values:

S_OK	Success.
S_FALSE	No modifications have been made; there is no need to update this user.
ILS_E_NOT_REGISTERED	This user is not registered on a server.
ILS_E_POINTER	Address of the request identifier is NULL.
ILS_E_MEMORY	Unable to allocate enough memory for this request.

puReqID: Address of a ULONG buffer to receive the request identifier.

This method is an asynchronous operation. The application receives the IIlsUserNotify::UpdateResult notification for the registration result.

EnumProtocolsResult
GetProtocolResult
ProtocolChangeResult
RegisterResult
StateChanged
UpdateResult

IConnectionPointContainer

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

IConnectionPoint

The IConnectionPoint_IIlsUser interface is instantiated from IConnectionPointContainer_IIlsUser. The User object provides only one connection point—IID_IIlsUserNotify—for a client's sink object to receive the callback notification. The client must provide the IIlsUserNotify interface methods described in this section in the sink object.

IIlsUserNotify Interface

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

IIlsUserNotify::EnumProtocolsResult

HRESULT IIlsUserNotify::EnumProtocolsResult(
    ULONG  uReqID,
    IEnumIlsProtocol  *pEnumProtocol,
    HRESULT  hResult);

Notifies the application of the result of the protocol enumeration request. If the request is successful, pEnumProtocol contains a valid protocol identification enumerator.

Returns S_OK if successful, or an error code otherwise.

uReqID: Request identifier matching the IIlsUser::EnumProtocols method.
pEnumProtocol: Protocol identification enumerator.
hResult: Enumeration result. Returns S_OK if the enumerator is valid, or an error code otherwise.

IIlsUserNotify::GetProtocolResult

HRESULT IIlsUserNotify::GetProtocolResult(
    ULONG  uReqID,
    IIlsProtocol  *pProtocol,
    HRESULT  hResult);

Notifies the application of the result of the protocol resolve request. If the request is successful, pProtocol contains a valid Protocol object.

Returns S_OK if successful, or an error code otherwise.

uReqID: Request identifier matching the IIlsUser::GetProtocol method.
pProtocol: Protocol object.
hResult: Modification result. Returns S_OK if the Protocol object is valid, or an error code otherwise.

IIlsUserNotify::ProtocolChangeResult

HRESULT IIlsUserNotify::ProtocolChangeResult(
    ULONG  uReqID,
    HRESULT  hResult);

Notifies the application of the result of the protocol add and remove requests. If the request is successful after registration, the information is propagated to the ILS server.

Returns S_OK if successful, or an error code otherwise.

uReqID: Request identifier matching the IIlsUser::AddProtocol or IIlsUser::RemoveProtocol method.
hResult: The modification result. Returns S_OK if the information is changed, or an error code otherwise.

IIlsUserNotify::RegisterResult

HRESULT IIlsUserNotify::RegisterResult(
    ULONG  uReqID,
    HRESULT  hResult);

Notifies the application of the result of the user register/unregister requests.

Returns S_OK if successful, or an error code otherwise.

uReqID: Request identifier matching the IIlsUser::Register or IIlsUser::Unregister method.
hResult: Result of the register/unregister request. Returns S_OK, or an error code otherwise.

IIlsUserNotify::StateChanged

HRESULT IIlsUserNotify::StateChanged(
    ULONG  fPrimary,
    BSTR  bstrServerName);

Notifies the application when the server state for the User object has changed. When notified, the application should call IIlsUser::GetState for the new state information.

Returns S_OK if successful.

fPrimary: If set to TRUE, the application can optionally put up a dialog box to inform the user about a state change. If set to FALSE, the application should not notify the user.
bstrServerName: Null-terminated string containing the name of the server whose state has changed.

IIlsUserNotify::UpdateResult

HRESULT IIlsUserNotify::UpdateResult(
    ULONG  uReqID,
    HRESULT  hResult);

Notifies the application of the result of the user update requests.

Returns S_OK if successful, or an error code otherwise.

uReqID: Request identifier matching the IIlsUser::Update method.
hResult: Result of the update request. Returns S_OK, or an error code otherwise.