Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Buddy groups are provided with the RTC Client API Version 1.2. A buddy group is a logical grouping of buddies (and watchers) such that actions can be performed upon the whole group.
The IRTCBuddyGroup interface is created on the client presence object when the AddGroup method of the IRTCClientPresence2 interface is called. Each buddy group created has a name string and an XML SIP profile associated with it. The profile has roaming capabilities under SIP Server, just like any other contact type.
Individual buddies are added to and removed from the group by calling the IRTCBuddyGroup::AddBuddy and IRTCBuddyGroup::RemoveBuddy methods, respectively. The default buddy group for RTC 1.2 buddies is the "no group." Programmatically, groups should be defined first, and buddies added to them as they are created. Adding a buddy or a group using IRTCClientPresence2::AddBuddyEx or IRTCClientPresence2::AddGroup is an asynchronous operation. The application must wait for the RTCBET_BUDDY_ADD and RTCGET_GROUP_ADD events to ensure that both buddy and group objects have been created successfully on the server before adding a buddy to a group using the IRTCBuddyGroup::AddBuddy method.
Private data available only to the buddy group can be set and retrieved using IRTCBuddyGroup::put_Data and IRTCBuddyGroup::get_Data, respectively. This data must be in the form of a binary string (BSTR), and can be used to contain group-specific images, text information, or data structures. This data is stored on the server and is opaque to the RTC infrastructure. The application can set any valid XML content for this property. Using this feature, groups can have individual programmatic features; for example, one particular group can have a sound associated with it that plays whenever one of the member buddies becomes active.
An enumerated list of all groups defined for the client presence object can be obtained by calling IRTCClientPresence2::EnumerateGroups. A collection object containing the groups can also be obtained by calling the IRTCClientPresence2::get_Groups property. An individual group can be obtained by calling IRTCClientPresence2::get_Group with the name of the buddy group. The maximum number of buddy groups allowed on any given client presence object is 64.
Buddy group events, such as the addition of buddies to or removal of buddies from a group, can be received by registering for the RTCEF_GROUP event with IRTCClient::put_EventFilter. Buddy group events will have the IRTCBuddyGroupEvent interface exposed, and calls to IRTCBuddyGroupEvent::get_Buddy and IRTCBuddyGroupEvent::get_Group will return pointers to the buddy and group interfaces that fired the event.
Buddy groups can be removed by calling IRTCClientPresence2::RemoveGroup and passing a pointer to the group's IRTCBuddyGroup interface.