This repository has been archived by the owner on Jan 19, 2022. It is now read-only.
/
api.xml
163 lines (126 loc) · 6.81 KB
/
api.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="api" version="5.0" xmlns="http://docbook.org/ns/docbook"
xmlns:ns52="http://www.w3.org/2000/svg"
xmlns:ns5="http://www.w3.org/1999/xlink"
xmlns:ns4="http://www.w3.org/1998/Math/MathML"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
<title>Dropbox API Binding</title>
<para>
Spring.NET Social Dropbox offers integration with Dropbox's REST API through the <interfacename>IDropbox</interfacename> interface
and its implementation, <classname>DropboxTemplate</classname>.
</para>
<para>
Creating an instance of <classname>DropboxTemplate</classname> involves invoking its constructor,
passing in the application's OAuth credentials, an access token/secret pair authorizing the application to act on a user's behalf
and the type of access level configured with the application.
<sbr/>For example:
</para>
<programlisting language="csharp"><![CDATA[string consumerKey = "..."; // The application's consumer key
string consumerSecret = "..."; // The application's consumer secret
string accessToken = "..."; // The access token granted after OAuth authorization
string accessTokenSecret = "..."; // The access token secret granted after OAuth authorization
IDropbox dropbox = new DropboxTemplate(consumerKey, consumerSecret, accessToken, accessTokenSecret, AccessLevel.Full);]]></programlisting>
<para>
In addition, <classname>DropboxTemplate</classname> has a <literal>Locale</literal> property
that allows to specify language settings of content responses:
</para>
<programlisting language="csharp"><![CDATA[dropbox.Locale = "fr-FR";]]></programlisting>
<para>
You can also get an instance of <interfacename>IDropbox</interfacename> from the <classname>DropboxServiceProvider</classname> class.
<sbr/>The example code below shows use of the <classname>DropboxServiceProvider</classname> to retrieve an instance of <interfacename>IDropbox</interfacename>
after authenticating through OAuth1 server-side flow:
<programlisting language="csharp"><![CDATA[
DropboxServiceProvider serviceProvider = new DropboxServiceProvider("consumerKey", "consumerSecret", AccessLevel.AppFolder);
OAuth1Operations oauthOperations = serviceProvider.AuthOperations;
OAuthToken requestToken = oauthOperations.FetchRequestToken(null, null);
OAuth1Parameters parameters = new OAuth1Parameters();
parameters.CallbackUrl = "http://my-callback-url/";
parameters.Add("locale", "fr-FR"); // for a localized version of the authorization website
string authorizeUrl = oauthOperations.BuildAuthorizeUrl(requestToken, parameters);
Response.Redirect(authorizeUrl);
// upon receiving the callback from the provider:
OAuthToken accessToken = oauthOperations.ExchangeForAccessToken(new AuthorizedRequestToken(requestToken, null), null);
IDropbox dropboxApi = serviceProvider.GetApi(accessToken.Value, accessToken.Secret);]]></programlisting>
</para>
<para>
Once you have a <interfacename>IDropbox</interfacename>, you can perform a several operations against Dropbox.
<sbr/><interfacename>IDropbox</interfacename> is defined as follows:
</para>
<programlisting language="csharp"><![CDATA[public interface IDropbox : IApiBinding
{
DropboxProfile GetUserProfile();
Entry CreateFolder(string path);
Entry Delete(string path);
Entry Move(string fromPath, string toPath);
FileRef CreateFileRef(string path);
Entry Copy(string fromPath, string toPath);
Entry CopyFileRef(string fromFileRef, string toPath);
Entry UploadFile(IResource file, string path);
Entry UploadFile(IResource file, string path, bool overwrite, string revision);
DropboxFile DownloadFile(string path);
DropboxFile DownloadFile(string path, string revision);
DropboxFile DownloadPartialFile(string path, long startOffset, long length);
DropboxFile DownloadPartialFile(string path, long startOffset, long length, string revision);
DeltaPage Delta(string cursor);
Entry GetMetadata(string path);
Entry GetMetadata(string path, MetadataParameters parameters);
IList<Entry> GetRevisions(string path);
IList<Entry> GetRevisions(string path, int revLimit);
Entry Restore(string path, string revision);
IList<Entry> Search(string path, string query);
IList<Entry> Search(string path, string query, int fileLimit, bool includeDeleted);
DropboxLink GetShareableLink(string path);
DropboxLink GetMediaLink(string path);
DropboxFile DownloadThumbnail(string path, ThumbnailFormat format, ThumbnailSize size);
}]]></programlisting>
<para>
There are 3 ways to call a method depending on the target Framework:
<itemizedlist>
<listitem>
<emphasis role="bold">Synchronuous methods</emphasis>
<para>Available on .NET 2.0 and .NET 3.5</para>
<programlisting language="csharp"><![CDATA[DropboxProfile profile = dropbox.GetUserProfile();
Console.WriteLine("Hi " + profile.DisplayName + "!");]]></programlisting>
</listitem>
<listitem>
<emphasis role="bold">Asynchronuous methods</emphasis>
<para>Available on .NET 2.0, .NET 3.5 and Windows Phone</para>
<programlisting language="csharp"><![CDATA[DropboxProfile profile = dropbox.GetUserProfileAsync(
r =>
{
Console.WriteLine("Hi " + r.Response.DisplayName + "!");
});]]>
</programlisting>
</listitem>
<listitem>
<emphasis role="bold">Task-based asynchronuous methods (Task Parallel Library)</emphasis>
<para>Available on .NET 4.0</para>
<programlisting language="csharp"><![CDATA[DropboxProfile profile = dropbox.GetUserProfileAsync()
.ContinueWith(task =>
{
Console.WriteLine("Hi " + task.Result.DisplayName + "!");
});]]>
</programlisting>
<para>Advanced usage scenario:</para>
<programlisting language="csharp"><![CDATA[Task[] tasks = new Task[]
{
dropbox.UploadFileAsync(new FileResource(@"c:\Image1.jpg"), "/Images/Image1.jpg")
.ContinueWith(t => Console.WriteLine("Image1.jpg uploaded!")),
dropbox.UploadFileAsync(new FileResource(@"c:\Image2.jpg"), "/Images/Image2.jpg")
.ContinueWith(t => Console.WriteLine("Image2.jpg uploaded!")),
};
Task.WaitAll(tasks);
Console.WriteLine("All images uploaded!");]]>
</programlisting>
</listitem>
</itemizedlist>
</para>
<para/>
<para>
For complete details on the Spring.NET Social's entire Dropbox API binding,
refer to the API documentation from the "doc/api" directory of the distribution
and to the <ulink url="https://www.dropbox.com/developers/reference/api">Dropbox REST API documentation</ulink>.
<sbr/>Samples are provided in the 'examples' directory of the distribution.
</para>
</chapter>