Gets or sets the tag status of a contact. Not scriptable.

Syntax


HRESULT IsTagged([out, retval] VARIANT_BOOL* pBoolIsTagged); HRESULT IsTagged([in] VARIANT_BOOL boolIsTagged);

Parameters

pBoolIsTagged: A pointer to a VARIANT_BOOL value as the tag status.

Return Value

An HRESULT of the following values. For managed code applications, these return values are received in the form of a COMException.

S_OK: The value is obtained or set successfully.

E_FAIL: The tag operation failed.

Remarks

The DMessengerEvents::OnContactStatusChange event continues to be raised in the same way as a non-tagged contact. A tagged contact causes the Office Communicator UI to display a "Toast" dialog when the tagged user has signed in or signed out.

Tagging is a way for the custom client application to determine which local client contacts require different application behavior when the event is handled. For example, the local client user has tagged Contact A. The event handler for the OnContactStatusChange event should check the tagged status of the contact passed as an event argument to the handler. When a tagged contact is passed, the event handler shows a dialog that alerts the local client. When Contact B signs in, the handler does not show the dialog. When Contact A signs in, the dialog is shown because Contact A is a tagged contact.

Example

The event handler displays a MessageBox if the pMContact object is a tagged contact. The IMessengerContactAdvanced::PresenceProperties property is queries to gain access to the IsTagged property and the availability value. If the contact is a tagged contact and the availability value is 3000 or 18000, a MessageBox is displayed with the availability of the contact. The following C# code demonstrates this with an event handler for contact status change.

	Copy Code
void communicator_OnContactStatusChange(object pMContact, MISTATUS mStatus) { IMessengerContactAdvanced imContact = (IMessengerContactAdvanced)pMContact; object[] contactPresenceProperties = (object[])imContact.PresenceProperties; int availabilityStr = (int)contactPresenceProperties[(int)PRESENCE_PROPERTY.PRESENCE_PROP_AVAILABILITY]; try { if (imContact.IsTagged == true) { switch (availabilityStr) { case 3000: MessageBox.Show(imContact.FriendlyName + " Has signed in"); break; case 18000: MessageBox.Show(imContact.FriendlyName + " Has signed out"); break; } } myContactList.updateContactStatus(imContact, mStatus); } catch (Exception e) { Console.WriteLine("Error updating contact status:" + e.Message.ToString()); } finally { Console.WriteLine("EVENT: " + sb.ToString()); } }

Copy Code

void communicator_OnContactStatusChange(object pMContact, MISTATUS mStatus)
{
  IMessengerContactAdvanced imContact = (IMessengerContactAdvanced)pMContact;
  object[] contactPresenceProperties = (object[])imContact.PresenceProperties;
  int availabilityStr = (int)contactPresenceProperties[(int)PRESENCE_PROPERTY.PRESENCE_PROP_AVAILABILITY];
  try
  {
	if (imContact.IsTagged == true) 
	{
	 switch (availabilityStr)
	 { 
		 case 3000:
			MessageBox.Show(imContact.FriendlyName + 
							" Has signed in");
			break;
		 case 18000:
			MessageBox.Show(imContact.FriendlyName + 
							" Has signed out");
		 break;
	 }
}
	myContactList.updateContactStatus(imContact, mStatus);
  }
  catch (Exception e)
  {
	 Console.WriteLine("Error updating contact status:" 
						+ e.Message.ToString());
  }
  finally
  {
	Console.WriteLine("EVENT: " + sb.ToString());
  }
}

When a contact is tagged, the IsTagged property is set to true and the caller is notified of the status change when the contact goes offline or online.

The following C++ code snippet shows how to toggle the tag status of a contact.

	Copy Code
IMessenger* m_pIMessenger = … // Assume this is already cocreated. // Get a contact whose sign-in name is "jaya@contoso.com". IDispatch* pIMessengerContact; hr = m_pIMessenger->GetContact(L"jaya@contoso.com", NULL, (IDispatch*)&pIMessengerContact); if (FAILED(hr)) return hr; // QI IMessengerContactAdvanced interface IMessengerContactAdvanced pContactAdvanced = NULL; hr = pIMessengerContact->QueryInterface( IID_IMessengerContactAdvanced, (void**)&pContactAdvanced); if (hr != S_OK) return hr; // Toggle (get and set) IsTagged property value VARIANT_BOOL tagged; hr = pContactAdvanced->get_IsTagged(&tagged); if (tagged == false) { tagged = true; } else { tagged = false; } hr = pContactAdvanced->putIsTagged(tagged); if (hr != S_OK) return hr;