Called by the API to inform an application that an attempt has been made to sign in. Scriptable.

Syntax

HRESULT OnSignin(
   [in] LONG hr
);

Parameters

hr

[in] Success or error code as a LONG. For a table of the MSGR_E_* constants, see Error Codes.

An error result for hr might result in all other event parameters being meaningless, null, or otherwise invalid. Always check for a successful hr before attempting to use the other event parameters.

A negative result indicates a failure to connect; a positive or zero result indicates a successful connection. The possible values are:

  • S_OK. The local client has successfully signed in.

  • MSGR_E_INVALID_SERVER_NAME. The server could not be resolved. Host resolution is handled by an asynchronous Windows Sockets API (Winsock) function call. Although this sign-in request never actually reached a server, the return value is passed back as a self-generated DMessengerEvents::OnSignin event.

  • MSGR_E_CONNECT. The server address is resolved, but proxy configurations are incorrect, or some other Winsock APIs error prevented full connection to the server. Warning, error, or Network Monitor trace output might display more information.

  • MSGR_E_CANCEL. The user has canceled the sign-in attempt before connecting to any server.

  • MSGR_E_LOGON_TIMEOUT. The connection to the server was not established within 15 seconds of continuous negotiating or requesting states. (These are internal states that appear as the MISTATUS_LOCAL_CONNECTING_TO_SERVER state.)

  • MSGR_E_SERVER_VERSION. The connection to the server was established, but version differences between client and server prevented further protocol exchange. The client might be unable to continue.

  • MSGR_E_INVALID_PASSWORD. The password did not match the password for the given sign-in name in the server-side user store. Because there is no differentiation between the case of a nonexistent user and the case of an existing user but invalid password, MSGR_E_USER_NOT_FOUND is not a return hr for this method.

  • MSGR_E_SERVER_TOO_BUSY. Additional server-returned error code that translates to these locally generated error codes.

  • MSGR_E_SERVER_UNAVAILABLE. Additional server-returned error code that translates to these locally generated error codes.

  • MSGR_E_UNEXPECTED. Additional server-returned error code that translates to these locally generated error codes.

Return Value

The implementer of this event handler will determine what value should be returned.

Remarks

The OC Automation API will raise this event in response to a call to IMessenger::AutoSignin, IMessenger::Signin, or a local client user attempt to sign in from a Communicator instance. This event is raised when the API has made the request to sign in to the Office Communicator server. The result of that request is returned by DMessengerEvents::OnMyStatusChange asynchronously.

The implementer should not rely on OnSignin to determine if the local client is ready for other API calls and should instead wait for the DMessengerEvents::OnMyStatusChange event. The local client is ready if the event returns mMYStatus = MISTATUS_ONLINE.

Example

The example code uses the hr parameter to determine whether the local client request to sign in has succeeded. A non-zero hr value indicates the sign in failed.

Copy Code 
void communicator_OnSignin(int hr)
{
   if (hr != 0)
   {
	Console.WriteLine("Signin failed " + hr.ToString());
	return;
   }
   Console.WriteLine("Signin successful " + hr.ToString());
   connected = true;
}

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

See Also

Reference

DMessengerEvents