Starts the Communicator client Sign In dialog box and populates the sign-in name field. Scriptable.
The behavior of this method varies, depending on the client version, the host operating system, and the primary service for the client. For more information, see the "Remarks" section later in this topic.
Syntax
HRESULT Signin( [in] long hwndParent, [in] BSTR bstrSigninName, [in] BSTR bstrPassword ); |
Parameters
- hwndParent
-
[in] A LONG. Reserved. All current implementations should set this parameter to 0 or null.
- bstrSigninName
-
[in] The sign-in name of the user to be signed in as a BSTR.
- bstrPassword
-
[in] The password associated with the account of the user defined in bstrSigninName, as a BSTR. The password is entered as plain text but is passed through the protocol in a hashed format. The password is relevant only if bstrSigninName is not null or empty. The maximum allowable length for the password depends on the version of the client. For more information, see the "Remarks" section later in this topic.
Return Value
Returns one of the following values. In a managed code environment, this value is returned in a COMException event argument as an integer.
- S_OK
-
Success.
- S_FALSE
-
The Sign In dialog box is already open.
- E_INVALIDARG
-
The provided values failed validation tests. The sign-in name or password cannot contain spaces, carriage returns, or linefeed characters. Some services do not accept ANSI values greater than 128. The sign-in name cannot be longer than 129 characters (not including the terminating null character). The password cannot exceed the maximum password length, which is dependent on the version of the Communicator client. These are the input limits enforced on the client. There might be other limits established by the service on initial account creation.
- or -
The state of the Messenger object cannot be determined. In scripting, E_INVALIDARG are not returned in the first case because bstrSigninName and bstrPassword are always ignored.
- E_OUTOFMEMORY
-
The string comparison or concatenation failed, or memory could not be allocated for new objects created at sign-in.
- E_FAIL
-
Could not create a Sign In dialog box, or the Messenger object is not responding or has not been created.
- MSGR_E_ALREADY_LOGGED_ON
-
The current user is already signed in.
- S_FALSE
-
(Scripting) The current user is already signed in. S_FALSE cannot usually be captured in scripting error trapping, because the initial error bit is not 1 in this HRESULT.
- MSGR_E_AUDIO_UI_ACTIVE
-
The Audio and Video Tuning Wizard is already open.
- MSGR_E_option_UI_ACTIVE
-
The Options dialog box is already open.
- MSGR_E_OTHER_UI_ACTIVE
-
The Customer Experience Improvement Program (CEIP) dialog box is already open.
Remarks
The maximum allowable password length is 256 characters.
Unless called through scripting, the bstrSigninName parameter of this method partially prepopulates the Sign In dialog box, but it does not submit credentials to the server automatically, even if both user name and password are provided.
- If sign-in name and password are given as null strings,
user settings determine whether the fields are prepopulated. If the
user chose to save the password, the dialog box is populated with
previously saved credentials. The Windows® XP Credentials Manager
user interface will potentially cache all last-used credentials in
this circumstance. If no cached credentials exist, the field is
blank.
- If sign-in name and password are given as blank strings, the
behavior is the same as in the previous case.
- If sign-in name and password are given as non-empty strings,
the Sign In dialog box starts with fields populated by those
strings, even if credentials are cached. Although not recommended,
this approach can be useful in cases in which a client handles the
provisioning of a brand new service account (that is, the client is
prepopulating the dialog box with credentials that were just
created and thus could not yet be cached).
Calling this method initially displays the UI but does not perform automatic sign-in. The sign-in that the user initiates through the UI results in a DMessengerEvents::OnSignin event and a DMessengerEvents::OnMyStatusChange event with MISTATUS_LOCAL_CONNECTING_TO_SERVER, which lasts until the server receives and responds to the protocol-level logon command or the client-side timer window on logon expires. That state lasts until the server of the service receives and responds to the protocol-level logoff command. Otherwise, after 15 seconds without connecting to the server, the client-side timer cancels the logon attempt and generates a DMessengerEvents::OnMyStatusChange event with mMYStatusOE=MISTATUS_OFFLINE and hr=MSGR_E_LOGON_TIMEOUT.
If you do not want to display a sign-in dialog box to the user, use the IMessenger::AutoSignin method instead. The IMessenger::AutoSignin method requires that the client has access to cached credentials (that is, the user has selected Remember My Password in the client UI) or the user has saved credentials in the Windows XP Credentials Manager UI.
Example
In the following example, the Signin method is
surrounded by a try/catch structure to capture any COM exceptions
that might occur. The event argument returned by the COM exception
includes an ErrorCode property as an integer value. To
determine the error condition that raised the exception event, the
integer error code is converted to a HEX value and looked up in a
generic dictionary structure called comErrors
.
Copy Code | |
---|---|
void Signin(string account, string passwd) { if (connected) return; if (communicator == null) { // Create a Messenger object, if necessary communicator = new CommunicatorAPI.Messenger(); } // Register event handlers for OnSignin and Signout events communicator.OnSignin += new DMessengerEvents_OnSigninEventHandler(communicator_OnSignin); communicator.OnSignout += new DMessengerEvents_OnSignoutEventHandler(communicator_OnSignout); // Register more event handlers as appropriate. (Omitted) int parentHandle = 0; try { communicator.Signin(parentHandle, account, passwd); } catch (COMException CE) { Console.WriteLIne(returnComError(CE.ErrorCode)); } } public string returnComError(int comErrorCode) { string hexError = Microsoft.VisualBasic.Conversion.Hex(comErrorCode); return comErrors["0x" + hexError]; } private void loadComErrors() { comErrors.Clear(); //... Additional return codes loaded before comErrors.Add("0x81000302","MSGR_E_INVALID_SERVER_NAME"); comErrors.Add("0x81000303","MSGR_E_INVALID_PASSWORD"); comErrors.Add("0x81000304","MSGR_E_ALREADY_LOGGED_ON"); //... Additional return codes loaded after } |
Requirements
- Client
-
Requires Microsoft DirectX 9.0, C Runtime libraries (msvcm80.dll) on Microsoft Windows© Vista, Microsoft Windows XP Service Pack 1 (SP1) or later, or Microsoft Windows 2000 with Service Pack 4 (SP4). Any Communicator-imposed restrictions apply. .
- Server
-
Requires Microsoft Office Communications Server 2007, AV MCU (for Media Support), Media Relay (for NAT/Firewall traversal) on Microsoft Office Communications Server 2007.
- Product
-
Microsoft Office Communicator 2007 Automation API
- IDL file
-
Msgrua.idl