HRESULT Signin(
   [in] long hwndParent,
   [in] BSTR bstrSigninName,
   [in] BSTR bstrPassword
);

Parameters

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.

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.

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 }

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

Reference