Schemat pliku kontaktów w GG 8 i nowszych

Twórcy komunikatora GG wraz z jego ósmą wersją wprowadzili nowy schemat pliku listy kontaktów. Wcześniej używany format CSV został zastąpiony formatem XML.

Plik kontaktów jest domyślnie kodowany w UTF-8. Składa się z jednej długiej linii (pomiędzy elementami nie występują żadne białe znaki), więc jest przeznaczony raczej do czytania przez maszyny niż ludzi. Nie zawiera żadnych komentarzy. Brak jest również deklaracji typu dokumentu, zalecanej przez specyfikację XML.

Budowa pliku

  1. Ogólna budowa pliku
  2. Definicje grup
  3. Definicje kontaktów

Ogólna budowa pliku

Poniżej znajduje się przykładowa konstrukcja pliku listy kontaktów. Dla zachowania czytelności, w kodzie użyte zostały wcięcia. W przykładzie użyte zostały jedynie wymagane elementy. Wszystkie dostępne elementy opisane są w dalszej części dokumentu.

<ContactBook>
	<Groups>
		<Group>
			<Id>Identyfikator</Id>
			<Name>Nazwa grupy</Name>
			<IsExpanded>Boolean</IsExpanded>
			<IsRemovable>Boolean</IsRemovable>
		</Group>
	</Groups>
	<Contacts>
		<Contact>
			<Guid>Identyfikator</Guid>
			<GGNumber>Numer GG</GGNumber>
			<ShowName>Wyświetlana nazwa kontaktu</ShowName>
			<Groups>
				<GroupId>Identyfikator grupy</GroupId>
			</Groups>
			<Avatars>
				<URL></URL>
			</Avatars>
			<FlagNormal>Boolean</FlagNormal>
		</Contact>
	</Contacts>
</ContactBook>
Jak widać, wszystkie elementy są potomkami elementu <ContactBook>

Definicje grup

Wszystkie grupy są bezpośrednim potomkiem elementu <Groups>.

Definicje właściwości każdej grupy są zawarte w elemencie <Group>. Każdy element <Group> zawiera właściwości tylko jednej grupy.

Właściwości grup

<Id>Identyfikator</Id>

Unikalny identyfikator grupy (UUID) zgodny z RFC 4122.

Identyfikatory 00000000-0000-0000-0000-000000000000 oraz 00000000-0000-0000-0000-000000000001 są zarezerwowane dla dwóch podstawowych grup GG — pierwsza dla grupy Moje kontakty (domyślna grupa do której należą wszystkie kontakty nie należące do żadnej innej grupy), druga dla grupy Ignorowani (grupa osób, od których wiadomości nie będą dostarczane do użytkownika).

<Name>Nazwa grupy</Name>

Nazwa grupy wyświetlana na liście kontaktów.

<IsExpanded>Boolean</IsExpanded>

Informacja, czy grupa jest aktualnie zwinięta czy rozwinięta w oknie listy kontaktów komunikatora. Jeśli lista jest zwinięta, wyświetlana jest tylko jej nazwa. Jeśli lista jest rozwinięta, wyświetlana jest jej nazwa oraz wszystkie należące do niej kontakty.

Przyjmowane wartości: true oraz false (pisane małymi literami). true oznacza że lista jest aktualnie rozwinięta. false oznacza że lista jest aktualnie zwinięta.

<IsRemovable>Boolean</IsRemovable>

Informacja, czy grupa może być usunięta. Jeśli grupa może zostać usunięta i zostanie usunięta, wszystkie należące do niej kontakty automatycznie wracają do grupy Moje kontakty.

Przyjmowane wartości: true oraz false (pisane małymi literami). true oznacza że grupa może zostać usunięta. false oznacza że grupa nie może zostać usunięta. Domyślnie wartość false mają grupy Moje kontakty i Ignorowani.

Definicje kontaktów

Wszystkie kontakty są bezpośrednim potomkiem elementu <Contacts>.

Definicje właściwości każdego kontaktu są zawarte w elemencie <Contact>. Każdy element <Contact> zawiera właściwości tylko jednego kontaktu. Właściwości poniżej zostały opisane w kolejności, w jakiej występują w pliku listy kontaktów.

Właściwości kontaktów

<Guid>Identyfikator</Guid>

Unikalny identyfikator grupy (UUID) zgodny z RFC 4122.

<GGNumber>Numer GG</GGNumber>

Numer Gadu-Gadu kontaktu.

<ShowName>Wyświetlana nazwa kontaktu</ShowName>

Nazwa kontaktu, która jest wyświetlana na liście kontaktów komunikatora.

<MobilePhone>Numer telefonu</MobilePhone>

Numer telefonu komórkowego kontaktu. Użytkownik musi go wpierw samodzielnie wpisać w komunikatorze.

<HomePhone>Numer telefonu</HomePhone>

Numer telefonu stacjonarnego kontaktu. Użytkownik musi go wpierw samodzielnie wpisać w komunikatorze.

<Email>Adres e-mail</Email>

Adres e-mail kontaktu. Użytkownik musi go wpierw samodzielnie wpisać w komunikatorze.

<WwwAddress>Adres strony WWW</WwwAddress>

Adres strony WWW kontaktu. Użytkownik musi go wpierw samodzielnie wpisać w komunikatorze.

<FirstName>Imię</FirstName>

Imię kontaktu. Nie może zostać uzupełnione przez użytkownika w komunikatorze. Wypełniane jest automatycznie jeśli kontakt został dodany poprzez wyszukiwarkę katalogu publicznego (oczywiście tylko w sytuacji, gdy dany kontakt udostępnił tę informację) lub poprzez import listy kontaktów w starym formacie (o ile znajdowała się w nim ta informacja).

<LastName>Nazwisko</LastName>

Nazwisko kontaktu. Nie może zostać uzupełnione przez użytkownika w komunikatorze. Wypełniane jest automatycznie jeśli kontakt został dodany poprzez wyszukiwarkę katalogu publicznego (oczywiście tylko w sytuacji, gdy dany kontakt udostępnił tę informację) lub poprzez import listy kontaktów w starym formacie (o ile znajdowała się w nim ta informacja).

<Gender>Płeć</Gender>

Liczba reprezentująca płeć kontaktu.

Przyjmuje wartości: 1 oraz 2. 1 oznacza kobietę, zaś 2 mężczyznę.

<Birth>Data urodzenia</Birth>

Data urodzenia kontaktu. Nie może zostać uzupełnione przez użytkownika w komunikatorze. Pole wypełniane jest automatycznie jeśli kontakt został dodany poprzez wyszukiwarkę katalogu publicznego (oczywiście tylko w sytuacji, gdy dany kontakt udostępnił tę informację).

Data jest zapisywana w formacie strftime %-d %B %Y; np. 2 czerwiec 1981.

<City>Miejscowość</City>

Miejsce zamieszkania kontaktu. Nie może zostać uzupełnione przez użytkownika w komunikatorze. Pole wypełniane jest automatycznie jeśli kontakt został dodany poprzez wyszukiwarkę katalogu publicznego (oczywiście tylko w sytuacji, gdy dany kontakt udostępnił tę informację).

<Groups></Groups>

Element stanowiący ramę dla listy grup, do których należy dany kontakt.

<GroupId>Identyfikator grupy</GroupId>

Identyfikator grupy, której członkiem jest dany kontakt. Każdy kontakt musi należeć przynajmniej do jednej grupy (właśnie dlatego istnieje nieusuwalna grupa Moje kontakty). Każdy kontakt może należeć do wielu grup jednocześnie; górna granica nie jest zbadana, jednak wynosi więcej niż dwanaście. Kontakt ignorowany należy do grupy Ignorowani. Kontakt może należeć do grupy Ignorowani oraz innych grup jednocześnie.

<Avatars>
	<URL></URL>
</Avatars>

Prawdopodobnie ścieżka do awataru użytkownika. W trakcie testów nie udało się doprowadzić do sytuacji, gdy element <URL/> przyjąłby jakąkolwiek wartość.

<FlagNormal>Boolean</FlagNormal>

Element zastępczy który występuje jeśli kontakt nie jest ignorowany ani nie ma zaznaczonej flagi niewysyłania informacji o statusie przy zaznaczonej opcji Tylko dla znajomych.

Teoretycznie powinien przyjmować wartości true oraz false. W rzeczywistości jednak, jeśli występuje to przyjmuje wartość true, jeśli zaś kontakt ma ustawioną którąś z opcjonalnych właściwości (poniżej), nie występuje w ogóle.

<FlagBuddy>Boolean</FlagBuddy>

Informacja, czy danemu kontaktowi wysyłać status jeśli w komunikatorze jest zaznaczona opcja Tylko dla znajomych. Jeśli jest ona zaznaczona, informacje o statusie są wysyłane tylko osobom znajdującym się na liście kontaktów (pozostałym jest wysyłany status Niedostępny). Jeśli dodatkowo przy kontakcie jest zaznaczona ta opcja, danemu kontaktowi również wysyłany jest status Niedostępny.

Teoretycznie powinien przyjmować wartość true oraz false. W rzeczywistości jednak, jeśli występuje to przyjmuje wartość true, jeśli zaś dany kontakt nie ma zaznaczonej opcji Ukrywaj przy opcji "Tylko dla znajomych", nie występuje w ogóle.

Nie może występować jednocześnie z <FlagNormal/>. Może występować jednocześnie z <FlagIgnored> (poniżej).

<FlagIgnored>Boolean</FlagIgnored>

Informacja o tym, czy dany kontakt znajduje się na liście ignorowanych użytkowników. Każdy ignorowany kontakt ma równocześnie identyfikator grupy Ignorowani w elemencie <Groups/>, tak więc listę ignorowanych użytkowników można uzyskać na dwa sposoby.

Teoretycznie powinien przyjmować wartość true oraz false. W rzeczywistości jednak, jeśli występuje to przyjmuje wartość true, jeśli zaś dany kontakt nie ma zaznaczonej opcji Ignoruj, nie występuje w ogóle.

Nie może występować jednocześnie z <FlagNormal/>. Może występować jednocześnie z <FlagBuddy> (powyżej).

<NickName>Pseudonim</NickName>

Pseudonim kontaktu. Nie może zostać uzupełnione przez użytkownika w komunikatorze. Wypełniane jest automatycznie jeśli kontakt został dodany poprzez wyszukiwarkę katalogu publicznego (oczywiście tylko w sytuacji, gdy dany kontakt udostępnił tę informację) lub poprzez import listy kontaktów w starym formacie (o ile znajdowała się w nim ta informacja).

Written by Minio.