IMessenger2::CreateGroup method
[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 |
|---|---|
|
Success. |
|
Client has not enabled groups, or the current service does not support groups. |
|
The new name of the group exceeds the maximum number of characters. |
|
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. |
|
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. |
|
ppGroup is a NULL pointer. |
|
Client was not signed in to the primary service at the time this method was called. |
|
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 |
|
| IDL |
|
| DLL |
|