IMessenger2::CreateGroup Method

[CreateGroup is no longer available in 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]
BSTR

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

vService [in]
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]
IDispatch

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

Return Value

HRESULT

Returns one of the following values:

Return codeDescription
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

Header

Msgrua.h

IDL

Msgrua.idl

DLL

Msgsc.dll

See Also

IMessenger2
IMessengerGroups

 

 

Send comments about this topic to Microsoft

Build date: 6/30/2010

Show: