Share via

IMessenger::Signin Method

  • Article

Deprecated. Launches the Messenger client Sign In dialog box and populates the sign-in name field. The behavior of this method will vary, depending on the Messenger 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(      
    long hwndParent,
    BSTR bstrSigninName,
    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. For the Microsoft .NET Messenger Service, this should include the @ symbol and domain name.
  • 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 Messenger client. For more information, see the Remarks section later in this topic.

Return Value

For a table of all MSGR_E_* constants MSGRConstants, see.

Returns one of the following values:

S_OK Success.
S_FALSE The Sign In dialog box is already open.
E_INVALIDARG

Values provided failed validation tests. The sign-in name or password cannot contain spaces, carriage returns, or linefeed characters. Some services will 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 Messenger client. These are the input limits enforced on the client. There may be other limits established by the service upon initial account creation.

- or -

The state of the Messenger object cannot be determined. In scripting, E_INVALIDARG will not be returned in the first case because bstrSigninName and bstrPassword are always ignored.
E_OUTOFMEMORY String comparison or concatenation failed, or memeory couldnot be allocated for new objects created at sign-in.
E_FAIL Could not create an 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 is already open.
MSGR_E_OTHER_UI_ACTIVE The Customer Experience Improvement Program(CEIP) is already open.

Remarks

This method always displays the dialog box for the primary service. The Microsoft Exchange Instant Messaging Service (IM) client offers users the option to use Exchange, instead of the default of the .NET Messenger Service, as the primary service.

If the primary service is not signed in to, the IMessenger::Signin method will not launch the secondary sign-in dialog box for any configured secondary services on any client. The IMessenger::Signin API cannot be used to prepopulate the sign-in name or password for the secondary service Sign In dialog box or to suppress this dialog box if the credentials are not cached.

The Microsoft Windows Messenger APIs cannot recall or display the secondary sign-in dialog box independently if the primary service has been signed in to but the secondary service has not. Calling IMessenger::Signin in this case will return MSGR_E_ALREADY_LOGGED_ON, and neither the primary nor secondary sign-in dialog boxes will be displayed. To sign in to the secondary service when the primary service has already been signed in, a client user must either choose Sign In from the File menu or click the Not signed in to all services link in the client status bar.

This API also has an operating system dependency. The Credentials Manager component for version 4.0 is included in the Windows XP operating system and handles signing in to the client. Because the Credentials Manager has its own logic for saving passwords, all passwords passed to this API will be ignored. Passwords can be set through user input or Credentials Manager caching only. NULL or blank strings passed as user name will cause the Credentials Manager user interface (UI) to populate the user name based on the one last used and stored in its internal caching strategy. The very first time the Credentials Manager dialog box is displayed in the operating system, a new Windows Live ID registration sequence may be invoked in the UI. This is handled by the operating system and cannot be controlled by the Windows Messenger APIs.

The maximum allowable password length depends on the version of the Messenger client. For versions 4.7 and earlier, the maximum password length is 16 characters. For versions 5.0 or later of the Messenger client, the maximum password length increases to 256 characters.

Unless called through scripting, the bstrSigninNameparameter of this method will partially prepopulate the Sign In dialog box, but will 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 will determine whether the fields are prepopulated. If the user chose to save the password, the dialog box will be populated with previously saved credentials. The Windows XP Credentials Manager UI will potentially cache all last-used credentials in this circumstance. If no cached credentials exist, the fields will be 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 launches with fields populated by those strings, even if credentials are cached. Although not recommended, this approach may 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 initiated by the user through the UI will result 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 will cancel the logon attempt and generate a DMessengerEvents::OnMyStatusChange event with mMYStatusOE=MISTATUS_OFFLINE and hr=MSGR_E_LOGON_TIMEOUT.

If you do not wish to display a sign-in dialog box to the user, use the IMessenger::AutoSignin method instead. IMessenger::AutoSigninrequires that the client has access to cached credentials (that is, the user has selected the Remember My Password option in the client UI); the user has saved credentials in the Windows XP Credentials Manager UI; or the client has been modified to always save the password independent of operating system or user options.

Note  The following remarks apply to scripting languages.

  • This method is scriptable.
  • You should not return MSGR_E_NOT_LOGGED_ON to avoid an exception.
  • Clear the value returned to the user.

Important  IMessenger::Signin is no longer available in Windows Vista. See Windows Messenger for more information.

See Also

IMessenger::Signout