Gets an IMessengerContact object for given IMessengerContact::SigninName. Scriptable.
Syntax
HRESULT GetContact( [in] BSTR bstrSigninName, [in] BSTR bstrServiceId, [out, retval] IDispatch** ppMContact ); |
Parameters
- bstrSigninName
-
[in] A BSTR that contains the sign-in name of the remote user to create as a local IMessengerContact object.
- bstrServiceId
-
in] A BSTR that contains the globally unique identifier (GUID) service ID. If this parameter is not used, by passing in an empty string, the method searches the local user's contact list and not the services. The only valid service ID is the Live Communications Service ID.
- ppMContact
-
[out, retval] A pointer to a pointer to the IDispatch interface on the new (or existing) IMessengerContact object. The new object can now be accessed through the IMessengerContact interface.
Return Value
Returns one of the following values. For managed code applications, these return values are received in the form of a COMException.
- S_OK
-
Success.
- RPC_X_NULL_REF_POINTER
-
ppMContact is a null pointer.
- E_INVALIDARG
-
One of the following:
- bstrSigninName exceeded 129 characters.
- bstrSigninName contains spaces, a carriage return, or
linefeed.
- bstrServiceId exceeded 38 characters.
- bstrServiceId contains spaces, a carriage return, or
linefeed.
- bstrSigninName exceeded 129 characters.
- MSGR_E_USER_NOT_FOUND
-
A MessengerContact object for a contact that is not in the contact list.
- MSGR_E_NOT_LOGGED_ON
-
The client is not signed in. It must be signed in to check this value.
- E_FAIL
-
One of the following:
bstrSigninName is a null string.
bstrServiceId is a null string.
Remarks
Service-specific variations in the MessengerContact object might include the initial defaults for property values in cases in which the object is created but no update is possible because the contact is offline or not in the contact list.
ppMContact should be released when it is no longer needed. Even if you remove the MessengerContact object from all lists, the reference count does not reach zero until you release the pointer.
If the IMessenger::GetContact method is invoked more than once using the same bstrSigninName input string, the same pointer is returned each time as long as ppMContact is not released or otherwise destroyed.
If you are creating a MessengerContact object for a contact that is not in the contact list, be aware of the following considerations:
- The MessengerContact object is not fully valid
initially. It is an object in the Component Object Model (COM)
sense, but not a fully working object from the perspective of the
properties it stores. The IMessengerContact::Status
property initially returns MISTATUS_UNKNOWN and the IMessengerContact::FriendlyName
property returns the sign-in name.
- The initial bstrSigninName input value is returned for
the IMessengerContact::SigninName
property.
- These properties are populated initially when a DMessengerEvents::OnContactStatusChange
event is received for the contact and is updated whenever there are
changes with another DMessengerEvents::OnContactStatusChange
event.
Creating a MessengerContact object for a user or contact that does not exist in the server-side user store initially returns S_OK. Attempting to add this unverified MessengerContact object to the contact list, however, results in a MSGR_E_USER_NOT_FOUND error on the DMessengerEvents::OnContactListAdd event.
Example
The code in the example is retrieving an IMessengerContact object by making a call to the GetContact method of the IMessenger interface. If no valid IMessengerContact object is returned because of an error, an exception is thrown to this calling code. If a valid IMessengerContact is returned, the properties of the contact are used to build a string that is displayed at the console.
Copy Code | |
---|---|
IMessengerContact foundContact; StringBuilder sb = new StringBuilder(); try { foundContact = communicator.GetContact("jaya@contoso.com", communicator.MyServiceId) as IMessengerContact; sb.Append("Friendly Name: " + foundContact.FriendlyName.Trim()); sb.Append(Environment.NewLine); sb.Append("Blocked: " + foundContact.Blocked.ToString()); sb.Append(Environment.NewLine); sb.Append("Signin Name: " + foundContact.SigninName.ToString()); sb.Append(Environment.NewLine); sb.Append("Status: " + foundContact.Status.ToString()); Console.WriteLine(sb.ToString()); } catch (COMException CE) { Console.WriteLine(CE.ErrorCode.ToString()); } |
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