Module Skype :: Class ContactSearch

Class ContactSearch

source code

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

This class encapsulates functionality for looking up contacts on the Skype network. Contacts can be searched by portion of their name, e-mail address, language preferences, etc.

Contact search is asynchronous. ContactSearch::Submit is a non-blocking function that initiates the search. Upon finding a matching contact, ContactSearch::OnNewResult event gets fired, that gives you the reference to the discovered contact. You can get up to 100 matching contacts per search. Note that you will need to keep a live reference of the ContactSearch object while the search is doing its work.

So, to perform a contact search:

When the search has done its job, the ContactSearch::P_CONTACT_SEARCH_STATUS property will go to one of the terminal values.

The terminal values are:

There are three methods to create the ContactSearch objects.

A) Skype::CreateIdentitySearch

This method takes a string argument and looks for exact matches against Contact::P_SKYPENAME property. So for example, identity search for "echo" will return 0 results and search for "echo123" will return exactly one.

Identity in this case means skypename - contact search does not work with PSTN type contacts. However, it does work for SKYPE type contacts that have supplied P_PHONE_HOME, P_PHONE_OFFICE or P_PHONE_MOBILE values in their account data. To search for those, you will need to use complex search (see below).

Note that you should always check for boolean return value of the CreateIdentitySearch method. If the user submits a string that is not a valid skypename, the method will return false and the ContactSearchRef argument will return as NULL.

B) Skype::CreateBasicContactSearch

This method takes a string argument and looks for non-exact matches against both P_SKYPENAME and P_FULLNAME properties of the contact. If you intend to implement a simple, one-input search feature - this is the best method for you. The non-exact matching operates similarly to the SQL LIKE condition.

C) Skype::CreateContactSearch

This method enables you to implement advanced contact search, matching against multiple seach criteria. It takes no input arguments and expects search criteria to be added to the already constructed search object.

Criteria can be added with ContactSearch::AddStrTerm and ContactSearch::AddIntTerm methods.

These methods take Contact class porperty ID, condition, and the match pattern as inputs.

Only the following Contact properties can be used for search:

String searches are case insensitive, i.e. search for echo123 also matches ECHO123

When adding multiple criteria, default behaviour is that the criterions are additive. I.e. a term skypename == "joe" followed by term country == "us" will result in intersection between all joes and everybody in US.

You can explicitly add an "OR" instead of "AND" between conditions, using the AddOr method.

By default, AND criteria are grouped together, before OR's, so that:

AddTerm(condition1) AddTerm(condition2) AddOr() AddTerm(condition3) AddTerm(condition4)

will result in the following logical statement: (condition1 AND condition2) OR (condition3 AND condition4)

However, you can add "global" critera, by using the add_to_subs argument of the AddXX methods.

AddTerm(condition1) AddTerm(condition2) AddOr() AddTerm(condition3) AddTerm(condition4, add_to_subs=true)

which would result in: (condition1 AND condition2 AND condition4) OR (condition3 AND condition4)

Every one of the contact properties can only be used once, per search. For example, you cannot create a search for two different P_FULLNAME patterns. The &valid argument will still return tue if you do this, but the last criteria for any given property will override all previous ones. So, a search like this:

cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "John Smith", isValid); cs->AddOr(); cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "Ivan Sidorov", isValid);

will only return matches for "Ivan Sidorov" and none for "John Smith".

Some of the contact properties are automatically combined for purposes of search.

A search for P_SKYPENAME also returns matches from the P_FULLNAME property and vice versa.

So that this: cs->AddStrTerm(Contact::P_SKYPENAME, ContactSearch::EQ, "john.smith", isValid);

..and this: cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "John Smith", isValid);

..and this: cs->AddStrTerm(Contact::P_SKYPENAME, ContactSearch::EQ, "john.smith", isValid); cs->AddOr(); cs->AddStrTerm(Contact::P_FULLNAME, ContactSearch::EQ, "John Smith", isValid);

..all search from both the P_FULLNAME and P_SKYPENAME fields.

Before using ContactGroup::Submit to start the search, you should always check whether the search criteria ended up being valid. This you can do with ContactSearch::IsValid method.

As you probably noticed, each of the AddXX methods also return a validity check boolean. However, it is a better practice to do the overall check as well, even if all the individual search criteria ended up looking Ok.

For example, lets take a search for contact's e-mail. This can be done with two different methods. Firstly we can use the ContactSearch::AddEmailTerm method. This method will actually validate whether the input is a valid e-mail address:

cs->AddEmailTerm ("test@test@test", isValid); will return the isValid argument as false.

However, you can also add the e-mail search criterion as a simple string, like this:

cs->AddStrTerm(Contact::P_EMAILS, ContactSearch::EQ, "test@test@test@", isValid); in which case the isValid will return true.

However, if you then check entire search object with:

cs->IsValid(isValid);

the isValid will correctly return false.

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
 
AddMinAgeTerm(self, min_age_in_years, add_to_subs=False)
construct CONTACT_BIRTHDAY term based on current time
source code
 
AddMaxAgeTerm(self, max_age_in_years, add_to_subs=False)
construct CONTACT_BIRTHDAY term based on current time
source code
 
AddEmailTerm(self, email, add_to_subs=False)
Adds a search term against Contact::P_EMAILS property and pre-validates the value given in the email argument.
source code
 
AddLanguageTerm(self, language, add_to_subs=False)
No description available.
source code
 
AddStrTerm(self, prop, cond, value, add_to_subs=False)
Adds a string search term to a custom contact search object.
source code
 
AddIntTerm(self, prop, cond, value, add_to_subs=False)
Adds a search term to a custom contact search object.
source code
 
AddOr(self)
used to group terms (AddTerm(1), AddTerm(2), Or(), AddTerm(3), AddTerm(4), etc)
source code
 
IsValid(self)
checks that terms list is non-empty and does not contain unsupported keys
source code
 
Submit(self)
launch search
source code
 
Extend(self)
extend if search is EXTENDABLE
source code
 
Release(self)
releases results that are not referenced from elsewhere
source code
 
GetResults(self, from_=0, count=4294967295)
result list is dynamically updated
source code
 
OnNewResult(self, contact, rank_value)
This callback is fired when a new matching contact has been found during the search.
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_new_result'}
  propid2label = {200: 'contact_search_status'}
  module_id = 1
  STATUS = {1: 'CONSTRUCTION', 2: 'PENDING', 3: 'EXTENDABLE', 4:...
Possible values for the ContactSearch.P_STATUS property.
  CONDITION = {0: 'EQ', 1: 'GT', 2: 'GE', 3: 'LT', 4: 'LE', 5: '...
List of available matching conditions that can be used in AddTerm methods.
  P_CONTACT_SEARCH_STATUS = 200

Inherited from skypekit.Object: rwlock

Instance Variables

Inherited from skypekit.Object: properties

Properties
  contact_search_status

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)

AddMinAgeTerm(self, min_age_in_years, add_to_subs=False)

source code 

construct CONTACT_BIRTHDAY term based on current time

Arguments:

  • min_age_in_years
  • add_to_subs

Return values:

  • valid

AddMaxAgeTerm(self, max_age_in_years, add_to_subs=False)

source code 

construct CONTACT_BIRTHDAY term based on current time

Arguments:

  • max_age_in_years
  • add_to_subs

Return values:

  • valid

AddEmailTerm(self, email, add_to_subs=False)

source code 

Adds a search term against Contact::P_EMAILS property and pre-validates the value given in the email argument.

Arguments:

  • email - e-mail addres to search for.
  • add_to_subs - This argument enables you to group conditions. See ContactSearch class details for more information.

Return values:

  • valid - Returns false if the value in email property did not look like a valid email address.

AddLanguageTerm(self, language, add_to_subs=False)

source code 

No description available.

Arguments:

  • language
  • add_to_subs

Return values:

  • valid

AddStrTerm(self, prop, cond, value, add_to_subs=False)

source code 

Adds a string search term to a custom contact search object.

Arguments:

  • prop - Following Contact class string propkeys can be used for Contact search:
    • Contact::P_SKYPENAME
    • Contact::P_FULLNAME
    • Contact::P_LANGUAGES
    • Contact::P_COUNTRY
    • Contact::P_PROVINCE
    • Contact::P_CITY
    • Contact::P_PHONE_HOME
    • Contact::P_PHONE_OFFICE
    • Contact::P_PHONE_MOBILE
    • Contact::P_EMAILS
    • Contact::P_HOMEPAGE
    • Contact::P_ABOUT

Note that while Contact::P_EMAILS is technically a string and can be used in this method, it is recommended that you use ContactSearch.AddEmailTerm method instead.

  • cond - Search condition (ContactSearch::CONDITION)
  • value - Value to match against.
  • add_to_subs - This argument enables you to group conditions. See ContactSearch class details for more information.

Return values:

  • valid - Returns true if the ContactSearch term-set remains valid after adding this term.

AddIntTerm(self, prop, cond, value, add_to_subs=False)

source code 

Adds a search term to a custom contact search object. For now, there are only two searchable Contact properties that are integers, so this can oly be used for Contact::P_BIRTHDAY and Contact::P_GENDER.

Arguments:

  • prop - Propkey to search for. Either Contact::P_BIRTHDAY or Contact::P_GENDER
  • cond - Search condition (ContactSearch::CONDITION)
  • value - Value to match against.
  • add_to_subs - This argument enables you to group conditions. See ContactSearch class details for more information.

Return values:

  • valid - Returns true if the ContactSearch term-set remains valid after adding this term.

IsValid(self)

source code 

checks that terms list is non-empty and does not contain unsupported keys

Return values:

  • result

GetResults(self, from_=0, count=4294967295)

source code 

result list is dynamically updated

Arguments:

  • from_
  • count

Return values:

  • contacts

OnNewResult(self, contact, rank_value)

source code 

This callback is fired when a new matching contact has been found during the search.

Return values:

  • contact
  • rank_value

Class Variable Details

STATUS

Possible values for the ContactSearch.P_STATUS property.

  • CONSTRUCTION - Transient state, obtained after submission and actually initiating the search on the network.
  • PENDING - Waiting for results to show up. This is a transient state.
  • EXTENDABLE - Enough matches are found. No more OnNewResult events will fire. The feature of extending long search results is about to be deprecated. It is still possible for search objects to occasionally reach that state, so it should be handled in the UI (as FINISHED), but the extending feature itself should not be implemented in your UI.
  • FINISHED - The search is finished. No more matches are expected. This is a terminal state.
  • FAILED - ContactSearch failed. Better check if the search terms made any sense, with ContactSearch::IsValid. This is a terminal state.
Value:
{1: 'CONSTRUCTION',
 2: 'PENDING',
 3: 'EXTENDABLE',
 4: 'FINISHED',
 5: 'FAILED',
 'CONSTRUCTION': 1,
 'EXTENDABLE': 3,
 'FAILED': 5,
...

CONDITION

List of available matching conditions that can be used in AddTerm methods.

  • EQ - Equals
  • GT - Is greater than
  • GE - Is greater or equal.
  • LT - Is less than
  • LE - Less or equal
  • PREFIX_EQ - Start of a word macthes exactly (string properties only).
  • PREFIX_GE - Start of a word is greater or equal (string properties only).
  • PREFIX_LE - Start of a word is less or equal (string properties only).
  • CONTAINS_WORDS - Contains the word (string properties only).
  • CONTAINS_WORD_PREFIXES - One of the words starts with searched value (string properties only).
Value:
{0: 'EQ',
 1: 'GT',
 2: 'GE',
 3: 'LT',
 4: 'LE',
 5: 'PREFIX_EQ',
 6: 'PREFIX_GE',
 7: 'PREFIX_LE',
...

Property Details

contact_search_status

Get Method:
_sk_get_contact_search_status(self)