Module Skype :: Class ContactGroup

Class ContactGroup

source code

     object --+        
              |        
skypekit.Cached --+    
                  |    
    skypekit.Object --+
                      |
                     ContactGroup

Collects and manages Contacts related by type, status, or some other arbitrary criteria. SkypeKit recognizes two distinct ContactGroup flavors - "hardwired" and "custom". SkypeKit both defines the criteria for and dynamically manages all "hardwired" ContactGroups. Individual users explicitly create and manage all "custom" ContactGroups.

"Hardwired" groups are primarily organizational tools, for example, they enable you to display a list of all Contacts awaiting authorization by you. "Custom" groups are also organizational tools, for example, they enable you to display a list of all Contacts in a particular geographical area or belonging to a particular professional association, social clubs, and so forth. Primarily, though, "custom" groups are functional tools that enable you to establish conference calls, group chats, and so forth.

"Hardwired" ContactGroups are defined for and available to all users. SkypeKit determines membership in a particular "hardwired" group dynamically whenever a user invokes Skype.GetHardwiredContactGroup for that group. Subsequent changes to a Contact's status might result in its being added to (for example, the Contact is now authorized) or removed from (for example, the Contact is now removed or blocked) one or more "hardwired" groups.

SkypeKit fires OnChange events for all affected ContractGroup instances. Essentially all ContactGroup methods related to explicitly adding and removing members and conversations from the group return false, and CanAdd and CanRemove additionally return a false result.

"Custom" ContactGroups can be defined by a particular Skype user through the UI. Your UI should implement Creation, deletion and filtering contact list by custom contact groups, as well as adding and removing contacts in those groups.

A Contact can belong to multiple non-mutually exclusive "hardwired" groups at the same time, for example, an authorized contact is typically in your "buddy" group, but a Contact cannot belong to CONTACTS_AUTHORIZED_BY_ME if they are awaiting authorization. Similarly, a Contact can belong to multiple "custom" groups and mutual exclusivity is typically not an issue.

Instance Methods
 
_sk_init_(self, object_id, transport)
actual constructor
source code
 
__str__(self)
str(x)
source code
 
OnPropertyChange(self, property_name)
notifies from a property change
source code
 
GiveDisplayName(self, name)
Setter for ContactGroup class GIVEN_DISPLAYNAME property.
source code
 
Delete(self)
Removes the contact group.
source code
 
GetConversations(self)
Returns list of conversations in the ContactGroup.
source code
 
CanAddConversation(self, conversation=0)
Checks if the current user can add given conversation to the ContactGroup.
source code
 
AddConversation(self, conversation)
Adds given conversation to the ContactGroup.
source code
 
CanRemoveConversation(self)
Checks if the current user can remove given conversation from the ContactGroup.
source code
 
RemoveConversation(self, conversation)
Removes given conversation from the ContactGroup.
source code
 
OnChangeConversation(self, conversation)
conversation added or removed from this group
source code
 
GetContacts(self)
Retrieves contact list.
source code
 
CanAddContact(self, contact=0)
Checks if the current user can add given contact to the ContactGroup.
source code
 
AddContact(self, contact)
Adds contact to a contact group.
source code
 
CanRemoveContact(self)
Checks if the current user can remove given contact from the ContactGroup.
source code
 
RemoveContact(self, contact)
Removes contact from the ContactGroup.
source code
 
OnChange(self, contact)
A contact has been added or removed to this ContactGroup.
source code

Inherited from skypekit.Object: multiget

Inherited from skypekit.Cached: __copy__

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __subclasshook__

Static Methods
 
propid(propname)
convert a property name to the enum of the property
source code

Inherited from skypekit.Cached: __new__, sk_exists

Class Variables
  event_handlers = {1: '_sk_on_change_conversation', 2: '_sk_on_...
  propid2label = {151: 'given_displayname', 152: 'nrofcontacts',...
  module_id = 10
  TYPE = {1: 'ALL_KNOWN_CONTACTS', 2: 'ALL_BUDDIES', 3: 'SKYPE_B...
The list of all possible ContactGroup types.
  P_TYPE = 155
  P_CUSTOM_GROUP_ID = 154
  P_GIVEN_DISPLAYNAME = 151
  P_NROFCONTACTS = 152
  P_NROFCONTACTS_ONLINE = 153

Inherited from skypekit.Object: rwlock

Instance Variables

Inherited from skypekit.Object: properties

Properties
  type
ContactGroup::TYPE
  custom_group_id
unique 32-bit ID for custom groups
  given_displayname
change via ContactGroup::GiveDisplayname()
  nrofcontacts
Number of contacts in the group.
  nrofcontacts_online
number of contacts online in the group

Inherited from object: __class__

Method Details

_sk_init_(self, object_id, transport)

source code 

actual constructor

Overrides: skypekit.Object._sk_init_

__str__(self)
(Informal representation operator)

source code 

str(x)

Overrides: object.__str__
(inherited documentation)

GiveDisplayName(self, name)

source code 

Setter for ContactGroup class GIVEN_DISPLAYNAME property.

Arguments:

  • name

Delete(self)

source code 

Removes the contact group. This is synced across instances logged in with the same account - which can take several minutes for the sync to happen.

Return values:

  • result

GetConversations(self)

source code 

Returns list of conversations in the ContactGroup.

Return values:

  • conversations

CanAddConversation(self, conversation=0)

source code 

Checks if the current user can add given conversation to the ContactGroup. Returns false for most of the hardwired contact groups for example.

Arguments:

  • conversation - Conversation to be checked.

Return values:

  • result - Returns true if Conversation can be added to this ContactGroup.

AddConversation(self, conversation)

source code 

Adds given conversation to the ContactGroup.

Arguments:

  • conversation

CanRemoveConversation(self)

source code 

Checks if the current user can remove given conversation from the ContactGroup. Again, returns false for most hardwired contact groups.

Return values:

  • result - true if RemoveConversation(contact) works on this group

RemoveConversation(self, conversation)

source code 

Removes given conversation from the ContactGroup.

Arguments:

  • conversation

OnChangeConversation(self, conversation)

source code 

conversation added or removed from this group

Return values:

  • conversation

GetContacts(self)

source code 

Retrieves contact list.

Return values:

  • contacts

CanAddContact(self, contact=0)

source code 

Checks if the current user can add given contact to the ContactGroup.

Arguments:

  • contact - Contact to be checked.

Return values:

  • result - returns true if AddContact(contact) works on this group.

AddContact(self, contact)

source code 

Adds contact to a contact group. This only works for non-hardwired contact groups.

Arguments:

  • contact

CanRemoveContact(self)

source code 

Checks if the current user can remove given contact from the ContactGroup.

Return values:

  • result - true if RemoveContact(contact) works on this group

RemoveContact(self, contact)

source code 

Removes contact from the ContactGroup.

Arguments:

  • contact

OnChange(self, contact)

source code 

A contact has been added or removed to this ContactGroup. NB! On rare occasions, the ContectRef argument to this callback can be NULL. You should always check whether the reference is valid, before accessing methods or properties.

Return values:

  • contact

Class Variable Details

event_handlers

Value:
{1: '_sk_on_change_conversation', 2: '_sk_on_change'}

propid2label

Value:
{151: 'given_displayname',
 152: 'nrofcontacts',
 153: 'nrofcontacts_online',
 154: 'custom_group_id',
 155: 'type'}

TYPE

The list of all possible ContactGroup types. A value of this type can be passed to Skype class GetHardwiredContactGroup to retrieve the relevant ContactGroup object.

  • ALL_KNOWN_CONTACTS - The superset of all "hardwired" contact groups.
  • ALL_BUDDIES - The set of all authorized contacts, that is, contacts that were last the target of Contact::SetBuddyStatus(false) plus all SkypeOut contacts.
  • SKYPE_BUDDIES - The set of all authorized Skype contacts (Contact:_SKYPENAME is non-null).

Note that this excludes Skype contacts that have either never been the target of Contact::SetBuddyStatus(true) or were last the target of Contactact::SetBuddyStatus(false).

  • SKYPEOUT_BUDDIES - The set of all SkypeOut contacts (Contact:_PSTNNUMBER is non-null). PSTN contacts can be added to the contact list by retrieving a new contact object with Skype::GetContact, passing in the phone number as string, and then either using Contact::SetBuddyStatus(true) or adding the contact to the SKYPEOUT_BUDDIES group with ContactGroup::AddContact.
  • ONLINE_BUDDIES - The subset of ALL_BUDDIES that are currently online, including those currently marked as DO_NOT_DISTURBED and AWAY.
  • UNKNOWN_OR_PENDINGAUTH_BUDDIES - The set of all contacts whose Contact:_TYPE reflects UNRECOGNIZED OR have not authorized the local user yet.
  • RECENTLY_CONTACTED_CONTACTS - This filter returns top 10 most recently contacted contacts, based on Contact::P_LASTUSED_TIMESTAMP property values. This is not configurable. Note that the P_LASTUSED_TIMESTAMP property does not propagate between different Skype instances - thus this filter only works in context of the local database. Recent contacts that were in touch with the user on some other Skype installation will not show up in this filter.
  • CONTACTS_WAITING_MY_AUTHORIZATION - Contacts to whose authorization request the user has not responded yet. The UI should enable the user to accept, decline the authorization request and in case of decline, optionally block further incoming communication from the contact. See: Contact::SetBuddyStatus, Contact::SetBlocked and Contact::IgnoreAuthRequest for more information.
  • CONTACTS_AUTHORIZED_BY_ME - All contacts authorized by the user.
  • CONTACTS_BLOCKED_BY_ME - Group of contacts the user has blocked from further incoming communications. If the UI enables contact blocking, it should also provide interface for the user to unblock the blocked contacts. Note that a contact can simultaneously be in both CONTACTS_BLOCKED_BY_ME and CONTACTS_AUTHORIZED_BY_ME groups.
  • UNGROUPED_BUDDIES - The set of all "buddies" that are not also a member of a custom group.
  • CUSTOM_GROUP - A custom group defined by user.
  • PROPOSED_SHARED_GROUP - The shared contact group functionality is no longer supported. This contact group type can be ignored.
  • SHARED_GROUP - The shared contact group functionality is no longer supported. This contact group type can be ignored.
  • EXTERNAL_CONTACTS - The set of all contacts that were originally imported from an external address book.
Value:
{1: 'ALL_KNOWN_CONTACTS',
 2: 'ALL_BUDDIES',
 3: 'SKYPE_BUDDIES',
 4: 'SKYPEOUT_BUDDIES',
 5: 'ONLINE_BUDDIES',
 6: 'UNKNOWN_OR_PENDINGAUTH_BUDDIES',
 7: 'RECENTLY_CONTACTED_CONTACTS',
 8: 'CONTACTS_WAITING_MY_AUTHORIZATION',
...

Property Details

type

ContactGroup::TYPE

Get Method:
_sk_get_type(self) - ContactGroup::TYPE

custom_group_id

unique 32-bit ID for custom groups

Get Method:
_sk_get_custom_group_id(self) - unique 32-bit ID for custom groups

given_displayname

change via ContactGroup::GiveDisplayname()

Get Method:
_sk_get_given_displayname(self) - change via ContactGroup::GiveDisplayname()

nrofcontacts

Number of contacts in the group. NB! The value of this property does not get updated until 5 seconds after account login. During these initial 5 seconds, the value of this property remains 0. The reason for this 5 second delay is to reduce the flurry of property update traffic that occurs during the CBL synchronization phase, following successful login. Note that if you absolutely need to have this value immediately after login, you can still get it by retrieving the contact list with ContactGroup::GetContacts method and examining its size.

Get Method:
_sk_get_nrofcontacts(self) - Number of contacts in the group.

nrofcontacts_online

number of contacts online in the group

Get Method:
_sk_get_nrofcontacts_online(self) - number of contacts online in the group