DMKit 2 0 API


DotMac Kit 2.0 (Developer Preview)
Abstract
The purpose of the DotMac Kit and its contained classes is to give developers all of the
tools required to tightly integrate the Internet-based services offered by Apple in its .Mac
product with their own. Additionally, .Mac developers have the opportunity to join
the .Mac Affiliate Program and earn a commission for every new .Mac membership that
they help generate.
The basic usage pattern for the Kit is that a DMMemberAccount instance can be created
and used to perform .Mac-specific functions, such as checking which services are
available to a given account, and can also be used in creating instances of individual
sessions with .Mac services, such as the iDisk service or the store-and-forward messaging
service. Each session is a specific object that encapsulates all state, network, and general
overhead work required to interface efficiently with a given .Mac service.
Version 2.0 of the DotMac Kit introduces API’s for Internet-based collaboration,
workflow and security, enabling powerful networked features not available on any other
platform.
Class Diagram
Description
At the highest level, the DotMac Kit enables you to perform data transfer, distributed
messaging and related user account transactions with the .Mac Internet Services
environment, all without having to worry about the underlying transport protocols,
security, or servers. The framework enables data I/O via iDisk and an interface
into .Mac’s store-and-forward messaging service, along with mechanisms for dealing
with specific attributes of a member’s .Mac account. Used by Apple’s own iApps
and .Mac’s application servers, the Kit is open standards-based and is the easiest way to
integrate with .Mac.
Many applications can benefit from the DotMac Kit. Document-centric applications, for
instance, can use the Kit’s workflow and collaboration features for sharing documents,
and can use iDisk for data backup or secure distribution. Multi-player or turn-based
games can use the Kit to communicate events across computers or to save game state to
an iDisk. Any application that requires reliable notifications or inter-application
communication, be it for distributed solutions or anything involving resource tracking or
reservation, can benefit.
And it’s free. At no cost to your application, the DotMac Kit gives you access to
the .Mac infrastructure and to well over half a million paying members. .Mac’s scalable
services, systems support and 24/7 monitoring make adding Internet-based features to
your application headache-free. Plus, you earn $15 for every member you sign up (see
the included ‘Affiliate Program’ document for more information).
The rest of this document covers the DotMac Kit 2.0 API’s in detail. Read on to learn
how easy it is to include powerful Internet-based features in your app.
2
Table of Contents
Constants ...........................................................................................4
Using Transactions ........................................................................... 8

DMTransaction ........................................................................................................................ 8
DMTransactionDelegate (Informal Protocol) ...................................................................... 12
DMTransactionGenerator (Formal Protocol) ...................................................................... 13
Credentials and Account Management ......................................... 14

DMCredential (Formal Protocol) .......................................................................................... 15
DMMemberAccount .............................................................................................................. 15
DMSecondaryUser .................................................................................................................20
DMGroup ................................................................................................................................ 21
DMPrincipal (Formal Protocol) ............................................................................................ 22
Security and Access Control ..........................................................23

DMSecurity (Formal Protocol) ............................................................................................. 23
DMUtilities ............................................................................................................................. 25
Transferring Data with iDisk ........................................................... 26

DMiDiskSession .................................................................................................................... 27
DMiDiskFileManager (Category of DMiDiskSession) ......................................................... 35
Using DMSecurity on DMiDiskSession ............................................................................... 37
Using Store-and-forward Messaging .......................................... 38

DMMessagePublisher ........................................................................................................... 39
DMMessageSubscriber ......................................................................................................... 43
DMSubscriptionDelegate (Informal Protocol) .....................................................................48
DMTopic ................................................................................................................................. 49
DMMessage ........................................................................................................................... 52
3
Constants
The NSString key constants below are used to access quota property values contained in
the NSDictionary created by DMiDiskSession’s -quotaAttributes method (the
NSDictionary is retrieved using DMTransaction’s result method):
Key Constant Corresponding Value Type
kDMiDiskQuotaInBytes NSNumber (bytes)
kDMiDiskSpaceUsedInBytes NSNumber (bytes)
DMMemberAccount’s -servicesAvailableForAccount method creates an NSArray of

NSString values (retrieved using DMTransaction’s result method), each of which will
equal one of these NSString constants:
Service Constant Meaning
kDMiDiskService The account has iDisk storage associated
with it.
kDMEmailService The account has an email address along with
the associated email storage.
kDMWebHostingService The account has web hosting capabilities
through its iDisk’s Sites folder.
kDMiSyncService The account has access to .Mac’s iSync-
related functionality.
Status Constants: The -validateCredentials and -errorType methods (from

DMMemberAccount and DMTransaction respectively) may return the following integer
status codes (or kDMUndefined) as appropriate:
Status Constant Meaning
kDMSuccess The operation was successful.
kDMNetworkError Unable to interact with .Mac because of a
networking error or lack of network
availability.
kDMInvalidCredentials The .Mac credentials set for this object do
not have access to a .Mac account.
kDMInsufficientStorage The .Mac account does not have sufficient
disk space to accommodate the given
operation.
kDMResourceNotFound A required resource was not found.
kDMResourceExists Indicates an error due to the pre-existence of
a given resource.
kDMServiceBusy The given .Mac service was too busy to
perform the requested operation and the
operation should be retried later.
kDMInvalidParameter A user-provided parameter was invalid.
4
kDMUnknownError Unable to complete operation because of an
unknown error.
Certain methods in this framework return an “Undefined” value when appropriate and as
noted in the method descriptions of this document.
Status Constant Meaning
kDMUndefined Used by individual methods as noted in this
document’s method descriptions.
DMiDiskSession’s -basicAttributesAtPath: method creates an NSDictionary (retrieved

using DMTransaction’s result method) which contains resource attributes whose values
can be accessed using the following NSString key constants:
kDMContentLength NSNumber (bytes)
kDMLastModified NSDate
DMiDiskSession’s -extendedAttributesAtPath: method creates an NSDictionary

(retrieved using DMTransaction’s -result method) which contains resource attributes
whose values can be accessed using the following NSString key constants:
kDMURI NSString
kDMContentType NSString
kDMIsCollection NSNumber (Boolean)
kDMIsLocked NSNumber (Boolean)
kDMLockOwner NSString
kDMLockToken NSString
kDMLockTimeout NSNumber (seconds)
5
DMTransaction’s -transactionState method returns one of the following integer status
codes:
Transaction State Constant Meaning
kDMTransactionNotStarted The transaction has not yet started.
kDMTransactionActive The transaction is in progress.
kDMTransactionSuccessful The transaction completed successfully and
without error.
kDMTransactionAborted DMTransaction’s abort method was called,
halting the given transaction.
kDMTransactionHadError A non-success http status code was returned,
a network error occurred, or the expected
data was not received. To get the exact error
that occurred, call DMTransaction’s
httpStatusCode or errorType methods.
Privilege constants used for setting privileges when setting access rights on
securable .Mac entities using DMSecurity methods (privileges are inherited unless
explicitly overridden):
Privilege Constant Meaning
kDMRead Includes ‘read’ and ‘list’ access to a given
entity.
kDMWrite Includes ‘create’, ‘modify’ and ‘delete’
access to a given entity.
kDMModify Includes ‘modify’ access to a given entity.
Does not include ‘create’ or ‘delete’ access.
kDMReadChildren Includes ‘read’ and ‘list’ access to children
of a given entity only. Does not include
‘read’ and ‘list’ access to the entity itself.
The following constants are used by the DMUtilities method,

-principalPropertiesFromPrincipalID:, to to parse a principal ID string returned by a
DMPrincipal method:
Key Constant Corresponding Value
kDMPrincipalName (NSString) The name of the given principal.
kDMPrincipalOwner (NSString) The name of the .Mac member
who owns the principal--this is the same as
the principal name if the principal represents
a DMMemberAccount.
kDMPrincipalType (NSString) The type of the given principal,
which is one of the ‘Principal Type
Constants’ listed below.
6
Principal Type Constants Meaning
kDMMemberAccount Type for principal representing .Mac
member.
kDMSecondaryUser Type for principal representing a .Mac
member-owned secondary user.
kDMGroup Type for principal representing a .Mac
member-owned group.
Auto-launch constants are used for passing launch options to DMMessageSubscriber

methods that schedule applications and tools to launch when a given topic changes (these
launch options can be or’d together as appropriate):
DMAutoLaunchOptions Meaning
kDMLaunchDefault Only one instance, launch in foreground.
kDMLaunchAlways Always launch a new instance of application
(applies to bundled apps only).
kDMLaunchInBackground Don’t bring launched app to foreground
(applies to bundled apps only).
7
Using Transactions
At the heart of the DotMac Kit is the DMTransaction class, which peforms all network
operations with .Mac. All methods in the Kit that return DMTransaction objects conform
to the DMTransactionGenerator protocol, a protocol that provides control over whether
transactions are done asynchronously or synchronously (the default is always async) and
that provides a mechanism for setting a transaction delegate object that conforms to the
informal DMTransactionDelegate protocol.
DMTransaction
Tracking transactions
- (NSString *)transactionID;
Returns a globally unique identifier string for this transaction.
- (void) setContext: (id)context;

Sets an object of the caller’s choosing on the given transaction that can be used to help
identify a transaction. This method is especially useful in tracking transactions done
asynchronously. After obtaining an asynchronously-fired DMTransaction object, the
caller need not worry about the transaction completing and generating a delegate callback
8
before the context can be set--since callbacks are made on the same client thread which
launched the transaction, setting the context simply needs to be done immediately after
generating the transaction and in the same thread. That way, even if the transaction
completes immediately, the context will still be set before the completion callback is
made.
- (id)context;
Returns the context object set for this transaction. This value is nil by default.
- (NSString *)uri;
Returns the target uri sent in this transaction’s originating request.
Getting transaction status
- (BOOL)isSuccessful;
Returns YES if the transaction has finished successfully, no network errors occurred, and
a valid http status code was returned. Otherwise, returns NO.
- (BOOL)isFinished;
This method will return YES if the given transaction is no longer active, due to success,
error or cancellation. Otherwise, NO is returned.
- (int)transactionState;
Returns one of the following integer constants:
Transaction State Constant Meaning
kDMTransactionNotStarted The transaction has not yet started.
kDMTransactionActive The transaction is in progress.
kDMTransactionSuccessful The transaction completed successfully and
without error.
kDMTransactionAborted DMTransaction’s abort method was called,
halting the given transaction.
kDMTransactionHadError A non-success http status code was returned,
a network error occurred, or the expected
data was not received. To get the exact error
that occurred, call DMTransaction’s
httpStatusCode or errorType methods.
9
- (int)httpStatusCode;
Returns the HTTP status code for the request if applicable. Check RFC 2616 (HTTP/1.1)
for a complete list of all of the applicable status codes. Some of the most noteworthy
ones are:
200 – Success
304 – Not Modified
401 – Authorization required
403 – Forbidden. Your authorization credentials will not allow the transaction
attempted.
404 – Not Found
[Note: kDMUndefined will be returned if the transaction has not yet completed, if an http
status code is not applicable for the given transaction type, or if the transaction failed
before an HTTP status code could even be received, as might be the case if the client
computer could not contact the .Mac environment for some reason.]
- (int)errorType;
If an error occurred while generating the response associated with this object, this method
will return a specific error type, as defined in the “Constants” section of this document.
If an unknown error occurred, kDMUnknownError is returned. However, if no error
occurred or the response has not yet completed when this method is called,
kDMUndefined will be returned. [Note: If the http status code that was received is
considered a failure code for the given transaction, kDMUnknownError is returned – the
http status code can be retrieved using the httpStatusCode method of this class.]
- (id)result;
Returns the result object of the given transaction as defined by the type of request the
transaction is handling, if currently available and applicable. Otherwise returns nil.
- (SInt64)contentLength;
Returns the length in bytes of the content being downloaded or uploaded. This returned
length does not change over the life of the given transaction, except in the case where this
method is called immediately after a GET request is started, before the content length has
been received from the server—this method returns kDMUndefined if called too early.
- (SInt64)bytesTransferred;
Most useful for asynchronous operations, this method returns the number of bytes
downloaded or uploaded thus far.
10
Cancelling an in-flight transaction
- (void)abort;
Stops the current transaction if it is running asynchronously, halting its progress. If the
transaction is already complete (or resulted in an error) this method has no effect.
11
DMTransactionDelegate (Informal Protocol)
- (void)transactionSuccessful: (DMTransaction *)theTransaction;

This delegate method is called when a transaction successfully completes. If the
transaction does not complete successfully, then transactionHadError: is called instead.
Takes one parameter, which is a reference to the DMTransaction object that completed.
- (void)transactionHadError: (DMTransaction *)theTransaction;

This delegate method is called when a transaction encounters an error condition. If the
transaction does complete successfully, then transactionSuccessful: is called instead.
Takes one parameter, which is a reference to the DMTransaction object that experienced
the error.
- (void)transactionAborted: (DMTransaction *)theTransaction;

This delegate method is called after the DMTransaction object’s abort method is called
and stops a currently-running asynchronous transaction.
12
DMTransactionGenerator (Formal Protocol)
- (void)setTransactionDelegate: (id)delegate;
This method is used to set the delegate object which will receive status messages from
asynchronous transactions generated by the object that conforms to this protocol. The
object passed in this method's delegate parameter must conform to the informal
DMTransactionDelegate protocol. Transaction delegates receive their messages on the
run loop originally used to create the given DMTransaction. It is safe to call this method
to change the delegate as needed--since an in-flight DMTransaction object uses the
settings that were in place at the time it was created, calling this method will not affect
any transaction already in progress. A transaction delegate object does not receive
callbacks for transactions executed synchronously.
- (id)transactionDelegate;
This method is used to get the currently set delegate object that receives status messages
from asynchronous transactions generated by the object that conforms to this protocol.
- (void)setIsSynchronous: (BOOL)useSynchronous;
This method is used to set the synchronicity state for generated transactions. Passing
YES for useSynchronous will cause the object's transaction methods to block until they
have either completed their transaction or failed with an error. Passing NO will cause the
methods to that return a DMTransaction object to return immediately, using any
previously set delegate object to signal completion or error. It is safe to call this method
to switch between asynchronous and synchronous modes as needed--since an in-flight
DMTransaction object uses the settings that were in place at the time it was created,
calling this method will not affect any transaction already in progress. [Note: The default
mode is asynchronous.]
- (BOOL)isSynchronous;
This method returns the synchronicity state used for newly generated transactions. YES
is returned for synchronous or NO for asynchronous. [Note: The default mode is
asynchronous.]
13
Credentials and Account Management
Objects conforming to the DMCredential protocol, such as DMMemberAccount and
DMSecondaryUser are used to provide credentials for .Mac session classes, such as
DMiDiskSession, DMMessagePublisher and DMMessageSubscriber. Besides providing
credentials, the DMMemberAccount class offers a mechanism for obtaining account
status such as which .Mac services are available and how many days the account has left
before expiration. It also provides methods for creating member-owned secondary users
and groups. (We’ll describe later how .Mac resources can be shared by using the Kit’s
access control features to grant access to other .Mac members, secondary users or
groups.)
14
DMCredential (Formal Protocol)
- (NSString *)name;
A username string is returned.
- (NSString *)password;
A password string is returned.
- (NSString *)owner;
The name of the .Mac member who owns the credential is returned.
DMMemberAccount
(Conforms to DMCredential, DMPrincipal, DMTransactionGenerator)
Factories and Initers
+ accountWithName: (NSString *)name

password: (NSString *)password
applicationID: (NSString *)creatorCode;
Returns an initialized, auto-released instance of DMMemberAccount keyed to a specific
application’s identification string. The instance returned will use the provided name and
password, rather than any credentials stored in the .Mac preferences on the system.
(To have the credentials stored on the system pre-applied, use the
accountFromPreferencesWithApplicationID: method instead.) Pass the unique 4-
character application identifier obtained from
http://developer.apple.com/datatype/creatorcode.html.
+ accountFromPreferencesWithApplicationID:

(NSString *)creatorCode;
Returns an initialized, auto-released instance of DMMemberAccount keyed to a specific
application’s identification string. The instance returned will have the .Mac name and
password from the system pre-applied. Pass the unique 4-character application identifier
obtained from http://developer.apple.com/datatype/creatorcode.html.
- initWithName: (NSString *)name

applicationID: (NSString *)theID;
Returns an initialized instance of DMMemberAccount keyed to a specific application’s
identification string. The instance returned will use the provided name and password,
rather than any credentials stored in the .Mac preferences on the system. (To have the
credentials stored on the system pre-applied, use the
initFromPreferencesWithApplicationID: method instead.) Pass the unique application
identifying string obtained from
http://developer.apple.com/datatype/creatorcode.html
15
- initFromPreferencesWithApplicationID: (NSString *)theID;
Returns an initialized instance of DMMemberAccount keyed to a specific application’s
identification string. The instance returned will have the .Mac name and password from
the system pre-applied. Pass the unique application identifying string obtained from
http://developer.apple.com/datatype/creatorcode.html
Convenience API (Inherited from DMAccount)
- (NSString *)applicationID;
The application ID currently set for this DMMemberAccount object is returned.
- (void)setApplicationName: (NSString *)name;

This method sets the human-readable name of the calling application. Once set, it will be
included in the user-agent header sent with all http requests.
- (NSString *)applicationName;
The human-readable name of the calling application is returned if set.
Checking account credentials
- (int)validateCredentials;
Use this method to check that the given account contains valid .Mac credentials. The
returned integer will correspond to one of the “Status Constants” defined in the Constants
section of this document.
- (BOOL)matchesSystemCredentials;
Returns true if the name and password currently set for this DMMemberAccount object
match the .Mac credentials stored on the system.
Requesting account properties
- (DMTransaction *)servicesAvailableForAccount;
The returned DMTransaction object’s result method returns an NSArray of NSString
entries corresponding to available services for the .Mac account represented by this
DMMemberAccount instance. If a given .Mac service is enabled for this account, then
the array will contain a string equal to one of these NSString constants:
Service Constant Meaning
kDMiDiskService The account has iDisk storage associated
with it.
kDMEmailService The account has an email address along with
the associated email storage.
16
kDMWebHostingService The account has web hosting capabilities
through its iDisk’s Sites folder.
kDMiSyncService The account has access to .Mac’s iSync-
related functionality.
[Note: If the account credentials do not exist or some other error occurs, the returned
DMTransaction’s errorType method can be used to identify the error.]
- (DMTransaction *)daysLeftUntilExpiration;
The returned DMTransaction object’s result method returns an NSNumber representing
the number of full days left until the given account expires.
- (DMTransaction *)canUpgradeAccount;
The returned DMTransaction object’s result method returns an NSNumber, whose
Boolean value can be retrieved using NSNumber’s boolValue method. This value will be
YES if the DMMemberAccount object’s credentials are associated with an existing
account that can be upgraded, such as a trial or email-only account, or if the account has
expired and needs to be renewed. Otherwise, the resulting value will be NO.
Upgrading or signing up a .Mac member
- (void)upgradeAccount;
This method will launch the user’s default web browser and open the appropriate .Mac
membership upgrade page, which is localized based on system preferences.
- (NSURL *)accountUpgradeURL;
This method provides access to the same localized URL that the upgradeAccount method
loads in the default browser.
+ (void)signUpNewMember;
This method will launch the user’s default web browser and open the .Mac new member
sign-up page, which is localized based on system preferences. This method can be used
when the user of the given application is not yet a .Mac member and cannot fully enjoy
the application’s features without a .Mac account.
17
+ (void)signUpNewMemberWithApplicationID: (NSString *)appID;
This method performs the same function as the +signUpNewMember method, and
additionally ensures that the owner of the provided application ID (if a member of
the .Mac Affiliate Program) earns a commission whenever a user of their application
becomes a paying .Mac member. For more information on the .Mac Affiliate Program,
please visit http://www.mac.com/1/affiliates/faq.html.
+ (NSURL *)signUpURL;
This method provides access to the same localized URL that the signUpNewMember
method loads in the default browser. [Note: The URL returned by this method should not
be hard-coded within an application, as it may change in the future.]
+ (NSURL *)signUpURLWithApplicationID: (NSString *)appID;

Returns the URL for the .Mac sign-up page, with commission tracking enabled if the
owner of the provided application ID is a member of the .Mac Affiliate Program. For
more information on the .Mac Affiliate Program, please visit http://www.mac.com/1/
affiliates/faq.html.
[Note: The URL returned by this method should not be hard-coded within an application,
as it may change in the future.]
Managing secondary accounts
- (DMTransaction *)secondaryUserNames;
Lists all secondary users owned by this .Mac member. Returns a DMTransaction object
whose -isSuccessful method can be used to test for success and whose -result method
returns an NSArray of NSStrings on success.
- (DMTransaction *)createSecondaryUserWithName: (NSString *)name

andPassword: (NSString *)password;
Adds a secondary user to .Mac if a secondary user of the same name does not already
exist for this owning member account. Returns a DMTransaction object whose
-isSuccessful method can be used to test for success.
- (DMTransaction *)removeSecondaryUserNamed: (NSString *)name;

Removes the secondary user with the given name from .Mac. Returns a DMTransaction
object whose -isSuccessful method can be used to test for success.
- (DMTransaction *)resetPassword: (NSString *)password

forSecondaryUserNamed: (NSString *)name;
Resets the password of the secondary user with the given name. Returns a
DMTransaction object whose -isSuccessful method can be used to test for success.
18
Managing groups
- (DMTransaction *)groupNames;
Lists all groups owned by this .Mac member. Returns a DMTransaction object whose
-isSuccessful method can be used to test for success and whose -result method returns an
NSArray of NSString group names upon success.
- (DMGroup *)groupNamed: (NSString *)name;

Use this method to obtain a DMGroup object representing a known group that already
exists.
- (DMTransaction *)createGroupWithName: (NSString *)name

andMembers: (NSArray *)members;
This method can be used to create a new DMGroup object with the provided name and
members if a group of the same name does not already exist for the owner’s account
on .Mac. The members argument is an NSArray of principal ID strings identifying
principals corresponding to DMMemberAccounts, DMSecondaryUsers and/or DMGroup
objects. Returns a DMTransaction object whose -isSuccessful method can be used to
test for success.
- (DMTransaction *)removeGroupNamed: (NSString *)name;

Removes the DMGroup with the given name from .Mac. Returns a DMTransaction
object whose -isSuccessful method can be used to test for success.
19
DMSecondaryUser
(Conforms to DMCredential, DMPrincipal, DMTransactionGenerator)
+ (DMSecondaryUser *)secondaryUserWithName: (NSString *)name


owner: (NSString *)memberName

Returns an autoreleased instance of DMSecondaryUser keyed to a specific application’s
identification string. The secondary user is owned by the .Mac member with the given
member name. Pass the unique 4-character application identifier obtained from
- (DMSecondaryUser *)initWithName: (NSString *)name


owner: (NSString *)memberName

Returns a newly initialized DMSecondaryUser object keyed to a specific application’s
identification string. The secondary user is owned by the .Mac member with the given
member name. Pass the unique 4-character application identifier obtained from
20
DMGroup
(Conforms to DMPrincipal, DMTransactionGenerator)
A DMGroup is owned by a .Mac member and can only be created using a

DMMemberAccount object.
Convenience API
- (NSString *)name;
Returns the name of the .Mac member-owned group represented by this DMGroup
object.
Returns the name of the .Mac member who owns this group.
Managing group members
- (DMTransaction *)addMembers: (NSArray *)members;

Adds members to the given .Mac member-owned group. If the group already exists, then
the identified principals are added as members. If the group does not already exist, this
call fails. The members argument is an NSArray of principal ID strings that identify
principals corresponding to DMMemberAccounts, DMSecondaryUsers and/or other
DMGroup objects. Returns a DMTransaction object whose -isSuccessful method can be
used to test for success.
- (DMTransaction *)removeMembers: (NSArray *)members;

Removes members from the given .Mac member-owned group. The members argument
is an NSArray of principal ID strings that identify principals corresponding to
DMMemberAccounts, DMSecondaryUsers and/or other DMGroup objects. Returns a
- (DMTransaction *)members;
Lists all members of the given .Mac member-owned group. Returns a DMTransaction
object whose -isSuccessful method can be used to test for success and whose -result
method, upon success, returns an NSArray of principal ID strings that identify principals
corresponding to DMMemberAccounts, DMSecondaryUsers and/or other DMGroup
objects.
21
DMPrincipal (Formal Protocol)
The DMPrincipal protocol is implemented by DMMemberAccount, DMSecondaryUser
and DMGroup. [Note: When calling +principalIDWithName:andOwner: for a
DMMemberAccount, the name and owner strings are the same.]
+ (NSString *)principalIDWithName: (NSString *)name

andOwner: (NSString *)memberName;
Returns a principal ID string identifying the principal with the given name
and owner (the owner is the name of the .Mac member that owns the given principal).
This class method is useful when the caller needs to obtain a principle ID representing a
DMMemberAccount, DMSecondaryUser or DMGroup without creating an instance of
one of those classes.
- (NSString *)principalID;
This method is implemented by DMMemberAccount, DMSecondaryUser or DMGroup
and returns the appropriate principal ID string.
22
Security and Access Control
The DMSecurity protocol is implemented by DMiDiskSession, DMMessagePublisher
and DMMessageSubscriber and allows the owner of a .Mac resource to apply ACLs to
that resource. (Examples of how to use the DMSecurity methods for each of these
three .Mac session classes can be found within each of their respective API sections in
this document.) This section describes the DMSecurity protocol in detail, along with the
DMUtilities class, which provides assistance in parsing principal ID strings returned by
DMSecurity methods.
DMSecurity (Formal Protocol)
The DMSecurity protocol is used to get and set access privileges for securable entities
(such as DMTopics and NSStrings paths representing iDisk resources). Access is granted
to principals corresponding to DMMemberAccounts, DMSecondaryUsers and
DMGroups. [Principals are represented by principal ID’s, which can be obtained by
calling the +principalIDWithName:andOwner method on a DMMemberAccount,
DMSecondaryUser or DMGroup object. If you already have an instance of one of these
objects you can call its –principalID instance method instead.]
Reading access privileges
- (DMTransaction *)accessToEntity: (id)entity

forPrincipal: (NSString *)principalID;
Retrieves access privileges set on the specified entity for a given principal. Takes an
entity (valid entities include DMTopics and NSString paths representing iDisk resources)
and also takes a principal ID string that corresponds to a DMMemberAccount,
DMSecondaryUser or DMGroup. Returns a DMTransaction object whose -isSuccessful
method can be used to test for success and whose -result method, upon success, returns
an NSArray of privilege strings. (Valid privilege strings are defined in the ‘Constants’
23
section of this document and include kDMRead, kDMWrite, kDMModify and
kDMReadChildren.)
- (DMTransaction *)accessToEntity: (id)entity

forPrincipals: (NSArray *)principalIDs;
Retrieves access privileges set on the specified entity for a list of principals (valid entities
include DMTopics and NSString paths representing iDisk resources). Returns a
DMTransaction object whose -isSuccessful method can be used to test for success and
whose -result method, upon success, returns an NSDictionary, where each key in the
dictionary is a principal ID string corresponding to an NSArray value that contains a set
of privilege strings for the given principal. (Valid privilege strings are defined in the
‘Constants’ section of this document and include kDMRead, kDMWrite, kDMModify
and kDMReadChildren.)
Setting access privileges
- (DMTransaction *)setAccess: (NSArray *)access

toEntity: (id)entity

forPrincipals: (NSArray *)principals;
Sets access privileges on the specified entity for the identified principal(s). The access
argument is an NSArray of privilege strings. (Valid privilege strings are defined in the
‘Constants’ section of this document and include kDMRead, kDMWrite, kDMModify
and kDMReadChildren.) Any privilege not included in the access array will be denied.
When the specified entity has children (such as a directory on iDisk) any direct or indirect
child will inherit the given privileges unless different access is explicitly set on that child.
If the access privileges array is nil, this method will remove all access for the given
principals. The entity argument is either a DMTopic object or an NSString path
representing an iDisk resource. The principals argument is an NSArray of principal ID
strings that identify the unique principals corresponding to DMMemberAccounts,
DMSecondaryUsers and/or DMGroups. Returns a DMTransaction object whose -
isSuccessful method can be used to test for success.
Resetting access to an entity’s children
- (DMTransaction *)resetAccessToChildrenOfEntity: (id)entity;

This method removes access privileges explicitly set on the children of the specified
entity. Returns a DMTransaction object whose -isSuccessful method can be used to test
for success.
24
DMUtilities
- (NSDictionary *)principalPropertiesFromPrincipalID:

(NSString *)principalID;
This utility method is used to parse a principal ID string returned by a DMPrincipal
method. This method returns a dictionary with values for the following keys:
kDMPrincipalName, kDMPrincipalOwner and kDMPrincipalType. The
kDMPrincipalOwner key corresponds to the name of the .Mac member who owns the
given principal (this is the same as the principal name if the principal represents a
DMMemberAccount) and the kDMPrincipalType key corresponds to one of the
following: kDMMemberAccount, kDMSecondaryUser or kDMGroup. (These constants
are defined in the “Constants” section of this document.)
25
Transferring Data with iDisk
At the core of the DotMac Kit is an implementation of an open standards-based
WebDAV client (RFC #2518). This allows DMiDiskSession objects to directly interact
with the .Mac iDisk service, which is also based on WebDAV.
Built on top of the DMiDiskSession class, which includes everything a user of this
framework needs to manipulate data on an iDisk, is a convenience category called
DMiDiskFileManager, which has an API and functionality representing a subset of that of
NSFileManager. DMiDiskFileManager is a wrapper around DMiDiskSession’s
WebDAV-based calls, and facilitates synchronous iDisk access through an API which will
be familiar to many developers. However, direct use of DMiDiskSession is the
recommended mode of communication with the iDisk, since it is more efficient, allows
asynchronous calls, and will be the class which gets updated in future framework releases
as enhanced WebDAV-based functionality is added. [Note: DMiDiskSession objects are
in asynchronous mode by default.]
Supported iDisk operations include:
Asynchronous and Synchronous Data Retrieval:

GET – Downloads the entire specified object.
GET If Modified Since – Downloads the entire specified object, but only if it has a
modification date more recent than the date supplied.
GET Range – Downloads only the specified range of an object.
GET Range If Modified Since – Downloads the specified range of an object if it has a
modification date more recent than the date supplied.
Asynchronous and Synchronous Data Upload:

PUT – Uploads the entire specified object.
PUT Range – Uploads the supplied data replacing the specified range within an existing
object.
Asynchronous and Synchronous File Maintenance & General:

LOCK – Locks a specified object on the iDisk server so that only this client can write to
the object.
RELOCK – Renews a previously acquired lock.
UNLOCK – Releases a previously acquired lock.
PROPFIND (Collection) – Returns the contents of the given collection (directory).
PROPFIND (File) – Returns the properties of a specific file.
MKCOL – Creates a directory at the specified location on the iDisk server.
MOVE – Moves a file or directory to a specified location on the iDisk server.
COPY – Creates a copy of a file or directory at a specified location on the iDisk server.
DELETE – Deletes a file or directory at the specified location on the iDisk server.
[Note: Unlike file system delete operations, iDisk delete operations will successfully
delete directories that contain files.]
26
DMiDiskSession
(Conforms to DMSecurity, DMTransactionGenerator)
DMiDiskSession is a thread-safe class which facilitates interactions with iDisk.
Please note: All server-side paths passed as arguments to DMiDiskSession methods

should start with a forward slash, omitting the iDisk account name at the beginning of
the path—for example, if uploading a local file to a user’s Public folder, the second
path passed to the putLocalFileAtPath:toPath: method would be of the format “/Public/
<filename>”.
Factories and initers
+ iDiskSessionWithCredentials: (id <DMCredential>)credentials;

This method returns an auto-released iDisk session instance that can be used to perform
I/O transactions with the .Mac iDisk servers. It takes an object that conforms to the
DMCredential protocol--the returned session will be used to access the iDisk owned by
the .Mac member with the given credentials.
27
+ iDiskSessionWithCredentials: (id <DMCredential>)credentials

DMCredential protocol and also takes the name of the .Mac member whose iDisk is to be
accessed using the provided credentials.
- initWithCredentials: (id <DMCredential>)credentials;

This method will return an iDisk session instance that can be used to perform I/O
transactions with the .Mac iDisk servers. It takes an object that conforms to the
DMCredential protocol--the returned session will be used to access the iDisk owned by
the .Mac member with the given credentials.
- initWithCredentials: (id <DMCredential>)credentials

DMCredential protocol and also takes the name of the .Mac member whose iDisk is to be
accessed using the provided credentials.
Convenience API
- (id <DMCredential>)credentials;
Returns the DMCredential-conforming object containing the credentials used to access
this session’s iDisk.
Returns the name of the .Mac member who owns the iDisk being accessed by this
session.
Getting the storage quota
- (DMTransaction *)quotaAttributes;
Use this method to get the user’s iDisk quota value along with the amount of storage
space that is currently used. The returned DMTransaction object’s result method returns
an NSDictionary containing two NSNumber values, which can be retrieved using the
following key constants:
kDMiDiskQuotaInBytes NSNumber (bytes)
kDMiDiskSpaceUsedInBytes NSNumber (bytes)
28
Downloading data
- (DMTransaction *)getDataAtPath: (NSString *)sourcePath;

If the transaction is successful, the returned DMTransaction object’s result method
returns a NSData object containing the desired resource (this NSData object is memory-
mapped from a file in /tmp, allowing an application to download a large amount of data
without bringing it into real memory until it is actually needed—clean-up of the
temporary file happens automatically). [Note: If the transaction is not yet complete, the
result method will return the data that has been downloaded so far.]
The returned DMTransaction object can be used to get the result of the transaction, status,
payload, and many other pieces of information about the actual transaction.
- (DMTransaction *)getDataAtPath: (NSString *)sourcePath

ifModifiedSince: (NSDate *)lastModifiedDate;

returns a memory-mapped NSData object containing the desired resource (this NSData
object is memory-mapped from a file in /tmp, allowing an application to download a
large amount of data without bringing it into real memory until it is actually needed —
clean-up of the temporary file happens automatically). [Note: If the transaction is
asynchronous and is not yet complete, the result method will return the data that has been
downloaded so far.]
- (DMTransaction *)getDataAtPath: (NSString *)sourcePath

ifModifiedSince: (NSDate *)lastModifiedDate
withByteRange: (NSRange)byteRange;
returns a memory-mapped NSData object containing the desired resource (this NSData
object is memory-mapped from a file in /tmp, allowing an application to download a
large amount of data without bringing it into real memory until it is actually needed —
clean-up of the temporary file happens automatically). The NSRange object, passed as
the byteRange argument, should have its location set as the index of the first byte to be
retrieved and its length should be set as the total number of bytes to be retrieved,
including the first byte. You can also pass nil for lastModifiedDate if you are not
interested in when the server resource was last modified.
[Note: If the transaction is asynchronous and is not yet complete, the result method will
return the data that has been downloaded so far.]
29
Uploading data
- (DMTransaction *)putData: (NSData *)data

toPath: (NSString *)destinationPath;
This method places the contents of the data argument into the resource at the location
specified by the destination path. [Note: Call will fail if any sublevels of destinationPath
(excluding the object itself) do not exist, and the call may return nil if an invalid data
argument is passed.]
Returns a DMTransaction object that can be used to get the result of the transaction,
status, payload, and many other pieces of information about the actual transaction.
- (DMTransaction *)putData: (NSData *)data

toPath: (NSString *)destinationPath
withByteRange: (NSRange)byteRange;
This method places the contents of the data argument into the resource at the location
specified by the byteRange argument. The NSRange object, passed as the byteRange
argument, should have its location set as the index of the first byte to be written to and its
length should be set as the total number of bytes, including the first byte. If the end of the
specified range is beyond the end of the file, then the length of the resource is extended to
accommodate all of the bytes. [Note: Call will fail if any sublevels of destinationPath
(excluding the object itself) do not exist, and the call may return nil if an invalid data
argument is passed.]

- (DMTransaction *)putLocalFileAtPath: (NSString *)localPath
This method places the contents of a local file into a new server-side file at the given
destination path. If the localPath parameter refers to a symlink, the symlink will not be
preserved—rather, the resource it references will be uploaded. [Note: Call will fail if all
sublevels of destinationPath (excluding the object itself) do not already exist, and the call
may return nil if an invalid localPath argument is passed.]
status, payload, and many other pieces of information about the actual
transaction.
Creating collections (directories)
- (DMTransaction *)makeCollectionAtPath: (NSString *)thePath;

This method creates a collection (directory) at the location specified in thePath. If any of
the levels above the one being created does not exist, then the create will fail.
30
Moving and Copying resources
- (DMTransaction *)moveResourceAtPath: (NSString *)sourcePath

Moves the resource identified by sourcePath if it is not locked by another client and the
account who owns the credentials used has write access to destinationPath. This method
will overwrite the resource at destinationPath if that resource is not locked by another
client.
- (DMTransaction *)copyResourceAtPath: (NSString *)sourcePath

Copies the resource identified by sourcePath if the account who owns the credentials used
has write access to destinationPath. This method will overwrite the resource at
destinationPath if that resource is not locked by another client.
Deleting resources
- (DMTransaction *)deleteResourceAtPath: (NSString *)thePath;

Deletes the resource referenced by thePath if it is not locked by another client and the
account who owns the credentials used has write access to thePath. If the delete request
fails because the specified resource or its parent is locked, the returned DMTransaction
object’s result method will return an NSArray of NSString’s representing the exact uri’s
which are currently locked.
[Note: Unlike on most file systems, a non-empty collection (directory) can be deleted.
Issuing a delete targeted at a collection will delete the collection and all of it contents
without warning (assuming you have the correct access privileges).]
Locking resources
- (DMTransaction *)lockResourceAtPath: (NSString *)thePath;

Locks the resource referenced by thePath so that only this session can execute write
operations (e.g., PUT, DELETE) on that resource. The iDisk server reserves the right to
grant a lock duration/timeout that differs from the requested lock duration—when this
method is successful, the returned DMTransaction object’s result method will return an
NSDictionary containing an NSNumber value (accessible using the kDMLockTimeout
key) which is the lock timeout that was granted by the server. The lock will expire after
the time specified by the granted lock timeout (in seconds) has passed. If the lock request
fails because the specified resource or its parent is already locked, the returned
31
DMTransaction object’s result method will return an NSArray of NSString’s representing
the exact uri’s which are currently locked. To maintain a lock, issue a relock request on
the same resource before the original lock has expired. [Note: The lock created is a
cooperative, ‘write’ lock.]
- (DMTransaction *)lockResourceAtPath: (NSString *)thePath

withDuration: (NSTimeInterval)lockDuration;
Locks the resource referenced by thePath so that only this session can execute write
operations (e.g., PUT, DELETE) on that resource. The iDisk server reserves the right to
grant a lock duration/timeout that differs from the requested lock duration—when this
method is successful, the returned DMTransaction object’s result method will return an
NSDictionary containing an NSNumber value (accessible using the kDMLockTimeout
key) which is the lock timeout that was granted by the server. The lock will expire after
the time specified by the granted lock timeout (in seconds) has passed. If the lock request
fails because the specified resource or its parent is already locked, the returned
DMTransaction object’s result method will return an NSArray of NSString’s representing
the exact uri’s which are currently locked. To maintain a lock, issue a relock request on
the same resource before the original lock has expired. [Note: The lock created is a
- (DMTransaction *)relockResourceAtPath: (NSString *)thePath;

Refreshes the lock on the resource referenced by thePath. The iDisk server reserves the
right to grant a lock duration/timeout that differs from the requested lock duration—when
this method is successful, the returned DMTransaction object’s result method will return
an NSDictionary containing an NSNumber value (accessible using the kDMLockTimeout
key) which is the lock timeout that was granted by the server. Once refreshed, the lock
will expire after the time specified by the granted lock timeout (in seconds) has passed.
Attempting to relock a resource that is not locked will always fail. If the relock request
fails because the specified resource or its parent was originally locked by another client,
the returned DMTransaction object’s result method will return an NSArray of NSString’s
representing the exact uri’s which are currently locked. [Note: The lock created is a
- (DMTransaction *)relockResourceAtPath: (NSString *)thePath

withDuration: (NSTimeInterval)lockDuration;
Refreshes the lock on the resource referenced by thePath. The iDisk server reserves the
right to grant a lock duration/timeout that differs from the requested lock duration—when
this method is successful, the returned DMTransaction object’s result method will return
32
an NSDictionary containing an NSNumber value (accessible using the kDMLockTimeout
key) which is the lock timeout that was granted by the server. Once refreshed, the lock
will expire after the time specified by the granted lock timeout (in seconds) has passed.
Attempting to relock a resource that is not locked will always fail. If the relock request
fails because the specified resource or its parent was originally locked by another client,
the returned DMTransaction object’s result method will return an NSArray of NSString’s
representing the exact uri’s which are currently locked. [Note: The lock created is a
- (DMTransaction *)unlockResourceAtPath: (NSString *)thePath;

Releases any lock on the resource referenced by thePath. Attempting to unlock a
resource that is not locked will fail.
- (void)setDefaultLockDuration: (NSTimeInterval)lockDuration;
This method sets the default lock duration, in seconds, used by all lock-related
DMiDiskSession methods that do not specify a transaction-specific lock duration of their
own. If this method is not called, the default lock duration is 5 minutes, given in seconds.
- (NSTimeInterval)defaultLockDuration;
Returns the default lock duration set for this DMiDiskSession instance. If no default lock
duration has been set for this instance using the setDefaultLockDuration: method, an
NSTimeInterval representing 5 minutes, given in seconds, is returned.
Getting info about objects and collections
- (BOOL)resourceExistsAtPath: (NSString *)thePath;

A method which always operates synchronously, resourceExistsAtPath: returns YES if the
resource specified by thePath exists on the iDisk server, and returns NO otherwise. [Note:
To check for the existence of a resource asynchronously, use the basicAttributesAtPath:
method.]
- (DMTransaction *)basicAttributesAtPath: (NSString *)thePath;

Performs a lightweight access against a single file or collection (directory) resource
referenced by thePath. Use this method when only basic information such as the last
modified date or content length is needed, as it is lighter weight than an
extendedAttributesAtPath: call. If a resource exists at thePath and the transaction is
successful, the returned DMTransaction object’s result method returns an NSDictionary.
That NSDictionary contains resource attributes whose values, if present and applicable,
can be retrieved using the following NSString key constants:
33
Key Corresponding Value Type
[Note: kDMContentLength is not returned for collections.]

- (DMTransaction *)extendedAttributesAtPath: (NSString*)thePath;

This method provides the attributes of the file or collection (directory) resource specified
by thePath. If a resource exists at thePath and the request is successful, the returned
DMTransaction object’s result method returns an NSDictionary. That NSDictionary
contains resource attributes whose values, if present and applicable, can be retrieved
using the following NSString key constants:
Key Corresponding Value Type
kDMURI NSString
kDMDisplayName NSString
kDMContentType NSString
kDMIsCollection NSNumber (Boolean)
kDMIsLocked NSNumber (Boolean)
kDMLockOwner NSString
kDMLockToken NSString
kDMLockTimeout NSNumber (seconds)
[Note: kDMContentLength is not returned for collections.]

- (DMTransaction *)listCollectionAtPath: (NSString *)thePath;

This method retrieves the contents of a collection (directory) on the server.
DMiDiskSession will issue a WebDAV PROPFIND with a depth of 1 against the target
path. The collection contents retrieved by this method are shallow and therefore do not
include the contents of any subdirectories. If the request is successful, the returned
DMTransaction object’s result method returns an NSArray of NSDictionaries. Each
dictionary contained in that array has the same format as the resource attribute dictionary
that is retrieved after calling DMiDiskSession’s extendedAttributesAtPath: method.
34
DMiDiskFileManager (Category of DMiDiskSession)
Please note: All server-side paths passed as arguments to DMiDiskFileManager

category methods should start with a forward slash, omitting the iDisk account name at
the beginning of the path—for example, if uploading a local file to a user’s Public
folder, the path passed to the createFileAtPath:contents:attributes: method would be of
the format “/Public/<filename>”.
- (BOOL)createDirectoryAtPath:(NSString *)path
attributes:(NSDictionary *);
This method will create a new directory at the given remote path. It has the same usage
as the corresponding method of NSFileManager. However, it does not support the setting
of attributes and if a non-nil attributes argument is passed to this method, it will be
ignored.
- (BOOL)createFileAtPath:(NSString *)path

contents:(NSData *)contents
attributes:(NSDictionary *)attributes;
This method creates a remote file at path that contains contents, behavior which matches
the style of the corresponding method of NSFileManager. However, it does not support
the setting of attributes and if a non-nil attributes argument is passed to this method, it
will be ignored.
- (BOOL)copyPath:(NSString *)source

toPath:(NSString *)destination
handler:(id)handler;
This method will create a copy of the source resource at the given destination path, but
will not overwrite an existing resource. Each path argument can be either a local or a
remote path—passing a local source path and remote destination path leads to an upload
of a local resource, while passing a remote source path and local destination path leads to
a download of a remote resource. If two remote paths are provided as arguments, this
method issues a single, server-side COPY request. This method has usage similar to that
of the corresponding method of NSFileManager. However, it does not support the usage
of a callback handler and if a non-nil handler argument is passed to this method, it will be
ignored. In the case of an upload or download, only the data forks of files and directories
are copied. In the case of an upload, local symlinks are not preserved—when a symlink
is encountered, the resource it references will be uploaded. [Note: If two local paths are
provided as arguments, this method calls NSFileManager’s copyPath:toPath:handler:
method with whatever handler argument was provided.]
35
- (BOOL)movePath:(NSString *)source

toPath:(NSString *)destination
handler:(id)handler;
This method will move the source resource to the given destination path, but will not
overwrite an existing resource. Each path argument can be either a local or a remote
path—passing a local source path and remote destination path leads to an upload of a
local resource, while passing a remote source path and local destination path leads to a
download of a remote resource. If two remote paths are provided as arguments, this
method issues a single, server-side MOVE request. This method has usage similar to that
of the corresponding method of NSFileManager. However, it does not support the usage
of a callback handler and if a non-nil handler argument is passed to this method, it will be
ignored. In the case of an upload or download, only the data forks of files and directories
are moved. In the case of an upload, local symlinks are not preserved—when a symlink
is encountered, the resource it references will be uploaded. [Note: If two local paths are
provided as arguments, this method calls NSFileManager’s movePath:toPath:handler:
method with whatever handler argument was provided.]

- (BOOL)removeFileAtPath:(NSString *)path handler:(id)handler;
This method will remove the resource at the given remote path and has the same usage as
the corresponding method of NSFileManager. However, it does not support the usage of
a callback handler and if a non-nil handler argument is passed to this method, it will be
ignored.

- (NSData *)contentsAtPath:(NSString *)path;

Returns the contents of the remote file specified in path as an NSData object. If path
specifies a directory, or if some other error occurs, this method returns nil.
[Note: Only the data fork of the given file is returned.]
- (BOOL)fileExistsAtPath:(NSString *)path;
Returns YES if the remote file specified in path exists, or NO if it does not.
- (BOOL)fileExistsAtPath:(NSString *)path isDirectory:(BOOL *)

isDirectory;
Returns whether the remote file specified in path exists. If you want to determine if path
is a directory, specify the address of a Boolean variable for isDirectory, which will be set
to YES if path is a directory, and to NO otherwise.
- (NSArray *)directoryContentsAtPath:(NSString *)path;

Searches the contents of the remote directory specified by path and returns an array of
strings identifying the directories and files (including symbolic links) contained in path.
The search is shallow and therefore does not return the contents of any subdirectories.
Returns nil if the directory specified at path does not exist or there is some other error
accessing it. Returns an empty array if the directory exists but has no contents.
36
Using DMSecurity on DMiDiskSession
Examples of setting access rights on iDisk resources:
1) Grant read/modify access to a shared file for a secondary user:
NSArray *accessRights = [NSArray arrayWithObjects: kDMRead, kDMModify, nil];

NSString *principalID = [DMSecondaryUser principalIDWithName:@”chris”
andOwner:@”scott”];
DMTransaction *trans = [myiDiskSession setAccess:accessRights
toEntity:@”/Documents/Group Project/To-Do.txt”
forPrincipals:[NSArray arrayWithObject:principalID]];

2) Turn a folder on iDisk into a drop box:
DMTransaction *trans = [myiDiskSession setAccess: [NSArray arrayWithObject:kDMModify]

toEntity:@”/Documents/Homework Assignments”
forPrincipals:principalIDs];
3) Grant read access to a shared folder such that any resource it contains can be
accessed, but the contents of the folder cannot be listed:
NSArray *accessRights = [NSArray arrayWithObject: kDMReadChildren];
DMTransaction *trans = [myiDiskSession setAccess:accessRights

toEntity:@”/Documents/Calendars”
forPrincipals:principalIDs];
37
Using Store-and-forward Messaging
38
DMMessagePublisher
The DMMessagePublisher session object is used to publish DMMessages to DMTopics

and is thread-safe. The .Mac member credential held by the DMMessagePublisher
session represents the member who will be publishing messages to topics. The
publishing member can publish messages to topics that it itself owns or to topics owned
by other .Mac members. The DMMessagePublisher session conforms to the DMSecurity
protocol and DMTopics are considered securable ‘entities’ that can be passed to
DMSecurity methods for this session. [Note: Only .Mac members can publish or
subscribe to messages. Currently, secondary users cannot.]
+ messagePublisherWithCredentials:(DMMemberAccount *)credentials;
Returns a new, autoreleased DMMessagePublisher session that will use the provided
object’s credentials when publishing DMMessages or otherwise accessing or modifying
DMTopics. The publishing member can publish messages to topics that it itself owns or
to topics owned by other .Mac members.
- initMessagePublisherWithCredentials:

(DMMemberAccount *)credentials;
Returns a newly initialized DMMessagePublisher session that will use the provided
object’s credentials when publishing DMMessages or otherwise accessing or modifying
DMTopics. The publishing member can publish messages to topics that it itself owns or
to topics owned by other .Mac members.
Convenience API
- (DMMemberAccount *)credentials;
Returns the .Mac member object containing the credentials set for this
DMMessagePublisher session. These credentials are used to determine which topics can
have messages published to them or be otherwise modified using this session.
Creating and Removing topics
- (DMTransaction *)createTopicNamed: (NSString *)name;

Adds a new, empty DMTopic to .Mac. The new topic will be owned by the .Mac member
specified by this DMMessagePublisher’s credentials. Returns a DMTransaction object
whose -isSuccessful method can be used to test for success.
- (DMTransaction *)removeTopicNamed: (NSString *)name;

Removes the named DMTopic from .Mac, including all of the messages it contains. A
topic can be removed only by its owner, using the same application that originally created
39
it. Therefore, the .Mac member name specified by this DMMessagePublisher’s
credentials must be the owner of the topic and the calling application must be the same
application used to originally create the topic. Returns a DMTransaction object whose
-isSuccessful method can be used to test for success.
Working with existing topics
- (DMTopic *)topicNamed: (NSString *)name;

Returns an autoreleased DMTopic instance with the provided name. The returned topic's
owner will be the .Mac member name specified by this DMMessagePublisher’s
credentials and the topic’s application ID will be set to the calling application’s creator
code. This method is used to obtain a DMTopic object that represents an existing topic
on .Mac. The credentials set for this DMMessagePublisher instance will be used to
access or modify the topic represented by the returned DMTopic object. To publish
messages to a topic or to list the messages in a topic, a DMTopic object is required. If
you are trying to obtain a DMTopic object that represents a topic not owned by this
DMMessagePublisher's credentials, use either the -topicNamed:andOwnedBy: method or
the –topicNamed:andOwnedBy:withApplicationID: method, as described below.
- (DMTopic *)topicNamed: (NSString *)name

andOwnedBy: (NSString *)memberName;
Returns an autoreleased DMTopic instance with the provided name and owner, where the
owner is the name of the .Mac member who hosts the given topic. The returned topic's
application ID will be set to the calling application’s creator code. This method is used to
obtain a DMTopic object that represents an existing topic on .Mac. The credentials set
for this DMMessagePublisher instance will be used to access or modify the topic
represented by the returned DMTopic object. To publish messages to a topic or to list the
messages in a topic, a DMTopic object is required. If you are trying to obtain a DMTopic
object that represents a topic that was created by an application different from the calling
application, use the -topicNamed:andOwnedBy:withApplicationID: method, as described
below.

andOwnedBy: (NSString *)memberName

withApplicationID: (NSString *)creatorCode;
Returns an autoreleased DMTopic instance with the provided name, owner and
application ID, where the owner is the name of the .Mac member who hosts the given
topic and the application ID is the creator code of the application that originally created
the topic. This method is used to obtain a DMTopic object that represents an existing
topic on .Mac. The credentials set for this DMMessagePublisher instance will be used to
access or modify the topic represented by the returned DMTopic object. To publish
messages to a topic or to list the messages in a topic, a DMTopic object is required.
40
- (DMTransaction *)topics;
Lists the topics that this DMMessagePublisher can publish messages to or remove
messages from. Each topic listed may be owned by this session's .Mac member
credentials or by another .Mac member. Returns a DMTransaction object whose
-isSuccessful method can be used to test for success and whose -result method, upon
success, returns an NSArray of all accessible DMTopic objects.
Publishing a message to a topic
- (DMTransaction *)publishMessage: (DMMessage *)message

toTopic: (DMTopic *)topic;
Publishes a new DMMessage to a DMTopic that already exists on .Mac (an existing topic
will have been previously created on .Mac by the topic’s owner using
DMMessagePublisher’s -createTopicNamed: method). The default time-to-live for a
newly published DMMessage is 7 days. This default can be overridden using the
session’s -setDefaultTimeToLive: method. Time-to-live can also be set on a message-by-
message basis using DMMessage’s -setTimeToLive: method. This method returns a
[Note: If .Mac is too busy to handle the message publication request, kDMServiceBusy
will be returned by the transaction’s -errorType method, and publication should be retried
later. If the given DMMessage has already been published to .Mac, kDMResourceExists
will be returned by the transaction’s -errorType method.]
Time-to-live defaults for newly published messages
- (NSTimeInterval)defaultTimeToLive;
Returns the default time-to-live that will be used by all DMMessages published by this
session. The default time-to-live value is 7 days. Returns an NSTimeInterval (precision
in seconds).
- (int)setDefaultTimeToLive: (NSTimeInterval)defaultTTL;
Sets the default time-to-live that will be used by all DMMessages published by this
session. The default time-to-live value cannot exceed 30 days. Takes an NSTimeInterval
(precision in seconds). If the provided ttl value not in the valid range,
kDMInvalidParameter will be returned; otherwise, this method returns kDMSuccess.
41
Using DMSecurity on DMMessagePublisher:
Grant another .Mac member read/write access to a DMTopic:
NSArray *accessRights = [NSArray arrayWithObjects: kDMRead, kDMWrite, nil];
//Note: For a DMMemberAccount, the name and owner are the same.
NSString *principalID = [DMMemberAccount principalIDWithName:@”george”
andOwner:@”george”];
DMTransaction *trans = [myMessagePublisher setAccess:accessRights
toEntity:myTopic
forPrincipals:[NSArray arrayWithObject:principalID]];

When a .Mac member is granted access to a topic, an invitation to that member is
automatically generated, which can be retrieved using DMMessageSubscriber’s
invitation-related methods. [Note: If only ‘read’ access is granted on a DMTopic, it
means that the invitee will not be able to publish messages to the topic, only receive
them.]
42
DMMessageSubscriber
The thread-safe DMMessageSubscriber session object is used to subscribe to specific

topics and to access new messages in topics of interest. The .Mac credentials held by the
DMMessageSubscriber session represent the subscriber. The subscriber can subscribe to
topics that it itself owns and to accessible topics owned by other .Mac members. [Note:
Only .Mac members can publish or subscribe to messages. Currently, secondary users
cannot.]
+ messageSubscriberWithCredentials:

Returns a new, autoreleased DMMessageSubscriber session that will use the provided
object’s credentials when subscribing to DMTopics or accessing a DMTopic’s messages.
The provided .Mac member credentials can be used to subscribe to accessible topics
owned by any .Mac member.
- initMessageSubscriberWithCredentials:

Returns a newly initialized DMMessageSubscriber session that will use the provided
object’s credentials when subscribing to DMTopics or accessing a DMTopic’s messages.
The provided .Mac member credentials can be used to subscribe to accessible topics
owned by any .Mac member.
Convenience API
Returns the .Mac member object containing the credentials set for this
DMMessagePublisher session. These credentials are used to determine which topics can
be subscribed to using this session.
Working with existing topics
- (DMTopic *)topicNamed: (NSString *)name;

Returns an autoreleased DMTopic instance with the provided name. The returned topic's
owner will be the .Mac member name specified by this DMMessageSubscriber’s
credentials and the topic’s application ID will be set to the calling application’s creator
code. This method is used to obtain a DMTopic object that represents an existing topic
on .Mac. The credentials set for this DMMessageSubscriber instance will be used to
access the topic represented by the returned DMTopic object. To access messages in a
topic, a DMTopic object is required. If you are trying to obtain a DMTopic object that
43
represents a topic not owned by this DMMessageSubscriber's credentials, use either the
-topicNamed:andOwnedBy: method or the
-topicNamed:andOwnedBy:withApplicationID: method, as described below.

andOwnedBy: (NSString *)memberName;
Returns an autoreleased DMTopic instance with the provided name and owner, where the
owner is the name of the .Mac member who hosts the given topic. The returned topic's
application ID will be set to the calling application’s creator code. This method is used to
obtain a DMTopic object that represents an existing topic on .Mac. The credentials set
for this DMMessageSubscriber instance will be used to access the topic represented by
the returned DMTopic object. To access messages in a topic, a DMTopic object is
required. If you are trying to obtain a DMTopic object that represents a topic that was
created by an application different from the calling application, use the
-topicNamed:andOwnedBy:withApplicationID: method, as described below.

andOwnedBy: (NSString *)memberName

withApplicationID: (NSString *)creatorCode;
Returns an autoreleased DMTopic instance with the provided name, owner and
application ID, where the owner is the name of the .Mac member who hosts the given
topic and the application ID is the creator code of the application that originally created
the given topic. This method is used to obtain a DMTopic object that represents an
existing topic on .Mac. The credentials set for this DMMessageSubscriber instance will
be used to access the topic represented by the returned DMTopic object. To access
messages in a topic, a DMTopic object is required.
Managing subscriptions to topics
- (DMTransaction *)subscribeToTopic: (DMTopic *)topic;

Creates a persistent subscription to the given topic. This subscription is specific to this
session's .Mac member credentials, the machine and local OS X user that the calling
application is running under and the calling application itself. As an argument, this
method takes a DMTopic to which this session's .Mac member credentials have access.
Calling this method creates an entry for the given subscription in the local user
preferences, which will cause the subscription to be reactivated every time the calling
application runs and creates a DMMessageSubscriber object. Therefore,
-subscribeToTopic: only needs to be called once for a given topic by an application.
Calling -unsubscribeFromTopic: removes the persistent subscription from the
preferences. This method returns a DMTransaction object whose -isSuccessful method
can be used to test for success.
44
- (DMTransaction *)unsubscribeFromTopic: (DMTopic *)topic;
Removes an existing subscription to the given topic. Removes a subscription specific to
the .Mac member for this session, the machine and local OS X user that the calling
application is running under and the calling application itself. Calling this method deletes
the entry for the given subscription from the local user preferences. As an argument, this
method takes a DMTopic object to which this session's .Mac member credentials have
access. Returns a DMTransaction object whose -isSuccessful method can be used to test
for success.
- (NSArray *)subscribedTopics;
Lists the topics to which this session's .Mac member has subscribed (where the
subscription was originally started on this machine for the current OS X user and
the .Mac member credentials set for this session). Each topic listed may be owned by
any .Mac member. Returns an NSArray of all DMTopic objects for which subscriptions
exist.
Setting the subscription delegate
- (void)setSubscriptionDelegate: (id)delegate;
Sets the delegate object for this session that will receive callbacks regarding topics of
interest. The callbacks relate either to changes to subscribed topics or to new topic
invitations sent by other .Mac members. The object passed in this method's delegate
parameter must conform to the informal DMSubscriptionDelegate protocol. Delegates
receive their messages on the same run loop originally used in calling this –
setSubscriptionDelegate: method.
- (id)subscriptionDelegate;
Retrieves the delegate object for this session that is set to receive callbacks regarding
topics of interest. The callbacks relate either to changes to subscribed topics or to new
topic invitations sent by other .Mac members. Returns a delegate object conforming to
the informal DMSubscriptionDelegate protocol if a subscription delegate has been set for
this session.
45
Launching apps when a topic changes
The following methods allow an application or tool to be launched automatically when

topics of interest change. A launched application can find out what new messages are
available for the changed topics by setting up its own DMMessageSubscriber session.
The changes that caused the application to be launched will trigger an appropriate
callback on any subscription delegate that the launched application creates at startup.
[Note: The following methods related to registering an app for launching can only be
used when the credentials set for this DMMessageSubscriber session are the same as
those credentials found in the .Mac System Preferences panel.]
- (void)addLaunchableAppForTopics: (NSArray *)topics

withBundleIdentifier: (NSString *)bundleID

arguments: (NSString *)args

options: (DMAutoLaunchOptions)options;
This method egisters a bundled application that will be launched when any of the
specified DMTopics change (the topics parameter is an NSArray of DMTopics). You can
have a single application that launches on changes of multiple topics. The specified
bundle identifier will be used to resolve the application's path for launching—if the
bundle identifier is nil, the calling application’s bundle identifier will be used. You can
specify launch arguments in the args parameter that will be passed in unchanged to the
application when it is launched. Possible values for the options parameter are described
in the “Constants” section of this document.
- (void)addLaunchableToolForTopics: (NSArray *)topics

withPath: (NSString *)fullPath

arguments: (NSString *)args

options: (DMAutoLaunchOptions)options;
This method registers a tool that will be launched when any of the given DMTopics
change (the topics parameter is an NSArray of DMTopics). You can have a single tool
that launches on changes of multiple topics. The path parameter is a fully-qualified path
to the tool. You can specify launch arguments in the args parameter that will be passed in
unchanged to the tool when it is launched. Possible values for the options parameter are
described in the “Constants” section of this document.
- (void)removeLaunchableAppForTopics: (NSArray *)topics

withBundleIdentifier: (NSString *)bundleID;
This method removes the identified launchable application for the specified topic(s). The
topics argument is an NSArray of DMTopic objects for which the given app should no
longer be launched. The bundle identifier argument is the identifier of the application that
was previously added for the given topics—if the bundle identifier is nil, the calling
application’s bundle identifier will be used.
46
- (void)removeLaunchableToolForTopics: (NSArray *)topics

withPath: (NSString *)fullPath;
Removes the launchable tool for the specified topic(s). The topics argument is an
NSArray of DMTopic objects for which the given tool should no longer be launched.
The path argument is a fully-qualified path to the tool that was previously added for the
given topics.
- (void)removeLaunchablesForTopics: (NSArray *)topics;

Removes all launchable applications and tools for the specified topic(s). Takes an
NSArray of DMTopic objects for which all applications and tools should no longer be
launched.
Handling topic invitations
- (DMTransaction *)invitationsForTopics;
Lists all unsubscribed DMTopics owned by other .Mac members to which the .Mac
member for this session has been invited to subscribe. Returns a DMTransaction object
whose -isSuccessful method can be used to test for success and whose -result method,
upon success, returns an NSArray of DMTopic objects. To be notified upon receipt of
new invitations immediately, register a subscription delegate that implements the -
invitationsReceivedForTopics: method.
[Note: An invitation for a topic is automatically sent to a .Mac member when that
member is granted access to the topic using the DMSecurity protocol methods
implemented by the DMMessagePublisher session.]
Using DMSecurity on DMMessageSubscriber:
Find out what privileges a .Mac member has for a given DMTopic:
NSArray *accessRights;
//Note: For a DMMemberAccount, the name and owner are the same.
NSString *myPrincipalID = [DMMemberAccount principalIDWithName:@”ryan”

andOwner:@”ryan”];
DMTransaction *trans = [myMessageSubscriber accessToEntity:theTopic

forPrincipal:myPrincipalID];
//Assuming transaction was done synchronously.

if ( [trans isSuccessful] ) {
accessRights = (NSArray *)[trans result];
}
47
DMSubscriptionDelegate (Informal Protocol)
- (void)topicsHaveChanged: (NSArray *)topics;

This method is called when new messages are published to topics of interest—that is,
topics to which the active DMMessageSubscriber session’s .Mac member is subscribed.
The method takes an NSArray of DMTopic objects. [Note: After receiving this delegate
message, clients can call a DMTopic’s -newMessages method to retrieve all new, unseen
messages.]
- (void)invitationsReceivedForTopics: (NSArray *)topics;

This method is called when new invitations to subscribe to another .Mac member’s topics
are received. Only new invitations that have not yet been seen by the current
combination of .Mac subscriber, running application and local OS X user account are
returned. [Note: An invitation to subscribe to a topic is automatically sent to the
invited .Mac member when that member is granted access to the topic by the topic’s
owner using DMSecurity protocol methods implemented by the DMMessagePublisher
class.]
48
DMTopic
(Conforms to DMTransactionGenerator)
DMTopics have DMMessages published into them using a DMMessagePublisher session.

Users of a DMMessageSubscriber session can subscribe to a DMTopic object in order to
be informed when new messages are published to it. DMTopic objects can only be
created using the factory methods of a DMMessagePublisher or a DMMessageSubscriber
session, and they inherit the credentials of their parent message session. A topic’s
namespace is scoped to its owner (the hosting .Mac member) and the application that
created it.
A DMTopic object can be passed to DMSecurity protocol methods that take an 'entity'
argument, in order to set access privileges on the given topic. When a .Mac member is
granted access to a DMTopic, an invitation is automatically generated and can be
accessed using a DMMessageSubscriber session.
Convenience API
- (NSString *)name;
Returns the name of the topic.
Returns the name of the .Mac member who owns and hosts the topic.
- (NSString *)applicationID;
Returns the creator code of the application that created the topic.
Returns the .Mac member object containing the credentials that will be used to access or
modify this DMTopic object. The returned credentials are the same credentials held by
the DMMessagePublisher or DMMessageSubscriber instance that was used to get a
reference to this DMTopic.
- (DMTransaction *)exists;
The returned DMTransaction object’s result method returns an NSNumber, whose
Boolean value can be retrieved using NSNumber’s boolValue method. This value will be
YES if the DMTopic exists and NO otherwise.
[Note: If an error is encountered that prevents the existence check, the returned
DMTransaction’s -errorType method can be used to identify the error.]
49
Retrieving messages from a topic
- (NSArray *)newMessages;
Returns all DMMessages in this DMTopic that have not yet been accessed by the caller.
(The caller is defined as a combination of the .Mac credentials set for the session that
created this DMTopic, the machine and local OS X user that the calling application is
running under and the calling application itself.) This method will most often be called
after a DMMessageSubscriber session’s subscription delegate is informed of a change in
this DMTopic. Returns an NSArray of DMMessages ordered by publication time,
starting with the earliest.
- (NSArray *)messages;
Returns all DMMessages found in this DMTopic on .Mac, as an NSArray of
DMMessages. Messages are ordered by publication time, starting with the earliest.
- (DMMessage *)messageWithID: (NSString *)messageID;

Retrieves a DMMessage using its globally unique identifier. Returns a DMMessage if the
provided message identifier is valid, and nil otherwise.
- (DMMessage *)newestMessage;
Returns the most recent DMMessage in the topic, based on publication time.
- (DMMessage *)oldestMessage;
Returns the oldest DMMessage in the topic, based on publication time.
Removing messages from a topic
- (DMTransaction *)removeMessageWithID: (NSString *)messageID;

Removes the identified DMMessage from this DMTopic on .Mac. Returns a
This method can only be called if the .Mac credentials being used have ‘write’ access to
the given topic.
- (DMTransaction *)removeMessages;
Removes all DMMessages from this DMTopic on .Mac. Returns a DMTransaction
object whose -isSuccessful method can be used to test for success. This method can only
be called if the .Mac credentials being used have ‘write’ access to the given topic.
50
Resetting the time-to-live of a published message
- (DMTransaction *)resetTimeToLive: (NSTimeInterval)ttl

forMessageWithID: (NSString *)messageID;
Resets the time-to-live value of the DMMessage specified by given identifier. Returns a
DMTransaction object whose -isSuccessful method can be used to test for success. The
provided time-to-live value, an NSTimeInterval with precision in seconds, cannot be
greater than 30 days. This method can only be called if the .Mac credentials being used
have ‘write’ access to the given topic.
Controlling auto-arrival of message payloads
- (void)setIsAutoArrivalEnabledForMessagePayloads:

(BOOL)isEnabled;
This method sets whether future messages received for the topic should have their
payloads downloaded automatically to the local message cache before any callbacks are
made on a DMMessageSubscriber’s subscription delegate. When automatic downloading
(or auto-arrival) of payloads is enabled, which is the default, a call to a DMMessage’s
-payload method simply returns the already-downloaded payload. When auto-arrival is
not enabled for a given topic, a DMMessage’s -payload method will do the extra work of
downloading the payload on request.
This method can be called regardless of whether a subscription to the given topic already
exists. (A message’s meta data—everything but the payload—always arrives
automatically). [Note: Any auto-arrival default set by this method for a topic is
automatically cleared from the local preferences cache if an ‘unsubscribe’ call on the
given topic is ever made in the future.] If this method is being called around the same
time that a subscription to the given topic is being created, it is recommended that this
method be called first, before the call to DMMessageSubscriber’s -subscribeToTopic:
method. This ensures that the desired auto-arrival behavior is in place for the given topic
before any topic-related callbacks are made into a DMMessageSubscriber’s subscription
delegate.
- (BOOL)isAutoArrivalEnabledForMessagePayloads;
This method returns a BOOL value indicating whether future messages received for the
topic should have their payloads downloaded automatically to the local message cache
before any callbacks are made on a DMMessageSubscriber’s subscription delegate.
When automatic downloading (or auto-arrival) of payloads is enabled, which is the
default, a call to a DMMessage’s -payload method simply returns the
already-downloaded payload. When auto-arrival is not enabled for a given topic, a
DMMessage’s -payload method will do the extra work of downloading the payload on
request.
51
DMMessage
(Conforms to DMTransactionGenerator)
Once published to a DMTopic, a DMMessage object becomes immutable. Use

DMMessage’s -isPublished method to determine whether a message has been published
to .Mac.
+ (DMMessage *)message: (NSString *)messageString;

Returns an autoreleased DMMessage instance containing the provided message string.
This is a convenience method for creating a DMMessage containing just the provided
message string and no payload object or properties dictionary. The message string cannot
exceed 1K in size.
+ (DMMessage *)message: (NSString *)messageString

withProperties: (NSDictionary *)properties

andPayload: (id)object

ofType: (NSString *)payloadType;
Returns an autoreleased DMMessage instance containing a payload object, payload type,
and an optional message string and properties dictionary (actually, all parameters are
optional, but at least one of them must be non-nil). The message string cannot exceed 1K
in size and the optional dictionary cannot exceed 100K in size. [Note: The dictionary can
contain only NSString keys and values and the 100K limit includes both keys and
values.] The payload object must conform to the NSCoding protocol—its size is limited
to 5MB and is further limited by the space available to the .Mac member who owns the
parent topic. The payload type is an NSString that represents the file type that would be
used if the payload object were serialized to disk.
- (DMMessage *)initMessage: (NSString *)messageString;

Returns a newly initialized DMMessage instance containing the provided message string.
This is a convenience method for creating a DMMessage containing just the provided
message string and no payload object or properties dictionary. The message string cannot
exceed 1K in size.
- (DMMessage *)initMessage: (NSString *)messageString

withProperties: (NSDictionary *)properties

andPayload: (id)object

ofType: (NSString *)payloadType;
Returns a newly initialized DMMessage instance containing a payload object, payload
type, and an optional message string and properties dictionary (actually, all parameters
are optional, but at least one of them must be non-nil). The message string cannot exceed
1K in size and the optional dictionary cannot exceed 100K in size. [Note: The dictionary
can contain NSString keys and values only and the 100K limit includes both keys and
values.] The payload object must conform to the NSCoding protocol—its size is limited
52
to 5MB and is further limited by the space available to the .Mac member who owns the
parent topic. The payload type is an NSString that represents the file type that would be
used if the payload object were serialized to disk.
Convenience API
- (NSString *)messageID;
Returns this DMMessage's globally unique identifier string.
- (NSString *)publisher;
Returns the name of the .Mac member who published this DMMessage to .Mac. Returns
nil if this DMMessage has not yet been published.
- (DMTopic *)topic;
Returns the topic that contains this DMMessage. Returns nil if this DMMessage has not
yet been published to a topic.
- (NSString *)messageString;
Returns the optional message string set for the DMMessage.
- (int)setMessageString: (NSString *)messageString;

Sets the optional message string for the DMMessage. The message string cannot exceed
1K in size. An integer status constant is returned. [Note: Calling this method on an
already-published message will result in kDMResourceExists being returned; otherwise,
this method returns kDMSuccess. The -isPublished method can be used to determine
whether this DMMessage has already been published.]
- (DMTransaction *)payload;
Retrieves the optional payload object set for the DMMessage. Upon success, the
returned DMTransaction object’s -result method will return this message’s payload
object, an object that conforms to the NSCoding protocol. If auto-arrival of payloads is
enabled for this message’s parent topic, then the payload object is already available
locally by the time this new message is received and the caller can call the returned
DMTransaction’s -result method right away. However, if auto-arrival is disabled, this
DMMessage’s payload is not downloaded until this -payload method is called. If this
DMMessage’s transaction processing is set to asynchronous, then the status of the
download can be observed by setting this DMMessage’s transaction delegate or through
polling the returned DMTransaction object. [Note: If this DMMessage’s transaction
delegate is not set, then it will inherit any transaction delegate that is explicitly set for its
parent DMTopic or that has been inherited by its parent DMTopic from the session object
used to create it.] If auto-arrival is disabled and this DMMessage’s transaction
53
processing is set to synchronous, then this method will not return until the payload is
completely downloaded. In all cases, the payload is retrieved with a call to the returned
DMTransaction object’s -result method.
- (NSString *)payloadType;
Returns the type corresponding to the payload for this DMMessage. The payload type is
an NSString that represents the file type that would be used if the payload object were
serialized to disk. Returns a type string, or nil if no payload object is set for this
DMMessage.
- (int)setPayload: (id)object ofType: (NSString *)payloadType;

Sets the payload object and its type. Both the payload and the type argument must be
non-nil if this method is called. The payload is an object that conforms to the NSCoding
protocol. Its size is limited to 5MB and is further limited by the space available to
the .Mac member who owns the parent topic. The payload type is an NSString that
represents the file type that would be used if the payload object were serialized to disk.
[Note: Calling this method on an already-published message will result in
kDMResourceExists being returned; otherwise, this method returns kDMSuccess. The
-isPublished method can be used to determine whether this DMMessage has already been
published.]
- (NSDictionary *)properties;
Returns the optional user-defined properties dictionary set for this DMMessage.
- (int)setProperties: (NSDictionary *)properties;

Sets the optional properties dictionary for this DMMessage. This dictionary cannot
exceed 100K in size. The dictionary can contain NSString keys and values only and the
100K limit includes both keys and values. [Note: Calling this method on an already-
published message will result in kDMResourceExists being returned; otherwise, this
method returns kDMSuccess. The -isPublished method can be used to determine whether
this DMMessage has already been published.]
- (NSDate *)publicationDate;
Returns the time when this DMMessage was published to .Mac, which is an NSDate
object with precision in seconds. If this DMMessage has not yet been published, this
method returns nil.
- (NSDate *)expirationDate;
If this DMMessage has already been published, this method returns an NSDate that
marks the time this DMMessage expires (with precision in seconds). Otherwise, this
method returns nil. If the expiration time returned for this DMMessage is in the past, it
means that this message is awaiting clean-up.
54
- (NSTimeInterval)timeToLive;
Returns an NSTimeInterval (with precision in seconds) representing the default time-to-
live of 7 days if the default was not overridden by a DMMessagePublisher setting or by a
call to this DMMessage’s -setTimeToLive: method.
- (int)setTimeToLive: (NSTimeInterval)timeToLive;
This method can be used to set the time-to-live for this DMMessage prior to publication.
The default time-to-live is 7 days, and the time-to-live cannot be made longer than 30
days. Takes an NSTimeInterval (precision in seconds). [Note: Calling this method on an
already-published message will result in kDMResourceExists being returned; otherwise,
this method returns kDMSuccess. The -isPublished method can be used to determine
whether this DMMessage has already been published.]
- (BOOL)isPublished;
Tells whether the DMMessage has already been published to .Mac. A DMMessage can
be published to .Mac only once and it becomes immutable once published. An attempt to
publish a DMMessage more than once will fail. Returns a BOOL value.
© 2005 Apple Computer, Inc. All rights reserved. .Mac, Apple, the Apple logo, Mac, Mac OS,
and Macintosh are trademarks of Apple Computer, Inc., registered in the U.S. and other
countries.
55

DMKit 2 0 API

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DMKit 2 0 API

Uploaded by

Copyright:

Available Formats



DotMac Kit 2.0 (Developer Preview)

Using Transactions ........................................................................... 8

DMTransactionDelegate (Informal Protocol) ...................................................................... 12

DMTransactionGenerator (Formal Protocol) ...................................................................... 13

Credentials and Account Management ......................................... 14

DMPrincipal (Formal Protocol) ............................................................................................ 22

Security and Access Control ..........................................................23

Transferring Data with iDisk ........................................................... 26

DMiDiskFileManager (Category of DMiDiskSession) ......................................................... 35

Using DMSecurity on DMiDiskSession ............................................................................... 37

Using Store-and-forward Messaging .......................................... 38

DMSubscriptionDelegate (Informal Protocol) .....................................................................48

DMMemberAccount’s -servicesAvailableForAccount method creates an NSArray of

Status Constants: The -validateCredentials and -errorType methods (from

DMiDiskSession’s -basicAttributesAtPath: method creates an NSDictionary (retrieved

DMiDiskSession’s -extendedAttributesAtPath: method creates an NSDictionary

The following constants are used by the DMUtilities method,

Auto-launch constants are used for passing launch options to DMMessageSubscriber

- (void) setContext: (id)context;

Getting transaction status

- (void)transactionSuccessful: (DMTransaction *)theTransaction;

- (void)transactionHadError: (DMTransaction *)theTransaction;

- (void)transactionAborted: (DMTransaction *)theTransaction;

Factories and Initers

+ accountWithName: (NSString *)name

- initWithName: (NSString *)name

Convenience API (Inherited from DMAccount)

- (void)setApplicationName: (NSString *)name;

Checking account credentials

Requesting account properties

Upgrading or signing up a .Mac member

+ (NSURL *)signUpURLWithApplicationID: (NSString *)appID;

Managing secondary accounts

- (DMTransaction *)createSecondaryUserWithName: (NSString *)name

- (DMTransaction *)removeSecondaryUserNamed: (NSString *)name;

- (DMTransaction *)resetPassword: (NSString *)password

- (DMGroup *)groupNamed: (NSString *)name;

- (DMTransaction *)createGroupWithName: (NSString *)name

- (DMTransaction *)removeGroupNamed: (NSString *)name;

Factories and Initers

+ (DMSecondaryUser *)secondaryUserWithName: (NSString *)name

- (DMSecondaryUser *)initWithName: (NSString *)name

A DMGroup is owned by a .Mac member and can only be created using a

Managing group members

- (DMTransaction *)addMembers: (NSArray *)members;

- (DMTransaction *)removeMembers: (NSArray *)members;

+ (NSString *)principalIDWithName: (NSString *)name

DMSecurity (Formal Protocol)

Reading access privileges

- (DMTransaction *)accessToEntity: (id)entity

- (DMTransaction *)accessToEntity: (id)entity

Setting access privileges

- (DMTransaction *)setAccess: (NSArray *)access

Resetting access to an entity’s children

- (DMTransaction *)resetAccessToChildrenOfEntity: (id)entity;

Supported iDisk operations include:

Asynchronous and Synchronous Data Retrieval:

Asynchronous and Synchronous Data Upload:

Asynchronous and Synchronous File Maintenance & General:

DMiDiskSession is a thread-safe class which facilitates interactions with iDisk.

Please note: All server-side paths passed as arguments to DMiDiskSession methods

Factories and initers

+ (NSURL )signUpURLWithApplicationID: (NSString )appID;

- (DMTransaction )createSecondaryUserWithName: (NSString )name

- (DMTransaction )removeSecondaryUserNamed: (NSString )name;

- (DMTransaction )resetPassword: (NSString )password

- (DMGroup )groupNamed: (NSString )name;

- (DMTransaction )createGroupWithName: (NSString )name

- (DMTransaction )removeGroupNamed: (NSString )name;

+ (DMSecondaryUser )secondaryUserWithName: (NSString )name

- (DMSecondaryUser )initWithName: (NSString )name

- (DMTransaction )addMembers: (NSArray )members;

- (DMTransaction )removeMembers: (NSArray )members;

+ (NSString )principalIDWithName: (NSString )name

- (DMTransaction )setAccess: (NSArray )access

- (DMTransaction )getDataAtPath: (NSString )sourcePath;

- (DMTransaction )getDataAtPath: (NSString )sourcePath

- (DMTransaction )getDataAtPath: (NSString )sourcePath

- (DMTransaction )putData: (NSData )data

- (DMTransaction )putData: (NSData )data

- (DMTransaction )makeCollectionAtPath: (NSString )thePath;

- (DMTransaction )moveResourceAtPath: (NSString )sourcePath

- (DMTransaction )copyResourceAtPath: (NSString )sourcePath

- (DMTransaction )deleteResourceAtPath: (NSString )thePath;

- (DMTransaction )lockResourceAtPath: (NSString )thePath;

- (DMTransaction )lockResourceAtPath: (NSString )thePath

- (DMTransaction )relockResourceAtPath: (NSString )thePath;

- (DMTransaction )relockResourceAtPath: (NSString )thePath

- (DMTransaction )unlockResourceAtPath: (NSString )thePath;

- (DMTransaction )basicAttributesAtPath: (NSString )thePath;

- (DMTransaction )extendedAttributesAtPath: (NSString)thePath;

- (DMTransaction )listCollectionAtPath: (NSString )thePath;

- (NSData )contentsAtPath:(NSString )path;

- (BOOL)fileExistsAtPath:(NSString )path isDirectory:(BOOL )

- (NSArray )directoryContentsAtPath:(NSString )path;

- (DMTransaction )createTopicNamed: (NSString )name;

- (DMTransaction )removeTopicNamed: (NSString )name;

- (DMTopic )topicNamed: (NSString )name;

- (DMTopic )topicNamed: (NSString )name

- (DMTopic )topicNamed: (NSString )name

- (DMTransaction )publishMessage: (DMMessage )message

- (DMTopic )topicNamed: (NSString )name;

- (DMTopic )topicNamed: (NSString )name

- (DMTopic )topicNamed: (NSString )name

- (DMTransaction )subscribeToTopic: (DMTopic )topic;