Home Page | Project Page at SourceForge


This is a manual page for the Tcladdressbook extension for Tcl. It documents version 1.1.4b1.


NAME

addressbook - manipulate the Mac OS X Address Book database

SYNOPSIS

package require addressbook

addressbook subcommand ?arg arg...?

INTRODUCTION

The argument subcommand indicates what operation to perform. Any unique abbreviation for each subcommand is acceptable. The valid subcommands are explained in the next sections.

SUBCOMMANDS

addressbook add groupID recordID ?recordID ...?

This command lets you add one or more already existing items (persons or groups) designated by their unique ID recordID to the group with ID groupID.

addressbook changed

This command returns 1 if there has been changes made to the database, 0 otherwise. Changes are made in memory with commands such as addressbook set, addressbook create, addressbook delete. To make these changes permanent, one must call the addressbook save command.

addressbook count (-groups | -persons) ?-ingroup groupID?

This command returns the count of existing groups or persons in the database. One can specify a particular group with the -ingroup option to count only the subgroups or members in this group.

addressbook create (group | person) name ?-ingroup groupID?

This command lets you create a new group or a new person record. The name argument is the name to give to the new group or the last name of the person for which a new record is created. With the -ingroup option one can make the newly created record a subgroup or a member of the particular group with unique ID groupID. If no error occurs, the command returns the unique ID of the created record.

addressbook delete recordID

This command removes the record with unique ID recordID from the database. Note that any changes made to the database won't be definitive until you invoke the addressbook save command.

In version 1.0 of the extension, this command used to accept an option called -fromgroup in order to remove the record from a particular subgroup. This is achieved now by the addressbook remove command.

addressbook export personID

This command lets you export the record with unique ID personID as a VCard. The result should be considered as binary data since it can contain an image associated to the record.

addressbook getme ?-id?

This command returns the ID or the data corresponding to the logged-in user ("Me"). If the -id option is specified, it returns the unique ID of the logged-in user. Otherwise the returned value takes the form of a keyed list: see the addressbook record command for a description of this format. Keyed lists can be easily manipulated with the keylget and keylset commands defined in the TclX extension.

addressbook groups ?-ids? ?-ingroup groupID?

This command returns a list of all the existing group records: if no option is specified, it is a list whose elements are sublists made of two elements. The first element is the unique ID associated with the group and the second is its name. If the -ids argument is specified, the returned list will contain only the unique IDs of the groups. If the -ingroup option is specified, only the subgroups contained in the group with ID groupID will be returned.

addressbook identifier count personID propName

This command returns the number of items in a multi-value list property (such as Phone, Email, Address, MSNInstant etc.).

addressbook identifier get personID propName index

This command gets the unique identifier of an item in a multi-value list property (such as Phone, Email, Address). It returns the identifier of the item at index index in the multi-value list of property propName for the record corresponding to personID. One can get the count of identifiers using the addressbook identifier count command. Identifiers are used by the addressbook identifier set command. See the section Distribution lists and identifiers below for explanations about identifiers.

addressbook identifier index personID propName ident

This command returns the index in a multi-value list corresponding to the identifier given in the ident argument. If ident is not a valid identifier, the command raises an error. The valid identifers are the values obtained by the addressbook identifier get command.

addressbook identifier primary personID propName ?ident?

This command lets you get or set the primary identifier of property propName in the record personID. This is the identifier which will be used by default if no distribution identifier has been specified using the addressbook identifier set command. Property propName must be a multi-value list property (such as Phone, Email, Address).

Used without the ident argument, the command will return the primary identifier concerning property propName for the person personID.

If the ident argument is specified, the command will set the primary value to be the value for the given identifier ident. This value must be a valid identifier used by the multi-value list: one can get the identifiers of any element of a multi-value list using the addressbook identifier get command.

addressbook identifier set groupID personID propName ?ident?

This command lets you get or set the distribution identifier for a multi-value list property of a person in a group. See the section Distribution lists and identifiers below for explanations about identifiers.

Used without the ident argument, the command will return the distribution identifier for the person personID belonging to the group groupID concerning property propName if it was set, otherwise the property's primary identifier. Property propName must be a multi-value list property (such as Phone, Email, Address).

If the ident argument is specified, this will assign a specific distribution identifier for the person's multi-value list property so that the group can be used as a distribution list (a mailing list for instance, in the case of an email property). This value must be a valid identifier used by the multi-value list: one can get the identifiers of any element of a multi-value list using the addressbook identifier get command.

addressbook image personID ?imageData?

If no imageData argument is specified, this command returns the custom image associated with the record corresponding to the unique ID personID. The returned bytes are binary data. If no image exists, it raises an error. If an imageData argument is specified, it should contain valid binary data defining an image which will be associated the record with unique ID personID.

addressbook import vCardData

This command imports data in VCard format. The data specified by the vCardData argument must be valid data in VCard format: a new record is created in the database corresponding to the information contained in the VCard. Note that the data can be binary if the VCard contains an image. Starting from version 1.1.1 of the extension, the image is also imported by the command as a custom icon for the record.

addressbook label personID propName index ?value?

This command lets you get or set the label of a value in a multi-value property for a particular record.

Used without the value argument, the command will return the current label at index index in property propName for the person personID. To determine the index range, one can use the addressbook identifier count command.

If the value argument is specified, the command will set the label at index index to this value.

addressbook parents ?-ids? recordID

This command returns a list of all the groups the record with unique ID recordID belongs to. The elements of this list are sublists made of one or two items: the unique ID and, possibly, the name of the record if this field exists. If the -ids option is specified, only IDs are returned.

addressbook persons ?-ids? ?-ingroup groupID?

This command returns a list of all the existing person records: if no option is specified, it is a list whose elements are sublists made of one or two items: the unique ID and, possibly, the name of the record if this field exists. If the -ids argument is specified, the returned list will contain only the unique IDs. If the -ingroup option is specified, only the members belonging to the group with ID groupID will be returned.

addressbook property names (-groups | -persons)

This command returns a list of all the properties defined in the database for group or person records. New properties can be created or removed with the addressbook property add and addressbook property remove commands.

addressbook property type (-groups | -persons) propName

This command returns the type of the property specified by the propName argument. The returned type is one of the values listed with the addressbook property add command below or Unknown.

addressbook property add (-groups | -persons) propName propType

This command lets you add a new property to the database, either for person or for group records. The name of the new property is specified by the propName argument: it must be unique. One can get the list of all the existing properties with the addressbook property names command. The type of the property is specified by the propType argument. This argument can have one of the following values: Array, Data, Date, Dictionary, Integer, Real, String, MultiArray, MultiData, MultiDate, MultiDictionary, MultiInteger, MultiReal, MultiString.

addressbook property remove (-groups | -persons | recordID) propName

This command lets you remove a property from the database, either for person or for group records. The name of the property is specified in the propName argument. If the third argument is either -groups or -persons, the command should remove the given property from all the records of this type in the Address Book database and return the number of properties successfully removed. Otherwise the third argument should be the record ID of a particular person or group: the property is removed for this record only and the command returns an empty string.

One can get the list of all the existing properties with the addressbook property names command.

addressbook record recordID

This command returns all the data available in the database concerning the record with unique ID recordID. The returned value takes the form of a keyed list.

The format used for a particular property's value depends on the type of the property (string, integer, date, multivalue etc.). Some properties have a multiple type: MultiString for fields like Email, Phone etc., MultiDate for fields like ABDate, MultiDictionary for the Address field. In case of a multivalue, the returned value is a keyed list itself. Each element of the list corresponds to a single property. For instance:

Dates are returned as values suitable for use with the clock format Tcl command. It is the number of seconds relative to "Thu Jan 01 00:00:00 CET 1970".

Note that keyed lists can be easily manipulated using the keylget and keylset commands defined in the TclX extension.

addressbook remove groupID recordID ?recordID ...?

This command lets you remove one or more already existing items (persons or groups) designated by their unique ID recordID from the group with ID groupID.

addressbook save

This command lets you save the changes made in the database. Commands such as addressbook set, addressbook create or addressbook delete modify the data in memory: to make the changes definitive in the database, one must call explicitely the addressbook save command. To check whether there has been changes in the database, use the addressbook changed command.

addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? property op value

This command returns all the records corresponding to the criterion described by the last three arguments:

The -groups or -persons options let you specify the kind of records you want to search. If it is not specified, the default is -person. If the -ids option is specified, only IDs of the matching records are returned, rather than pairs made of the ID and the name. The -nocase argument concerns string comparisons and requires that no distinction be made between uppercase and lowercase letters.

To get a list of all possible properties, use the addressbook property names command. To know the type of a particular property, use the addressbook property type command.

addressbook set recordID propertyName ?value?

This command lets you get or set the value of a particular property for the record with unique ID recordID. If the value argument is not specified, it returns the current value of the property specified in the propertyName argument. If value is specified, the property propertyName will be set to this value. See the addressbook record command for a description of the format used for the various kinds of properties.

addressbook setme recordID

This command sets the record that represents the logged-in user.

addressbook type recordID

This command returns the type (ABPerson or ABGroup) of the record with unique ID recordID.

DISTRIBUTION LISTS AND IDENTIFIERS

Identifiers are necessary when one wants to use a group as a distribution list, that is send something to all the members of the group. The members can be addressed by Address, Phone, Email etc. For instance, a group could be used as a mailing list. The Address, Phone, Email properties are multi-value list properties: since a person can have several e-mail addresses, one must specify which one is to be used in the distribution list. Labels (such as Home, Work etc.) are not sufficient to specify precisely an e-mail because they are not unique: one can have several e-mails with the label Work. Here the identifiers come in: each value of a multi-value list property has an identifier. One of them can be designated as the distribution identifier. The AddressBook database also has a notion of a primary identifier: it is the identifier which will be used by default by the distribution list if no distribution identifier as been specified.

INSTALLATION

The extension is made of two files: the dynamic library (called addressbook1.1.dylib in version 1.1) and a file pkgIndex.tcl necessary for Tcl to be able to locate the extension upon request. Both files are contained in a folder called TclAddressBook1.1, in version 1.1. This folder should be installed on your system in /Library/Tcl or in ~/Library/Tcl or, more generally, in any folder contained in your auto_path Tcl variable. If you use the extension within the AlphaX editor (version 8.0b11 or greater), you can also install it in the Tclextensions folder which is located at the same level as the application.

VERSION HISTORY

REQUIREMENTS AND PORTABILITY

This extension is only useful on Macintosh platforms. Version 10.2 or greater of the system is required: the AddressBook framework was introduced in version 10.2 of the System (aka Jaguar).

KNOW ISSUES

Tcladdressbook was written by Bernard Desgraupes. Please e-mail any bug or problem you encounter: bdesgraupes@users.sourceforge.net

SOURCE CODE

Tcladdressbook is an Open Source Project. Its source code is public and can be found on the SourceForge site at the following address:

http://sourceforge.net/projects/tcladdressbook

Tcladdressbook binary releases are available at

http://sourceforge.net/project/showfiles.php?group_id=96169 or on my web page at

http://perso.orange.fr/bdesgraupes/tcl.html

The code is under CVS control. You can retrieve the latest stage of development using any CVS client. See instructions at:

http://sourceforge.net/cvs/?group_id=96169

You can also browse the cvs repository online at

http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook

CONTRIBUTIONS

Code contributions (Tcl scripts making use of the Tcladdressbook extension) are very welcome. There is a "Contribs" directory in the Tcladdressbook project on SourceForge for code contributions. They must be free software, distributed under an Open Source license acceptable by the SourceForge site (for instance, the same licensing terms as the Tcl language itself).

LICENSE AND DISCLAIMER

This software is free software and distributed under the same licensing terms as the Tcl language itself. See license.terms in the Tcl distribution.

(c) Copyright: Bernard Desgraupes 2003-2006

SEE ALSO

See the TclX extension for keyed lists: TclX(n). See the Mk4Tcl extension for commands to open directly the database file.

KEYWORDS

Address book, data base.


Last updated 2006-10-14 15:01:05