InstapaperKit 技术文档

安装指南

获取源代码

InstapaperKit 使用 git submodule。要获取源代码及其子模块，请执行以下步骤：

git clone git://github.com/matthiasplappert/InstapaperKit.git /some/path/InstapaperKit
cd /some/path/InstapaperKit/
git submodule update --init --recursive

集成到项目中

最简单的方式是将 Xcode 项目中的 InstapaperKit 组中的所有类添加到您自己的项目中。包含的 Xcode 项目还包括一个框架构建目标，您可以在 Mac OS X 上使用。

导入头文件

如果您使用的是框架，请使用以下方式导入头文件：

#import <InstapaperKit/InstapaperKit.h>

如果直接使用类文件，请使用：

#import "InstapaperKit.h"

项目的使用说明

配置 OAuth Consumer Key 和 Secret

首先，设置您的 OAuth consumer key 和 secret。如果您还没有这些信息，您需要向 Instapaper 申请。

[IKEngine setOAuthConsumerKey:@"your application's consumer key"
            andConsumerSecret:@"your application's consumer secret"];

这些值是全局使用的，因此建议在应用程序启动后立即进行此配置。确保您的 OAuth consumer secret 是保密的。

请求 OAuth Token 和 Secret

xAuth（类似于 OAuth）不通过用户名和密码进行身份验证，而是通过 token 和 secret。因此，您应该永远不要存储用户的密码，而只存储 token 和 secret。通常在用户输入用户名和密码后立即请求 token。

// 假设您的类有一个实例变量 _engine
_engine = [[IKEngine alloc] initWithDelegate:self];
[_engine authTokenForUsername:@"[e-mail]" password:@"shh, secret!" userInfo:nil];

请求完成后，您的代理的 engine:connection:didReceiveAuthToken:andTokenSecret: 方法将被调用：

- (void)engine:(IKEngine *)engine connection:(IKURLConnection *)connection didReceiveAuthToken:(NSString *)token andTokenSecret:(NSString *)secret
{
    // 分配 token 和 secret
    engine.OAuthToken  = token;
    engine.OAuthTokenSecret = secret;

    // 将 token 和 secret 存储在 keychain 中（不要使用 NSUserDefaults 存储 secret！）
}

确保存储您的 token 和 secret，您不希望每次应用程序启动时都请求 token 和 secret。同时，确保将 secret 存储在安全的地方，如 keychain。

IKEngineDelegate

配置好 InstapaperKit 后，您可以开始使用 API。由于 InstapaperKit 使用异步连接，它大量使用 IKEngineDelegate。

IKEngineDelegate 定义了 4 个通用方法：engine:willStartConnection:、engine:didFinishConnection:、engine:didFailConnection:error: 和 engine:didCancelConnection:。这些方法在每次连接开始、完成、失败或取消时被调用。您可以使用 IKURLConnection 的 type 属性来确定您正在处理的连接类型。

IKEngineDelegate 还定义了一些在请求成功时调用的代理方法。这些方法传递相应请求的解析返回值。请注意，无论您是否实现特定的成功方法，engine:didFinishConnection: 方法都会被调用。

尝试 InstapaperKit

InstapaperKit Xcode 项目包含 Test 目标，该目标构建了一个简单的 Mac OS X 应用程序，该应用程序实现了所有代理方法并将结果记录下来。您可以尝试使用该框架。

项目API使用文档

IKEngine 类

IKEngine 类是 InstapaperKit 的核心类，负责与 Instapaper API 进行交互。它处理所有的网络请求和响应解析。

主要方法

• authTokenForUsername:password:userInfo:：请求用户的 OAuth token 和 secret。
• addBookmark:withUrl:userInfo:：添加书签。
• listBookmarks:limit:type:userInfo:：列出书签。
• deleteBookmark:userInfo:：删除书签。

IKEngineDelegate 协议

IKEngineDelegate 协议定义了与 IKEngine 交互的代理方法。您需要实现这些方法来处理 API 请求的结果。

主要方法

• engine:willStartConnection:：连接开始时调用。
• engine:didFinishConnection:：连接完成时调用。
• engine:didFailConnection:error:：连接失败时调用。
• engine:didCancelConnection:：连接取消时调用。

项目安装方式

使用 Git 克隆项目

git clone git://github.com/matthiasplappert/InstapaperKit.git /some/path/InstapaperKit
cd /some/path/InstapaperKit/
git submodule update --init --recursive

集成到 Xcode 项目

将 InstapaperKit 组中的所有类添加到您的 Xcode 项目中，或者使用框架构建目标。

导入头文件

根据您的集成方式，使用以下方式导入头文件：

#import <InstapaperKit/InstapaperKit.h>

或

#import "InstapaperKit.h"

通过以上步骤，您可以成功安装并使用 InstapaperKit 项目。