代码
GDataObjCIntroduction
Introduction for Objective-C Developers
* Introduction to Google Data APIs for Cocoa Developers
o Requirements
o Example Applications
o Adding Google Data APIs to a project
o Google Data APIs Basics
o Creating GDataObjects from scratch
o Adding custom data to GDataObject instances
o Passing objects to fetch callbacks
o Batch requests
o Uploading files
+ Upload progress monitoring
o Status 304 and service data caching
o Fetching during modal dialogs
o Authentication errors and captchas
o Automatic retry of failed fetches
o Proxy Authentication
o Logging http server traffic
o Service Introspection
o Performance and Memory Improvements
o Questions and Comments
2: 实例程序
3：如何向工程中添加Google Data APIs
4: Google Data APIs 基础知识
5: 如何创建 GDataObjects
6: 往GDataObject实例中添加自定义数据结构。
7: 传递对象到回叫函数
8: 批量请求 （一个服务器处理多种请求，新建，删除，上传，更新等）
9: 上传文件
上传过程监听
10: 状态 304 和 服务器数据缓存
11: Fetching抓取 对话模式 （网络链接过程）
12: 证书（认证）错误和 说明
13: 获取失败后自动链接
14: 代理认证
15: 记录HTTP服务器
16: 服务自检
17: 性能和内存优化
18: 问题和评语
Introduction to Google Data APIs for Cocoa Developers
Google Data APIs allow client software to access and manipulate data hosted by Google services.
Google Data APIs 让客户端连接操作由google服务器上的数据
The Google Data APIs Objective-C Client Library is a Cocoa framework that enables developers for Mac OS X and iPhone to easily write native applications using Google Data APIs. The framework handles
The Google Data APIs Objective-C Client Library 属于Cocoa框架，让MAC和iPhone程序员更容易编写程序。
这个框架处理
* XML parsing and generation
xml文件的解析和生成
* Networking
网络处理
* Sign-in for Google accounts
google帐户登陆
* Service-specific protocols and query generation
特殊服务协议和问题的产生
Requirements
The Google Data APIs Objective-C Client Library requires Mac OS X 10.4 due to its use of NSXMLDocument.
要求10.4以上OSX版本，使用NSXMLDocument
Example Applications
The Examples directory contains example applications showing typical interactions with Google services using the framework. The applications act as simple browsers for the structure of feed and entry classes for each service. The WindowController source files of the samples were written with typical Cocoa idioms to serve as quick introductions to use of the APIs.
在示例目录中包含一个示例程序，演示了通过这个框架与Google服务器进行典型的交互通信。这个示例程序演示了各种服务中所须使用的feed（源）和entry（元）的结构和典型用法。
示例程序中的WindowController源文件作为如何是用apis的说明代码，是用典型的cocoa习惯语法写的。
Adding Google Data APIs to a project
如何添加apis到项目工程
BuildingTheLibrary explains how to add the library to a Mac or iPhone application project.
Google Data APIs Basics
基础知识
Servers respond to client GData requests with feeds that include lists of entries. For example, a request for all of a user's calendars would return a Calendar feed with a list of entries, where each entry represents one calendar. A request for all events in one calendar would return a Calendar Event feed with a list of entries, with each entry representing one of the user's scheduled events.
服务器用包含一系列的数据元的feed来应答客户端的请求。列如：用户请求获得其所有日历信息，服务器将返回包含由多个数据元（entries）的一个日历feed，其中每个数据元都对应于用户的一个日历信息。如果请求获取某个日历中所有事件信息，服务器将返回日历事件feed，其中的每个数据元就对应与日历中的一个事件。
Each feed and entry is composed of elements. Elements represent either standard Atom XML elements, or custom-defined GData elements.
每个feed和entry都是由元素组成，其元素又是由Atom或xml或自定义的一种Gdata数据结构中的一个元素来描述
Feeds, entries, and elements are derived from GDataObject, the base class that implements XML parsing and generation.
Feeds, entries, and elements都是继承与GDataObject－作为xml文件解析生成的基础
Google web application interactions are handled by service objects. A single transaction with a service is tracked with a service ticket.
google网页程序通过service objects（服务器对象）处理交互。服务器通过service ticket（服务器票）来标识一个与服务器的交互通信。
For example, here is how to use the Google Calendar service to retrieve a feed of calendar entries, where each entry describes one of the user's calendars.
列如，下面介绍google日历服务器如何获取一个日历数据源的feed，其中每个数据元都描述用户的一个日历。
代码
service = [[GDataServiceGoogleCalendar alloc] init]; //生成服务器。
[service setUserCredentialsWithUsername:username //认证
password:password];
NSURL *feedURL = [GDataServiceGoogleCalendar calendarFeedURLForUsername:username]; //获取用户的feed
GDataServiceTicket *ticket; //ticket 服务器通过ticket标识用户与服务器的连接交互通信。
ticket = [service fetchFeedWithURL:feedURL
delegate:self
didFinishSelector:@selector(ticket:finishedWithFeed:error:)];
Service objects maintain cookies and track data modification dates to minimize server loads, so it's best to reuse a service object for sequences of server requests.
服务器对象实例保存了cookies和用于追踪的数据以及修改日期，来减少服务器的负载，所以在执行一系列的服务请求时，最好重用一个服务器对象实例。
The application may choose to retain the ticket following the fetch call so the user can cancel the service request. The ticket is valid so long as the application retains it. To cancel a fetch in progress, call [ticket cancelTicket]. Once the finished or failed callback has been called, the ticket is no longer useful and may be released.
在程序种可能会保存ticket以便在回调函数之后取消当前的服务请求。只要程序种retain了ticket那这个ticket就一直是有效的。在请求服务执行的过程中，可以通过调用[ticket cancelTicket]函数取消。直到执行完毕函数或者失败返回函数被调用，ticket才失效或者被释放。
The delegate of the fetch is also retained until the fetch has stopped.
fetch（回叫函数）的代理将一直被保留直到这个fetch运行结束。
Here is what the callback from a fetch of the calendar list might look like. This callback example just prints the title of the user's first calendar.
下面这段代码是 日历列表fetch的回叫函数。
这段代码执行效果，打印用户第一个日历列表的title标题。
代码
- (void)ticket:(GDataServiceTicket *)ticket
finishedWithFeed:(GDataFeedCalendar *)feed
error:(NSError *)error {
if (error == nil) {
if ([[feed entries] count] > 0) {
GDataEntryCalendar *firstCalendar = [[feed entries] objectAtIndex:0];
GDataTextConstruct *titleTextConstruct = [firstCalendar title];
NSString *title = [titleTextConstruct stringValue];
NSLog(@"first calendar's title: %@", title);
} else {
NSLog(@"the user has no calendars")
}
} else {
NSLog(@"fetch error: %@", error);
}
}
Service objects include a variety of methods for interacting with the service. Typically, the interactions include some or all of these activities:
服务器对象包括了大量的方法用于与服务相关的交互。典型来说，这些交互请求中包括以下这些活动：
* fetching a feed
fetch捕捉一个feed
* inserting an entry into a feed
添加一个entry数据元到feed
* updating (replacing) an entry in a feed
更新（替换）feed中的某个entry数据元
* deleting an entry or a feed
删除一个entry数据元或数据源feed
* performing queries to obtain a subset of the feed's entries
执行查询语句保存数据源数据元的子集
* performing a batch operation of inserting, updating, and deleting entries
执行批处理操作－包括插入，更新和删除某个数据元。
Feeds and entries usually contain links to themselves or to other objects. The library provides convenience methods for retrieving individual links. 数据源和数据元一般都保存有到他们的服务器或其它相关对象的连接。这个程序框架提供了一些转换方法函数来处理每个独立的连接。
For example, to retrieve the events for a user's calendar, use a Calendar service object to fetch from the Calendar's "alternate" link:
以处理用户日历事件来说，用Calendar service object日历服务器对象去获取从Calendar's返回的"alternate" link
GDataLink *link = [calendarEntry alternateLink];
if (link != nil) {
[service fetchFeedWithURL:[link URL]
delegate:self
didFinishSelector:@selector(eventsTicket:finishedWithFeed:error:)];
}
Typically, the alternate link points to an html or user-friendly representation of the data, though Google Calendar uses it as a link to the event feed for a calendar.
一般说来，the alternate link指向一个html文件或者指向一个用户有好的数据描述，而GoogleCalendar用the alternate link指向日历事件feed
Modifiable feeds may have a post link, which contains the URL for inserting new entries into the feed. Modifiable entries have an edit link, which is used to update or delete the entry. Entries that refer to non-XML data, such as photographs, may include an edit media link for modifying or deleting the media data.
可修改的数据源feed可能有一个post link，包含了可以添加新数据元到feed数据源的URL。可修改的数据元有一个可编辑的link，用于更新或删除entry
Entries数据元是非xml格式的数据，如照片，包括可编辑的多媒体link连接去编辑或删除多媒体信息。
Both entries and feeds have self links, which self-referentially contain the URL of the XML for the entry or feed. The self link is useful for fetching a complete, current version of an entry prior to updating the entry on the server.
所有的数据元和数据源都有自己的links，xml可以包含这些数据源和数据元的URL。他们自身的连接地址在fetching结束时很有用，当前版本中的数据元要先在服务器上更新？？？？_ghl_这一段翻译的很有问题。
A particularly important link in feeds is the next link; it is present when the feed contains only a partial set, or one page, of entries from the request. If the feed's -nextLink is non-nil, the client application must perform a new request using the "next" link URL to retrieve the next page of the feed, containing additional entries.
在数据源中一个特别重要的连接地址时the next link（下一个连接地址），下一个连接地址只有在当前数据源中包含的只是所有数据的一个子集，或其中的一页 这是才会出现下一个连接地址。如何单前处理的数据源中的-nextLink 属性非空，那么客户端程序必须要建立对nextlink的请求以获得下一页的数据源，包含更多的数据元信息。
Rather than make a new fetch for each "next" link, the library's service object can follow next links automatically, and return a feed whose entries are the full accumulated set of entries from fetching all pages of the feed (up to 25 pages.) This can be turned on in the service object with [service setServiceShouldFollowNextLinks:YES]. The fetch's ticket then applies to the sequence of http requests needed to obtain the entries from all pages in the feed, so canceling the ticket will cancel the sequence of requests.
比起对于每个“下个连接”都做新的fetch请求更好的方法是，在Gdata函数库中，服务器对象可以自动的检测“下个连接地址”并且返回一个数据源包含所有不同页面的数据元（最多25个分页面）。这个功能可以通过服务器对象 [service setServiceShouldFollowNextLinks:YES]函数开启。开启后The fetch's ticket就包含了一系列的所有页面需要被保存的http请求，如果这时释放了这个The fetch's ticket，那么这一系列的http请求也将被释放。
Note, however, that feeds spread over many pages may take a long time to be retrieved, as each "next" link will lead to a new http request. The server can be told to use a larger page size (that is, more entries in each page of the feed) by fetching a query for the feed with a maxResults parameter:
需要主意的是：不管这个数据源包含多少页面，可能需要更多的时间去处理，因为每个页面上的“next link”都要引申初新的http请求。服务器可以被告知用一个更大的页面（包含更过数据元的页面。）通过请求fetching中maxResults parameter属性设置
GDataQueryCalendar *query = [GDataQueryCalendar calendarQueryWithFeedURL:feedURL]; [query setMaxResults:1000]; //设置 GDataServiceGoogleCalendar *service = [self calendarService]; GDataServiceTicket *ticket; ticket = [service fetchFeedWithQuery:query delegate:self didFinishSelector:@selector(ticket:finishedWithFeed:error:)];
Beginning with version 2 of the Google Data API core protocol, each fetched feed and entry has an ETag attribute. The ETag is just a server-generated hash string uniquely identifying the version of the entry data. Services may require that the ETag attribute be present when updating or deleting an entry or other file, such as a photo. This prevents the client application from accidentally modifying or deleting the wrong version of the data on the server.
在第二版中，GData API 核心协议中，每个fetched feed 和entry 都添加了ETag 属性。ETag属性是由服务器生成的哈希字符串是数据元数据的唯一标识。服务器可能会要求ETag属性，当用户要对某数据元或文件执行更新或删除操作。以防止客户端程序在服务器上错误的修改、删除错误的版本文件。
ETag strings are also useful to clients for determining if a feed, entry, or other file on the server has changed. If the underlying resource data has changed, the ETag is guaranteed to have changed as well.
ETag 字符串也可以被客户端程序用来判断一个feed或entry或者服务器上的文件是否被修改过。只要源数据被修改了，则可以保证它的ETag也将进行相应的修改。
Service-specific query objects can generate URLs with parameters appropriate for restricting a feed's entries. For example, a query could request a feed of Calendar events between specific dates, or of database items of a specified category.
服务器的特别请求对象可以生成一个属性被适当修改以进行某些限制的URL地址。举个例子，一个请求要求返回日历事件中特定日期或者特定类别的事件。
Here is an example of a query to retrieve the first 5 events from a user's calendar:
下面这个示例程序要求返回用户日历事件中的前5个事件。
- (void)beginFetchingFiveEventsFromCalendar:(GDataEntryCalendar *)calendar {
NSURL *feedURL = [[calendar alternateLink] URL];
GDataQueryCalendar* query = [GDataQueryCalendar calendarQueryWithFeedURL:feedURL];
[query setStartIndex:1];
[query setMaxResults:5];
GDataServiceGoogleCalendar *service = [self calendarService];
[service fetchFeedWithQuery:query
delegate:self
didFinishSelector:@selector(queryTicket:finishedWithEntries:error:)];
}