Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.skype.api
Class ContactSearch

    java.lang.Object
      com.skype.ipc.SidObject
          com.skype.api.ContactSearch

All Implemented Interfaces:
  SidGetResponding

    public final class ContactSearch

extends SidObject

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: - create a contact search object - specify search terms and conditions - submit search - in ContactSearch.OnNewResult callback, update your UI - in ContactSearch.OnChange, check for terminal values of P_CONTACT_SEARCH_STATUS and update the UI accordingly. 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: - FINISHED - the search has stopped. Note that this does not mean any matches were actually found. - FAILED - the search has failed. - EXTENDABLE - this state should be considered the same as FINISHED. 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. 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: - P_SKYPENAME - P_FULLNAME - P_BIRTHDAY (uint) - P_GENDER (uint: 1-male, 2-female) - P_LANGUAGES - P_COUNTRY - P_PROVINCE - P_CITY - P_PHONE_HOME - P_PHONE_OFFICE - P_PHONE_MOBILE - P_EMAILS - P_HOMEPAGE - P_ABOUT 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.

Nested Class Summary
`static class` | `ContactSearch.Condition` List of available matching conditions that can be used in AddTerm methods.
`static class` | `ContactSearch.Property` Properties of the ContactSearch class
`static class` | `ContactSearch.Status` Possible values for the ContactSearch.P_STATUS property.

Field Summary
`ContactSearch.Status` | `mContactSearchStatus`

Fields inherited from class com.skype.ipc.SidObject
`mSidCached, mSidOid, mSidRoot, mSidTimestamp`

Constructor Summary
`ContactSearch(int oid, SidRoot root)`

Method Summary
`boolean` | `addEmailTerm(java.lang.String email, boolean addToSubs)` Adds a search term against Contact.P_EMAILS property and pre-validates the value given in the email argument.
`boolean` | `addIntTerm(int prop, ContactSearch.Condition cond, int value, boolean addToSubs)` Adds a search term to a custom contact search object.
`boolean` | `addLanguageTerm(java.lang.String language, boolean addToSubs)` addLanguageTerm
`boolean` | `addMaxAgeTerm(int maxAgeInYears, boolean addToSubs)` construct CONTACT_BIRTHDAY term based on current time * @param maxAgeInYears
`boolean` | `addMinAgeTerm(int minAgeInYears, boolean addToSubs)` construct CONTACT_BIRTHDAY term based on current time * @param minAgeInYears
`void` | `addOr()` used to group terms (AddTerm(1), AddTerm(2), Or(), AddTerm(3), AddTerm(4), etc)
`boolean` | `addStrTerm(int prop, ContactSearch.Condition cond, java.lang.String value, boolean addToSubs)` Adds a string search term to a custom contact search object.
`void` | `extend()` extend if search is EXTENDABLE
`ContactSearch.Status` | `getContactSearchStatus()`
`java.lang.String` | `getPropertyAsString(ContactSearch.Property prop)`
`java.lang.String` | `getPropertyAsString(int prop)`
`Contact[]` | `getResults(int from, int count)` result list is dynamically updated * @param from
`boolean` | `isValid()` checks that terms list is non-empty and does not contain unsupported keys * @return result
`int` | `moduleId()`
`void` | `release()` releases results that are not referenced from elsewhere
`EnumConverting` | `sidGetEnumProperty(PropertyEnumConverting prop)`
`SidGetResponding` | `sidMultiGet(ContactSearch.Property[] requested)` generic multiget of a list of Property
`static SidGetResponding[]` | `sidMultiGet(ContactSearch.Property[] requested, ContactSearch[] objects)` generic multiget of list of Property for a list of ContactSearch
`protected void` | `sidOnChangedProperty(int propertyId, int value, java.lang.String svalue)`
`void` | `sidSetProperty(PropertyEnumConverting prop, int newValue)`
`void` | `submit()` launch search

Methods inherited from class com.skype.ipc.SidObject
`finalize, getOid, hasCached, invalidateCache, isCached, sidDoRequest, sidGetBinaryProperty, sidGetBoolProperty, sidGetFilenameProperty, sidGetIntProperty, sidGetLongProperty, sidGetObject, sidGetObjectProperty, sidGetStringProperty, sidGetUintProperty, sidGetXmlProperty, sidMultiGet, sidMultiGet, sidMultiGet, sidMultiGet, sidRequestBinaryProperty, sidRequestBoolProperty, sidRequestEnumProperty, sidRequestFilenameProperty, sidRequestIntProperty, sidRequestObjectProperty, sidRequestProperty, sidRequestStringProperty, sidRequestUintProperty, sidRequestXmlProperty, sidSetProperty, sidSetProperty, sidSetProperty, sidSetProperty`

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### mContactSearchStatus

    public ContactSearch.Status mContactSearchStatus

Constructor Detail

### ContactSearch

    public ContactSearch(int oid,
                         SidRoot root)

Method Detail

### addMinAgeTerm

    public boolean addMinAgeTerm(int minAgeInYears,
                                 boolean addToSubs)

  construct CONTACT_BIRTHDAY term based on current time * @param minAgeInYears

  Parameters:
    `addToSubs` -
  Returns:
    valid

### addMaxAgeTerm

    public boolean addMaxAgeTerm(int maxAgeInYears,
                                 boolean addToSubs)

  construct CONTACT_BIRTHDAY term based on current time * @param maxAgeInYears

  Parameters:
    `addToSubs` -
  Returns:
    valid

### addEmailTerm

    public boolean addEmailTerm(java.lang.String email,
                                boolean addToSubs)

  Adds a search term against Contact.P_EMAILS property and pre-validates the value given in the email argument. * @param email e-mail addres to search for.

  Parameters:
    `addToSubs` - This argument enables you to group conditions. See ContactSearch class details for more information.
  Returns:
    valid Returns false if the value in email property did not look like a valid email address.

### addLanguageTerm

    public boolean addLanguageTerm(java.lang.String language,
                                   boolean addToSubs)

  addLanguageTerm

  Parameters:
    `language` -
    `addToSubs` -
  Returns:
    valid

### addStrTerm

    public boolean addStrTerm(int prop,
                              ContactSearch.Condition cond,
                              java.lang.String value,
                              boolean addToSubs)

  Adds a string search term to a custom contact search object. * @param 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.

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

### addIntTerm

    public boolean addIntTerm(int prop,
                              ContactSearch.Condition cond,
                              int value,
                              boolean addToSubs)

  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. * @param prop Propkey to search for. Either Contact.P_BIRTHDAY or Contact.P_GENDER * @param cond Search condition (ContactSearch.CONDITION)

  Parameters:
    `value` - Value to match against.
    `addToSubs` - This argument enables you to group conditions. See ContactSearch class details for more information.
  Returns:
    valid Returns true if the ContactSearch term-set remains valid after adding this term.

### addOr

    public void addOr()

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

### isValid

    public boolean isValid()

  checks that terms list is non-empty and does not contain unsupported keys * @return result

### submit

    public void submit()

  launch search

### extend

    public void extend()

  extend if search is EXTENDABLE

### release

    public void release()

  releases results that are not referenced from elsewhere

### getResults

    public Contact[] getResults(int from,
                                int count)

  result list is dynamically updated * @param from

  Parameters:
    `count` -
  Returns:
    contacts

### sidMultiGet

    public SidGetResponding sidMultiGet(ContactSearch.Property[] requested)

  generic multiget of a list of Property

  Parameters:
    `requested` - the list of requested properties of ContactSearch
  Returns:
    SidGetResponding

### sidMultiGet

    public static SidGetResponding[] sidMultiGet(ContactSearch.Property[] requested,
                                                 ContactSearch[] objects)

  generic multiget of list of Property for a list of ContactSearch

  Parameters:
    `requested` - the list of requested properties
  Returns:
    SidGetResponding[] can be casted to (ContactSearch[]) if all properties are cached

### getContactSearchStatus

    public ContactSearch.Status getContactSearchStatus()

### sidGetEnumProperty

    public EnumConverting sidGetEnumProperty(PropertyEnumConverting prop)

  Specified by:
    `sidGetEnumProperty` in interface `SidGetResponding`
  Overrides:
    `sidGetEnumProperty` in class `SidObject`

### getPropertyAsString

    public java.lang.String getPropertyAsString(int prop)

### getPropertyAsString

    public java.lang.String getPropertyAsString(ContactSearch.Property prop)

### sidOnChangedProperty

    protected void sidOnChangedProperty(int propertyId,
                                        int value,
                                        java.lang.String svalue)

  Specified by:
    `sidOnChangedProperty` in class `SidObject`

### sidSetProperty

    public void sidSetProperty(PropertyEnumConverting prop,
                               int newValue)

  Specified by:
    `sidSetProperty` in interface `SidGetResponding`
  Overrides:
    `sidSetProperty` in class `SidObject`

### moduleId

    public int moduleId()

  Specified by:
    `moduleId` in class `SidObject`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010, 2011 Skype Technologies. All Rights Reserved.