Public Types | Public Member Functions

ContactSearch Class Reference

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. More...

#include <skype-embedded_2.h>

List of all members.

Public Types

enum  { MODULE_ID = 1 }
enum  PROPERTY { P_CONTACT_SEARCH_STATUS = 200 }
enum  STATUS {
  CONSTRUCTION = 1,
  PENDING,
  EXTENDABLE,
  FINISHED,
  FAILED
}
enum  CONDITION {
  EQ = 0,
  GT,
  GE,
  LT,
  LE,
  PREFIX_EQ,
  PREFIX_GE,
  PREFIX_LE,
  CONTAINS_WORDS,
  CONTAINS_WORD_PREFIXES
}
typedef ContactSearchRef Ref
typedef ContactSearchRefs Refs

Public Member Functions

virtual ~ContactSearch ()
ContactSearchRef ref ()
bool AddMinAgeTerm (const uint &min_age_in_years, bool &valid, const bool add_to_subs=false)
bool AddMaxAgeTerm (const uint &max_age_in_years, bool &valid, const bool add_to_subs=false)
bool AddEmailTerm (const Sid::String &email, bool &valid, const bool add_to_subs=false)
bool AddLanguageTerm (const Sid::String &language, bool &valid, const bool add_to_subs=false)
bool AddStrTerm (const int &prop, const CONDITION &cond, const Sid::String &value, bool &valid, const bool add_to_subs=false)
bool AddIntTerm (const int &prop, const CONDITION &cond, const uint &value, bool &valid, const bool add_to_subs=false)
bool AddOr ()
bool IsValid (bool &result)
bool Submit ()
bool Extend ()
bool Release ()
bool GetResults (ContactRefs &contacts, const uint from=0, const uint count=MAX_UINT)
virtual void OnNewResult (const ContactRef &contact, const uint &rankValue)
bool GetPropContactSearchStatus (STATUS &contact_search_status)

Detailed Description

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:

Definition at line 652 of file skype-embedded_2.h.


Member Typedef Documentation

Definition at line 661 of file skype-embedded_2.h.

Definition at line 662 of file skype-embedded_2.h.


Member Enumeration Documentation

anonymous enum
Enumerator:
MODULE_ID 

Definition at line 663 of file skype-embedded_2.h.

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

Enumerator:
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).

Definition at line 718 of file skype-embedded_2.h.

Properties of the ContactSearch class

Enumerator:
P_CONTACT_SEARCH_STATUS 

type: STATUS

Definition at line 677 of file skype-embedded_2.h.

Possible values for the ContactSearch.P_STATUS property.

Enumerator:
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.

Definition at line 682 of file skype-embedded_2.h.


Constructor & Destructor Documentation

ContactSearch::~ContactSearch (  )  [virtual]

Definition at line 279 of file skype-embedded_2.cpp.


Member Function Documentation

bool ContactSearch::AddEmailTerm ( const Sid::String &  email,
bool &  valid,
const bool  add_to_subs = false 
)

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

Parameters:
email e-mail addres to search for.
valid Returns false if the value in email property did not look like a valid email address.
add_to_subs This argument enables you to group conditions. See ContactSearch class details for more information.
bool ContactSearch::AddIntTerm ( const int &  prop,
const CONDITION cond,
const uint &  value,
bool &  valid,
const bool  add_to_subs = false 
)

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.

Parameters:
prop Propkey to search for. Either Contact::P_BIRTHDAY or Contact::P_GENDER
cond Search condition (ContactSearch::CONDITION)
value Value to match against.
valid Returns true if the ContactSearch term-set remains valid after adding this term.
add_to_subs This argument enables you to group conditions. See ContactSearch class details for more information.
bool ContactSearch::AddLanguageTerm ( const Sid::String &  language,
bool &  valid,
const bool  add_to_subs = false 
)
bool ContactSearch::AddMaxAgeTerm ( const uint &  max_age_in_years,
bool &  valid,
const bool  add_to_subs = false 
)

construct CONTACT_BIRTHDAY term based on current time

bool ContactSearch::AddMinAgeTerm ( const uint &  min_age_in_years,
bool &  valid,
const bool  add_to_subs = false 
)

construct CONTACT_BIRTHDAY term based on current time

bool ContactSearch::AddOr (  ) 

used to group terms (AddTerm(1), AddTerm(2), Or(), AddTerm(3), AddTerm(4), etc)

bool ContactSearch::AddStrTerm ( const int &  prop,
const CONDITION cond,
const Sid::String &  value,
bool &  valid,
const bool  add_to_subs = false 
)

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

Parameters:
prop Following Contact class string propkeys can be used for Contact search:

cond Search condition (ContactSearch::CONDITION)
value Value to match against.
valid Returns true if the ContactSearch term-set remains valid after adding this term.
add_to_subs This argument enables you to group conditions. See ContactSearch class details for more information.
bool ContactSearch::Extend (  ) 

extend if search is EXTENDABLE

bool ContactSearch::GetPropContactSearchStatus ( STATUS contact_search_status  ) 
bool ContactSearch::GetResults ( ContactRefs contacts,
const uint  from = 0,
const uint  count = MAX_UINT 
)

result list is dynamically updated

bool ContactSearch::IsValid ( bool &  result  ) 

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

virtual void ContactSearch::OnNewResult ( const ContactRef contact,
const uint &  rankValue 
) [virtual]

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

ContactSearchRef ContactSearch::ref (  )  [inline]

Definition at line 664 of file skype-embedded_2.h.

bool ContactSearch::Release (  ) 

releases results that are not referenced from elsewhere

bool ContactSearch::Submit (  ) 

launch search


The documentation for this class was generated from the following files:
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

(c) Skype Technologies S.A. Confidential/Proprietary

Last updated: Fri Mar 16 2012