IMessenger2::CreateGroup method

Article
05/31/2018

[CreateGroup is no longer available for use as of Windows Vista. See Windows Messenger for more information.]

Creates a new group to the MessengerGroups collection object.

Syntax

HRESULT CreateGroup(
  [in]          BSTR      bstrName,
  [in]          VARIANT   vService,
  [out, retval] IDispatch **ppGroup
);

Parameters

bstrName [in]

Type: BSTR

A BSTR that specifies the name of the group to be created.

vService [in]

Type: VARIANT

A VARIANT that can take as its value either a VT_BSTR string or a VT_DISPATCH pointer to an existing MessengerService object.

ppGroup [out, retval]

Type: IDispatch**

Return value. Pointer to a pointer to an IDispatch interface.

Return value

Type: HRESULT

Returns one of the following values.

Return code	Description
S_OK	Success.
MSGR_E_GROUPS_NOT_ENABLED	Client has not enabled groups, or the current service does not support groups.
MSGR_E_GROUP_NAME_TOO_LONG	The new name of the group exceeds the maximum number of characters.
MSGR_E_BAD_GROUP_NAME	The new name of the group is invalid. Characters such as carriage returns, linefeeds, tabs, and nonprintable characters are not allowed. Spaces before and after the group name will be trimmed automatically.
E_INVALIDARG	bstrName or vService (if VT_BSTR) is a NULL string or contains nothing but spaces. - or - vService (if VT_BSTR) exceeds the maximum number of characters. - or - bstrName or vService (if VT_BSTR) contains a carriage return or linefeed.
RPC_X_NULL_REF_POINTER	ppGroup is a NULL pointer.
MSGR_E_NOT_LOGGED_ON	Client was not signed in to the primary service at the time this method was called.
E_POINTER	bstrName is NULL.

Remarks

Some services, such as Microsoft Exchange Instant Messaging Service (IM), do not support groups. Using this method on these services will return the error, MSGR_E_GROUPS_NOT_ENABLED.

The CreateGroup method will look for a group name (bstrName) in the local user list of groups for the service (vService). If not found, the method will attempt to create a new group. To check the success of the creation of a new group, use OnGroupAdded.

The service parameter (vService) can be a string that contains the service ID, not the name, of the service. The service ID can be obtained from MyServiceId for the primary service or from PrimaryService or ServiceID.

Note

This method is not available for scripting languages.

Requirements


End of client support	Windows XP
End of server support	Windows Server 2003
Header	Msgrua.h
IDL	Msgrua.idl
DLL	Msgsc.dll

Share via