Python na Symbian-u

5. KONTAKTI

5.1. Uvod

Modul kontakata obezbeđuje API (Application Programming Interface) koji nam omogućava da otvorimo default imenik uređaja, te da izvršavamo operacije poput pretrage, čitanja, dodavanja, izmena i brisanja unosa.

Baza podataka kontakata je predstavljena pomoću ContactDb, koja sadrži broj Contact objekata, koji pak sadži ContactField objekte. ContactDb je objekat poput dictionary-ja koji je indeksiran jedinstvenim ID-jem bilo kojih Contact-a koji su sadržani. Contact-i su objekti poput listi, indeksirani su koristeći polje indeksa sadržanih u ContactField objektima.

ContactDb predstavlja 'živi' pregled baze podataka. Promene načinjene bazi podataka su odmah vidljive spoljašnjim aplikacijama i obrnuto. Kontakti su zaključani za izmene pre modifikacije i otključani odmah nakon izmene.

Naredno poglavlje objašnjava kako pretraživati, dodavati, brisati i uređivati kontakte i kako raditi sa grupama kontakata. Dodatne informacije su dostupne na http://pys60.garage.maemo.org/doc/s60/module-contacts.html

5.2. Otvaranje baze podataka

Baza podataka mora biti otvorena pre nego što se pristupi operacijama sa kontaktima. Kako bismo otvorili default bazu podataka uređaja, poziva se metod open() modula kontakata, kao što je prikazano ispod:

import contacts

#Otvori default bazu podataka kontakata
db = contacts.open()

U teoriji, možemo kreirati i našu sopstvenu bazu podataka za specifičnu aplikaciju (application-specific database) prosleđujući ime baze podataka i mode metodi open(). Međutim, funkcionalnost se smatra nepouzdanom, prema zvaničnoj dokumentaciji na, http://pys60.garage.maemo.org/doc/s60/module-contacts.html, i u svakom slučaju je ograničena mogućnost upotrebe.

Nema potrebe za eksplicitnim zatvaranjem baze podataka kontakata, ona se automatski zatvara kada objekat kontakata istupi iz opsega važenja.

5.3. Dodavanje kontakta

Da bismo kreirali novi kontakt, prvo otvaramo bazu podataka, kreiramo Contact objekat, dodajemo željena polja i vrednosti i sačuvamo to pozivanjem commit().

Sledeći deo koda kreira novi kontakt, određujući ime i broj mobilog telefona.

import contacts

#Open the default contact database
db = contacts.open()

#Add new contact's details
c = db.add_contact()
c.add_field('first_name', 'Samantha')
c.add_field('mobile_number', '0123456789')

#And save the changes
c.commit()

Sledeća tabela prikazuje listu najuobičajnijih tipova polja dostupnih od Nokia S60 (3rd Edition), pa nadalje (Tabela 8 ). Polja ovih tipova se dodaju korištenjem add_field(), koji koristi istu sintaksu kao prethodni deo koda.

Tabela 8 – Lista najuobičajnijih polja pri dodavanju kontakta

city	company_name	country	date
dtmf_string	email_address	extended_address	fax_number
first_name	job_title	last_name	mobile_number
note	pager_number	phone_number	po_box
postal_address	postal_code	state	street_address
url	video_number	picture	second_name
voip	sip_id	personal_ringtone	share_view
prefix	suffix	push_to_talk	locationid_indication
city	company_name	country	date
dtmf_string	email_address	extended_address	fax_number
first_name	job_title	last_name	mobile_number
note	pager_number	phone_number	po_box
postal_address	postal_code	state	street_address
url	video_number	picture	second_name
voip	sip_id	personal_ringtone	share_view
prefix	suffix	push_to_talk	locationid_indication

Zvanična dokumentacija na http://pys60.garage.maemo.org/doc/s60/node83.html objašnjava koji tip podatka se može dodeliti, a takođe nabraja i nekoliko polja koja se prepoznaju, ali se ne mogu kreirati.

5.4. Brisanje kontakta

Sledeći deo pokazuje kako pronaći ID određenog kontakta i, kada je ID poznat, kontakt se može izbrisati iz baze podataka korištenjem del operatora sa njegovim ID-jem. Naredno deo koda prikazuje kako se briše prvi Contact objekat koji sadrži 'Samantha' u svom imenu:

import contacts

#Open the default contact database
db = contacts.open()

#Search for a contact whose name is Samantha
l = db.find('Samantha')

#l is a list of contacts matching the criterion
#We only need the first one, if it exists
if len(l) > 0:
    c = l[0]
    #Get its ID
    id = c.id

    #Delete it
    del db[id]
else:
    print "No such contact found"

5.5. Traženje kontakta

Nad bazom podataka kontakata se može izvršiti upit za kontakte koji sadrže određeni string u bilo kom od svojih polja, korištenjem find() metoda, prosleđujući traženi string kao argument te metode. Pretraga se onda može 'pročistiti' da bi se videlo da li se određeno polje poklapa sa kriterijumom pretrage.

Na primer, sledeći deo koda prvo izvlači sve kontakte koji sadrže tekst „James“ u bilo kom polju, i onda među nađenima, vrši novu pretragu i prikazuje informacije za one kontakte koji imaju „James“ samo u polju first_name.

import contacts

#Open the database
db = contacts.open()

#Retrieve every contact that contains the name "James"
#and display only those that have it in the first_name field
for c in db.find('James'):
if c.find('first_name')[0].value == u"James":
print c.find('first_name')[0].value + " " + c.find('last_name')[0].value + " " c.find('mobile_number')[0].value

5.6. Izmena postojećih kontakata

Izmena kontakta se može uraditi na dva načina. Jednostavni način je naprosto načiniti izmene i onda pozvati metodu commit() objekta kontakta, koji ga snima (čuva).
Druga opcija je:

pozvati metod begin() objekta kontakta, koji zaključava kontakt za uređivanje (čineći ga tako nedostupnim za ostale aplikacije)
načiniti promene
onda pozvati metodu commit() objekta kontakta, koji uklanja blokadu i sačuvava (snima) izmene.

Ukoliko poželimo poništiti promene (undo), možemo jednostavno pozvati rollback() metod objekta umesto commit(), koji uklanja blokadu i vraća kontakt u stanje u kom je bio pre nego što je begin() pozvan.

Moguće je dodati nova polja (kao što je prikazano u poglavlju 'Dodavanje kontakta') i postojeća polja, nazivi (labels) i vrednosti se takođe mogu prilagoditi, kao što je prikazano u sledećem primeru:

#Promene se ponište (undo) na kraju
import contacts

db = contacts.open()
c = db.find('Jim')[0]

c.begin()

#Pribavi "last_name" polje ako postoji, promeni mu vrednost u neko drugo ime i njegovu labelu(naziv) u "Surname"
if c.find("last_name"):
c.find("last_name")[0].value = u"Cohen"
c.find("last_name")[0].label = u"Surname"

#Poništi promene
c.rollback()

#Promene se sačuvaju i kontakt ostaje promenjen
import contacts

db = contacts.open()
c = db.find('Jim')[0]

#Pribavi "last_name" polje ako postoji, promeni mu vrednost u neko drugo ime i njegovu labelu(naziv) u "Surname"
if c.find("last_name"):
c.find("last_name")[0].value = u"Cohen"
c.find("last_name")[0].label = u"Surname"

#Sačuvaj promene
c.commit()

Konačno, pojedinačna polja se mogu ukloniti iz kontakta upotrebom del operatora.

5.7. Rad sa grupama

Python na Symbian-u dozvoljava nam kreiranje i pristup povezanim kontaktima koristeći Group objekte, i daje pristup skupu Group objekata preko Groups objekta.

Jednostavno rečeno, Group je objekat nalik na listu koji sadrži ID-je Contact objekata koji pripadaju toj grupi. Groups objekat je kolekcija u obliku dictionary-ja svih Group objekata iz baze podataka, kojima se pojedinačno može pristupiti korištenjem jedinstvenog ID-ja Group-e.

Kao i sa svakom drugom operacijom s kontaktima, baza podataka mora biti otvorena da bi se mogle izvršavati operacije sa grupama.

5.7.1. Kreiranje nove grupe

Nakon kreiranja objekta Groups, koristi se njegov add_group(name) metod za kreiranje nove grupe (novog Group objekta).

Naredni deo koda dodaje grupu 'My new group' Groups objektu (a samim tim i bazi podataka):

import contacts

#Otvori bazu podataka
db = contacts.open()

#Iniciraj Groups objekat
groups = db.Groups(db)

#Dodaj novu grupu
group = groups.add_group(u"My new group")

5.7.2. Vraćanje postojećih grupa

Grupe se identifikuju njihovim jedinstvenim ID-jem. Lista jedinstvenih ID-ja grupa se može pribaviti pozivanjem Python-ove ugrađene funkcije list() na iterator objektu, koja se vraća pozivom Python-ove ugrađene funkcije iter() na Groups objektu.

Naredni deo koda koristi iterator liste da ispiše imena svih grupa, na osnovu njihovih ID-ja:

import contacts

# Otvori bazu podataka
db = contacts.open()

#Pribavi listu ID-ja dostupnih grupa
ids = list(iter(db.groups))

#Prikaži imena grupa
for id in ids:
print db.groups[id].name

5.7.3. Brisanje grupa

Grupa se briše iz objekta Groups i, istovremeno iz baze podataka upotrebom Python-ovog del() operatora. Naredni deo koda pribavlja listu postojećih grupa po ID-ju, onda poziva del() da ukloni određeni Group objekat:

import contacts

# Otvori bazu podataka
db = contacts.open()

# Pribavi listu ID-ja dostupnih grupa
ids = list(iter(db.groups))

# Izbriši grupu čiji je ID prvi na listi
del db.groups[ids[0]]

*Napomena: Brisanje grupe neće izbrisati članove te grupe, tj. kontakti iz te grupe se ne brišu iz baze podataka kontakata, već ostaju u listi kontakata telefona.

5.7.4. Dodavanja ili uklanjanje kontakata iz grupe

Pozivanje append(id) metoda objekta Group dodaje kontakt sa odgovarajućim ID-jem grupi, kao što to prikazuje naredni kod.

import contacts

# Otvori bazu podataka
db = contacts.open()

# Pribavi listu ID-ja dostupnih grupa
group_ids = list(iter(db.groups))

#Otvori prvu grupu na listi
group = db.groups[group_ids[0]]

#Pribavi listu ID-ja svih kontakata
contact_ids = contacts.open().keys()

#Dodaj prvi kontakt na listi
group.append(contact_ids[0])

Za uklanjanje kontakta iz grupe, koristimo del() operator na grupi.