[ { "path": ".gitignore", "content": "# Built application files\n*.apk\n*.ap_\n\n# Files for the Dalvik VM\n*.dex\n\n# Java class files\n*.class\n\n# Generated files\nbin/\ngen/\n\n# Gradle files\n.gradle/\nbuild/\n\n# Local configuration file (sdk path, etc)\nlocal.properties\n\n# Proguard folder generated by Eclipse\nproguard/\n\n# Log Files\n*.log\n\n# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm\n*.iml\n.idea/\n\n## Directory-based project format:\n\n# User-specific stuff:\n .idea/workspace.xml\n .idea/tasks.xml\n .idea/dictionaries\n\n# Sensitive or high-churn files:\n .idea/dataSources.ids\n .idea/dataSources.xml\n .idea/sqlDataSources.xml\n .idea/dynamic.xml\n .idea/uiDesigner.xml\n\n# Gradle:\n .idea/gradle.xml\n .idea/libraries\n\n# Mongo Explorer plugin:\n .idea/mongoSettings.xml\n\n## File-based project format:\n*.ipr\n*.iws\n\n.DS_Store\n" }, { "path": ".travis.yml", "content": "language: android\n\nenv:\n global:\n - ADB_INSTALL_TIMEOUT=8\n\n matrix:\n - ANDROID_TARGET=15 ANDROID_ABI=default/armeabi-v7a\n - ANDROID_TARGET=21 ANDROID_ABI=default/armeabi-v7a\n\nandroid:\n components:\n - platform-tools\n - extra\n - android-23\n - build-tools-23.0.1\n\nbefore_script:\n - echo no | android create avd --force -n test -t android-$ANDROID_TARGET --abi $ANDROID_ABI\n - emulator -avd test -no-skin -no-audio -no-window &\n - android-wait-for-emulator\n - adb shell input keyevent 82 &\n\nbefore_install:\n - chmod +x gradlew\n\nscript:\n - ./gradlew clean assemble\n - ./gradlew connectedAndroidTest\n" }, { "path": "LICENSE", "content": "OneDrive SDK Android\n\nCopyright (c) 2015 Microsoft Corporation\n\nAll rights reserved.\n\nMIT License\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "# OneDrive SDK for Android\n\n[ ![Download](https://api.bintray.com/packages/onedrive/Maven/onedrive-sdk-android/images/download.svg) ](https://bintray.com/onedrive/Maven/onedrive-sdk-android/_latestVersion)\n[![Build Status](https://travis-ci.org/OneDrive/onedrive-sdk-android.svg?branch=master)](https://travis-ci.org/OneDrive/onedrive-sdk-android)\n\nIntegrate the [OneDrive API](https://dev.onedrive.com/README.htm) into your Android application!\n\n## 1. Installation\n### 1.1 Install AAR via Gradle\nAdd the maven central repository to your projects build.gradle file then add a compile dependency for com.onedrive.sdk:onedrive-sdk-android:1.3+\n\n```gradle\nrepository {\n jcenter()\n}\n\ndependency {\n // Include the sdk as a dependency\n compile ('com.onedrive.sdk:onedrive-sdk-android:1.3+') {\n transitive = false\n }\n\n // Include the gson dependency\n compile ('com.google.code.gson:gson:2.3.1')\n\n // Include supported authentication methods for your application\n compile ('com.microsoft.services.msa:msa-auth:0.8.+')\n compile ('com.microsoft.aad:adal:1.1.+')\n}\n```\n\n## 2. Getting started\n\n### 2.1 Register your application\n\nRegister your application by following [these](https://dev.onedrive.com/app-registration.htm) steps.\n\n### 2.2 Set your application Id and scopes\n\nThe OneDrive SDK for Android comes with Authenticator objects that have already been initialized for OneDrive with Microsoft accounts and Azure Activity Directory accounts. Replace the current settings with the required settings to start authenticating.\n\nApplication that authenicate via MSA need to have a [scope of access](https://github.com/OneDrive/onedrive-api-docs/blob/master/auth/msa_oauth.md#authentication-scopes) defined to use features on OneDrive. If your application is being used in for OneDrive for business AAD will need the [administrators consent](https://dev.onedrive.com/app-registration.htm) for your application to communicate with OneDrive.\n\nNote that your _msa-client-id_ and _adal-client-id_ should look be in GUID format like `00000000-0000-0000-0000-000000000000`. For legacy MSA application, the _msa-client-id_ should look like `0000000000000000`.\n\n```java\nfinal MSAAuthenticator msaAuthenticator = new MSAAuthenticator() {\n @Override\n public String getClientId() {\n return \"\";\n }\n\n @Override\n public String[] getScopes() {\n return new String[] { \"onedrive.appfolder\" };\n }\n}\n\nfinal ADALAuthenticator adalAuthenticator = new ADALAuthenticator() {\n @Override\n public String getClientId() {\n return \"\";\n }\n\n @Override\n protected String getRedirectUrl() {\n return \"https://localhost\";\n }\n}\n```\n\n### 2.3 Get a OneDriveClient object\n\nOnce you have set the correct application Id and scopes, you must get a **OneDriveClient** object to make requests against the service. The SDK will store the account information for you, but when a user logs on for the first time, it will invoke UI to get the user's account information.\n\n```java\nfinal IClientConfig oneDriveConfig = DefaultClientConfig.createWithAuthenticators(\n msaAuthenticator,\n adalAuthenticator);\n \nfinal DefaultCallback callback = new DefaultCallback(activity) {\n @Override\n public void success(final IOneDriveClient result) {\n // OneDrive client created successfully.\n }\n\n @Override\n public void failure(final ClientException error) {\n // Exception happened during creation.\n }\n };\n \nfinal IOneDriveClient oneDriveClient = new OneDriveClient.Builder()\n .fromConfig(oneDriveConfig)\n .loginAndBuildClient(getActivity(), callback);\n\n```\n\n## 3. Make requests against the service\n\nOnce you have an OneDriveClient that is authenticated you can begin making calls against the service. The requests against the service look like our [REST API](https://dev.onedrive.com/README.htm).\n\n### Get the drive\n\nTo retrieve a user's drive:\n\n```java\noneDriveClient\n .getDrive()\n .buildRequest()\n .get(new ICallback() {\n @Override\n public void success(final Drive result) {\n final String msg = \"Found Drive \" + result.id;\n Toast.makeText(getActivity(), msg, Toast.LENGTH_SHORT)\n .show();\n }\n ...\n // Handle failure case\n});\n```\n\n### Get the root folder\n\nTo get a user's root folder of their drive:\n\n```java\noneDriveClient\n .getDrive()\n .getRoot()\n .buildRequest()\n .get(new ICallback() {\n @Override\n public void success(final Item result) {\n final String msg = \"Found Root \" + result.id;\n Toast.makeText(getActivity(), msg, Toast.LENGTH_SHORT)\n .show();\n }\n ...\n // Handle failure case\n});\n```\n\nFor a general overview of how the SDK is designed, see [overview](docs/overview.md).\n\n## 4. Documentation\n\nFor a more detailed documentation see:\n\n* [Overview](docs/overview.md)\n* [Authentication](docs/authentication.md)\n* [Extensibility](docs/extensibility.md)\n* [Items](docs/items.md)\n* [Collections](docs/collections.md)\n* [Errors](docs/errors.md)\n* [Contributions](docs/contributions.md)\n\n## 5. Issues\n\nFor known issues, see [issues](https://github.com/OneDrive/onedrive-sdk-android/issues).\n\n## 6. Contributions\n\nThe OneDrive SDK is open for contribution. Please read how to contribute to this project [here](docs/contributions.md).\n\n## 7. Supported Android Versions\nThe OneDrive SDK for Android library is supported at runtime for [Android API revision 15](http://source.android.com/source/build-numbers.html) and greater. To build the sdk you need to install Android API revision 23 or greater.\n\n## 8. License\n\n[License](LICENSE)\n\n## 9. Third Party Notices\n\n[Third Party Notices](THIRD PARTY NOTICES)\n\n## 10. Code of Conduct\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n" }, { "path": "THIRD PARTY NOTICES", "content": "This file is based on or incorporates material from the projects listed below\n(Third Party IP). The original copyright notice and the license under which\nMicrosoft received such Third Party IP, are set forth below. Such licenses and\nnotices are provided for informational purposes only. Microsoft licenses the\nThird Party IP to you under the licensing terms for the Microsoft product.\nMicrosoft reserves all other rights not expressly granted under this agreement,\nwhether by implication, estoppel or otherwise.\n\nGson\nCopyright 2008-2011 Google Inc.\n\nProvided for Informational Purposes Only\n\nApache 2.0 License\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use\nthis file except in compliance with the License. You may obtain a copy of the\nLicense at http://www.apache.org/licenses/LICENSE-2.0\n\nTHIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF\nANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED\nWARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,\nMERCHANTABLITY OR NON-INFRINGEMENT.\n\nSee the Apache Version 2.0 License for specific language governing permissions\nand limitations under the License.\n" }, { "path": "build.gradle", "content": "// Top-level build file where you can add configuration options common to all sub-projects/modules.\n\nbuildscript {\n repositories {\n jcenter()\n }\n dependencies {\n classpath 'com.android.tools.build:gradle:1.3.0'\n }\n}\n\nallprojects {\n repositories {\n maven {\n url project.nightliesUrl\n }\n jcenter()\n }\n}\n" }, { "path": "checkstyle.xml", "content": "\n\n\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n" }, { "path": "docs/authentication.md", "content": "# Authenticating with the OneDrive SDK for Android\nThe OneDrive SDK requires that all requests are authenticated with OneDrive. This SDK is built to make it easy to incorporate any application with the authentication provider.\n\n## Authenticators\n\nAuthenticators are provided with the SDK to handle authentication settings.\n\n### Disambiguation Authenticator\nIn order to support as many different users as possible with a single application, we supplied a disambiguation authenticator to provide a user experience that determines which authenticator that user requires. This is the recommended way to distribute your application.\n\n### MSA Authenticator\nUse the **MSAAuthenticator** object for any account that needs to authenticate with the Microsoft account service.\n\nOnce you have your client id, you need to determine the appropriate scopes of authority that your application will need. For a complete list of scopes, consult the OAuth [documentation](https://dev.onedrive.com/auth/msa_oauth.htm#authentication-scopes).\n\n* For applications that need to store data, use the __onedrive.appfolder__ scope and interact with /drive/special/approot.\n* For applications that need to read only the contents of user's OneDrive, request the __onedrive.readonly__ scope.\n\nYour client id should be formatted like `0000000000000000`.\n```java\nfinal MSAAuthenticator msaAuthenticator = new MSAAuthenticator {\n @Override\n public String getClientId() {\n return \"0000000000000000\";\n }\n\n @Override\n public String[] getScopes() {\n return new String[] { \"onedrive.appfolder\" };\n }\n}\n```\n\n### ADAL Authenticator\nUse the **ADALAuthenticator** object for accounts that are hosted on Azure Active Directory.\n\nAfter you've [configured](https://dev.onedrive.com/auth/aad_oauth.htm) your service to allow access to an application for OneDrive, you will need create an **ADALAuthenticator** object with the client id and the redirect url in your application. Your client id should be formatted like `00000000-0000-0000-0000-000000000000`.\n\n```java\nfinal ADALAuthenticator adalAuthenticator = new ADALAuthenticator {\n @Override\n public String getClientId() {\n return \"\";\n }\n\n @Override\n protected String getRedirectUrl() {\n return \"https://localhost\";\n }\n}\n```\n\n## Using Authenticators in your application\nCreating the **OneDriveClient** object enables the silent or interactive login appropriately, but the only functionality that needs be implemented is the sign out user experience. All the provided authenticators will clear preserved tokens after a sign out has completed, ensuring your application has a clean state.\n\n```java\noneDriveClient.getAuthenticator().logout(new ICallback() {\n @Override\n public void success(final Void result) {\n // Handle any state change your application needs to undergo\n }\n ...\n // Handle failure\n```\n" }, { "path": "docs/collections.md", "content": "# Collections in the OneDrive SDK for Android\nThe OneDrive SDK for Android allows you to work with item collections in OneDrive.\n\nCollection information is contained within a `BaseCollectionPage` object, to which there are three core aspects:\n* `getCurrentPage` The list of items within the current page.\n* `getNextPage` The next page request builder. `null` if there are no additional pages.\n* `getRawObject` The json that represents this page response, containing additional data.\n\n## Getting a children collection by expansion\nThere are several navigation properties within the OneDrive service which can be expanded and returned in collections pages. In order to access these properties, the service request needs to call `expand(...)` once the request is issued.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_itemId_|The item id of the item that has the children.|\n|_propertyToExpand_|The name of the navigation property to expand.|\n|_callback_|The callback when the get call is returned.|\n\n```java\nfinal String itemId = \"0000000000000000000000\";\nfinal String propertyToExpand = \"children\";\nfinal ICallback callback = new ICallback {\n @Override\n public void success(final Item result) {\n final IItemCollectionPage page = result.children;\n Toast.makeText(getActivity(), \"Got children\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .buildRequest()\n .expand(propertyToExpand)\n .get(callback);\n```\n\n## Getting a children collection by request\n\nYou can reference navigation properties directly by using the `getChildren()` function within the item's request builder.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_itemId_|The item id of the item that has the children.|\n|_callback_|The callback when the get call is returned.|\n\n```java\nfinal String itemId = \"0000000000000000000000\";\nfinal ICallback callback = new ICallback {\n @Override\n public void success(final IItemCollectionPage result) {\n Toast.makeText(getActivity(), \"Got children\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .getChildren()\n .buildRequest()\n .get(callback);\n```\n\n## Getting the next page\nWhen getting a collection response, the `getNextPage()` function will return the null if there are no more pages, or the request builder to get the next page. By using these request builders you can retrieve all of the items under a collection no matter the size.\n\n|Name|Description|\n|----|-----------|\n|**itemId**|The item id of the item that has the children|\n|**callback**|The callback when the get call is returned|\n\n\n```java\nfinal String itemId = \"0000000000000000000000\";\nfinal ICallback callback = new ICallback {\n @Override\n public void success(final IItemCollectionPage result) {\n // If there was more pages retrieve them too\n if (result.getNextPage() != null) {\n result.getNextPage()\n .buildRequest()\n .get(new ICallback ...);\n }\n Toast.makeText(getActivity(), \"Got children\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .getChildren()\n .buildRequest()\n .get(callback);\n```\n\n## Create a folder\n\nYou can create a folder within an item collection by using the request builders `getDrive`, `getItems`, and `getChildren` with the `create` method.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_folderToCreate_|The folder to create.|\n|_parentId_|The item id for the parent item.|\n|_callback_|The callback when the folder has been created.|\n\n```java\nfinal String parentId = \"0000000000000000000000\";\nfinal Item folderToCreate = new Item();\nfolderToCreate.name = \"NewFolder\";\nfolderToCreate.folder = new Folder();\n\nfinal ICallback callback = new ICallback {\n @Override\n public void success(final Item result) {\n Toast.makeText(getActivity(), \"Created Folder\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(parentId)\n .getChildren()\n .buildRequest()\n .create(folderToCreate, callback);\n```\n" }, { "path": "docs/contributions.md", "content": "# Contributing to the OneDrive SDK for Android\n\nThe OneDrive SDK is avaliable for all manner of contribution. There are a couple of different recommended paths to get contributions into the released version of this SDK.\n\n__NOTE__ A signed a contribution license agreement is required for all contributions, and is checked automatically on new pull requests. Please read and sign the agreement https://cla.microsoft.com/ before starting any work for this repository.\n\n## File issues\n\nThe best way to get started with a contribution is to start a dialog with the owners of this repository. Sometimes features will be under development or out of scope for this SDK and it's best to check before starting work on contribution.\n\n## Submit pull requests for trivial changes\n\nIf you are making a change that does not affect the interface components and does not affect other downstream callers, feel free to make a pull request against the __master__ branch. The master branch will be updated frequently, and the gradle dependency will be kept closely inline with it.\n\nRevisions of this nature will result in a 0.0.X change of the version number.\n\n## Submit pull requests for features\n\nIf major functionality is being added, or there will need to be gestation time for a change, it should be submitted against the __feature__ branch.\n\nRevisions of this nature will result in a 0.X.X change of the version number.\n" }, { "path": "docs/errors.md", "content": "# Handling errors in the OneDrive SDK for Android\n\nErrors in the OneDrive SDK for Android behave just like errors returned from the service. You can read more about them [here](https://github.com/OneDrive/onedrive-api-docs/blob/master/misc/errors.md).\n\nAnytime you make a request against the service there is the potential for an error. You will see that all requests to the service can return an error. The errors are returned as `ClientException`, with possible subclasses `ClientAuthenticationException` and `OneDriveServiceException` which your application will want to handle.\n\n## Checking the error\n\nThere are a few different types of errors that can occur during a network call. We have provided some helper methods to make it easy to check what kind of error occurred. These error types are defined in [OneDriveErrorCodes.java](../OneDriveSDK/src/main/java/com/onedrive/sdk/core/OneDriveErrorCodes.java).\n\n```java\ntry {\n // ...\n} catch (final ClientExcepion ex) {\n if (ex.isError(OneDriveErrorCodes.AuthenticationCancelled)) {\n // Handle the specific authentication cancelled case\n }\n // Handle the authentication exception\n}\n```\n\n### Client authentication exceptions\n\nThese exceptions represent errors during the authentication flow. The two exceptions are `AuthenticationCancelled` for interactive user cancelation and `AuthenticationFailure` for a problem with the underlying authentication system.\n\n### OneDrive service exceptions\n\nThese are exceptions from the OneDrive service, that contain extra error diagnostic information. The standard error codes should give your application more than enough detail to message users. However, there is useful debug information contained in the response.\n\n__Note__: Sometimes you might see a `OneDriveFatalServiceException`. If you do, please open a [new issue](https://github.com/OneDrive/onedrive-sdk-android/issues/new) so that we can fix it.\n" }, { "path": "docs/extensibility.md", "content": "# Extensibility with the OneDrive SDK for Android\n\nThe OneDrive SDKs are built to allow for customization and enhancement over time while maintaining backwards compatibility.\n\n## Contribution\n\nContributions are welcome on the OneDrive SDKs. To contribute, please open a [new issue](https://github.com/OneDrive/onedrive-sdk-android/issues/new) to start a dialog with the team about what you are creating.\n\n__Note__ There is an area of the SDK which is not available for direct contribution, which is anything under the com.onedrive.sdk.generated package. These components are built using automated tools and will be overwritten. As this tooling matures this process will be open to contributions as well.\n\n## Minor modification\n\nOneDrive's service is described in accordance with OData. This service description is [available](https://api.onedrive.com/v1.0/$metadata) and continuously updated as new features become available. However, the OneDrive $metadata description does not encompass all features and functionality. To aid with elements of the service that are not described here, the `com.onedrive.sdk.extensions` package was created. The files are all generated automatically but will not be overwritten. Some functionality is already exposed in this manner, and here is example using the `OneDriveClient`.\n\nThe class hierarchy:\n\n```java\nclass OneDriveClient extends BaseOneDriveClient implements IOneDriveClient {}\nclass BaseOneDriveClient extends BaseClient implements IBaseOneDriveClient {}\nclass BaseClient implements IBaseClient {}\n```\nThe companion interface hierarchy:\n\n```java\ninterface IOneDriveClient extends IBaseOneDriveClient {}\ninterface IBaseOneDriveClient extends IBaseClient {}\ninterface IBaseClient {}\n```\n\n- The `BaseClient` layer represents the under-pinnings of an OData client. These objects are open for modification and additions.\n- The `BaseOneDriveClient` layer is supplied by the OData $metadata description, and is automatically populated with the features described therein.\n- The `OneDriveClient` layer is where extra functionality above and beyond the $metadata description can be placed.\n\nThe OneDrive team keeps the interfaces up to date to detect backwards compatibility breaking changes.\n\nMost classes generated at this 'top tier' will be empty to support future modification, and OneDriveClient already has been modified to support the 'drive()' behavior. 'drive' is exposed to shorten the `{service-root}/drives/{default-drive-id}` into `{service-root}/drive`.\n\n## Major dependencies\n\nDuring the construction of the `IOneDriveClient` object an `IClientConfig` is used. This configuration determines how the internal functionality of the SDK is supplied. By creating a new `IClientConfig` implementation the components can be modified or wholly replaced to best meet the needs of the caller.\n\n### IHttpProvider\n\nProvides the http fabric that is used for all network requests within the SDK.\n\n### IAuthenticator\n\nProvides the facilities to authenticate users and supply an authentication token for requests to the service.\n\n### ISerializer\n\nSerializes and deserializes the structured object from the service.\n\n### IExecutors\n\nHandles executing tasks for the SDK on foreground and background threads.\n\n### ILogger\n\nThe logging system used by the SDK to report debug and error messages for debugging purposes.\n" }, { "path": "docs/items.md", "content": "# Items in the OneDrive SDK for Android\nItems in the OneDrive SDK behave just like items through the OneDrive API. All actions on items described in the OneDrive API are available through the SDK. For more information, see the [Items Reference](https://dev.onedrive.com/README.htm#item-resource).\n\nThe examples in this topic all use a previously created `oneDriveClient` object.\n\n* [Get an item](#get-an-item)\n* [Delete an item](#delete-an-item)\n* [Upload a file](#upload-a-file)\n* [Download a file](#download-a-file)\n* [Move an item](#move-an-item)\n* [Rename an item](#rename-an-item)\n* [Copy an item](#copy-an-item)\n* [Upload a large file](#upload-a-large-file)\n\n## Get an item\n\nTo get an item, you construct request builders `getDrive` and `getItems`, you call `buildRequest` to build the request, and then make a final call to `get`.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_itemId_|The item id of the item to retrieve.|\n|_callback_|The callback for when the get call is returned.|\n\n#### Example\n\n```java\n//Enter the itemId here.\nfinal String itemId = \"0000000000000000000000\";\nfinal ICallback callback = new ICallback() {\n @Override\n public void success(final Item result) {\n Toast.makeText(getActivity(), \"Got item\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .buildRequest()\n .get(callback);\n```\n\n## Delete an item\n\nTo delete an item, you construct request builders to get the item you want to delete, and then call `delete` on the item.\n\n#### Parameters\n\n|Name|Description|\n|--------------|-----------|\n|_itemId_|The item id of the item to delete.|\n|_callback_|The callback for when the get call is completed.|\n\n#### Example\n\n```java\nfinal String itemId = \"0000000000000000000000\";\nfinal ICallback callback = new ICallback() {\n @Override\n public void success(final Void ignored) {\n Toast.makeText(getActivity(), \"Deleted item\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .buildRequest()\n .delete(callback);\n```\n\n## Upload a file\n\nTo upload a file, you chain together build requests in this order: `getDrive`, `getItems`, `getChildren`, `byID`, and then `getContent`. You then call `buildRequest` to build the requests, and finally, `put` to complete the upload.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_filename_|The name of the file to upload.|\n|_fileContents_|The byte array (byte[]) that contains the file contents.|\n|_callback_|The callback when the file is uploaded, as well as progress reported.|\n\n#### Example\n\n```java\nfinal String filename = \"The Filename.txt\";\nfinal byte[] fileContents = new byte[] { /* The File contents to upload */};\nfinal IProgressCallback callback = new IProgressCallback() {\n public void success(final Item item) {\n Toast.makeText(getActivity(), \"Item uploaded\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle progress\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(ItemId)\n .getChildren()\n .byId(filename)\n .getContent()\n .buildRequest()\n .put(fileContents, callback);\n```\n\n## Download a file\n\nTo download a file, you construct the request builders `getDrive`, `getItems`, and `getContent`, and then call `buildRequest` to build the request. Finally, you call `get` to retrieve the item to download.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_itemId_|The item id of the item to download.|\n\n#### Example\n\n```java\nfinal String itemId = \"0000000000000000000000\";\n\nfinal InputStream inputStream = oneDriveClient\n .getDrive()\n .getItems(itemId)\n .getContent()\n .buildRequest()\n .get();\n// Use the input stream\n// Close the input stream\n\n```\n\n## Move an item\n\nTo move an item, construct request builders to get the item with `getItem`, and then call `update` with the new location.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_newParentId_|The new parent's item id.|\n|_itemId_|The item id of the item to move.|\n|_newLocation_|The specific aspects of the item to update.|\n|_callback_|The callback when the item update has returned.|\n\n#### Example\n\n```java\nfinal String newParentId = \"0000000000000000000000\";\nfinal String itemId = \"0000000000000000000000\";\nfinal Item newLocation = new Item();\nnewLocation.parentReference = new ItemReference();\nnewLocation.parentReference.id = newParentId;\n\nfinal ICallback callback = new ICallback() {\n @Override\n public void success(final Item result) {\n Toast.makeText(getActivity(), \"Update the item location\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .buildRequest()\n .update(newLocation, callback);\n```\n\n## Rename an item\n\nLike all other operations, you rename an item by constructing request builders `getDrive` and `getItems` on the item, and then calling `update` with the new name.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_newItemName_|The new name for the item.|\n|_itemId_|The item id of the item to rename.|\n|_newName_|The specific aspects of the item to update.|\n|_callback_|The callback when the item update has returned.|\n\n#### Example\n\n```java\nfinal String newItemName = \"My File.txt\";\nfinal String itemId = \"0000000000000000000000\";\nfinal Item newName = new Item();\nnewName.name = newItemName;\n\nfinal ICallback callback = new ICallback() {\n @Override\n public void success(final Item result) {\n Toast.makeText(getActivity(), \"Update the item name\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n}\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .buildRequest()\n .update(newName, callback);\n```\n\n## Copy an item\n\nCopy requests are processed asynchronously on the service, so the pattern is slightly different, and can require multiple sets of requests.\n\n### Starting a copy request\n\nYou create a copy request for an item by constructing request builders `getDrive`, `getItems` and 'getCopy' on the item, and then calling `create` to start the request.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_itemId_|The item id of the item to copy.|\n|_copiedItemName_|The name for the copied item.|\n|_parentId_|The parent's item id for the copied item.|\n|_callback_|The callback when the copy request has started.|\n\n#### Example\n\n```java\nfinal String itemId = \"0000000000000000000000\";\nfinal String copiedItemName = \"My File Copy.txt\"\nfinal String newParentId = \"0000000000000000000000\";\n\nfinal ItemReference parentReference = new ItemReference();\nparentReference.id = newParentId;\n\nfinal ICallback> callback = new ICallback>() {\n @Override\n public void success(final AsyncMonitor itemAsyncMonitor) {\n Toast.makeText(getActivity(), \"Started the copy session\", Toast.LENGTH_LONG).show();\n }\n ...\n // Handle failure\n};\n\noneDriveClient\n .getDrive()\n .getItems(itemId)\n .getCopy(copiedItemName, parentReference)\n .buildRequest()\n .create(callback);\n```\n\n### Waiting for a copy request to finish\nThe result from the copy requests creation is a monitor that can be checked for status updates, return result of the operation, and automatically poll for the result.\n\nMost applications will want to get the result to the user as soon as possible via a polling approach, the following shows how to get the resulting item from with a process notifications.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_millisBetweenPoll_|The time in milliseconds between progress updates.|\n|_asyncMonitor_|The name for the copied item.|\n|_callback_|The callback when the copy request has finished and progressed.|\n\n#### Example\n\n```java\nfinal int millisBetweenPoll = 1000; // 1 second\nfinal AsyncMonitor asyncMonitor = ...;\n\nfinal IProgressCallback callback = new IProgressCallback() {\n public void success(final Item item) {\n Toast.makeText(getActivity(), \"Item copied!\", Toast.LENGTH_LONG).show();\n }\n\n public void progress(final int progress, final int progressMax) {\n Toast.makeText(getActivity(), \"Item copy process \" + progress, Toast.LENGTH_SHORT).show();\n }\n ...\n // Handle failure\n}\n\nasyncMonitor\n .pollForResult(millisBetweenPoll, callback);\n\n```\n\n## Upload a large file\n\nUploading a large file to OneDrive needs create upload session and uploading bytes to the session url.\n\n#### Make create session request\n\nYou create a create session request for an item by constructing request builders `getDrive`, `getRoot`, `getItemWithPath`, `getCreateSession`, `buildRequest` on the item, and then calling `post` to start the create session request. The response is an upload session object which you call `createUploadProvider` of the object to create an upload provider which handles large file uploading.\n\n#### Parameters\n\n|Name|Description|\n|----|-----------|\n|_itemPath_|The path to the file.|\n|_chunkedUploadSessionDescriptor_| The chunked upload session descriptor.|\n|_oneDriveClient_|The one drive client.|\n|_fileStream_|The input file stream.|\n|_fileSize_|The size of the file.|\n|_uploadType_|The upload class type.|\n|_uploadOptions_|The upload options.|\n|_callback_|The upload callback.|\n|_chunkSize_|The chunk size for each upload chunk, default is 5MiB.|\n|_maxRetry_| The max retry times for each upload chunk, default is 3.|\n\n\n#### Example\n\n```java\nfinal String itemPath = \"documents/file to copy.txt\";\nfinal Option uploadOptions = new QueryOption(\"@name.conflictBehavior\", \"fail\");\nfinal int chunkSize = 640 * 1024; //must be the multiple of 320KiB\nfinal int maxRetry = 5;\n\nfinal IProgressCallback callback = new IProgressCallback() {\n @Override\n public void progress(long current, long max) {\n dialog.setProgress((int) current);\n dialog.setMax((int) max);\n\n }\n\n @Override\n public void success(Item item) {dialog.dismiss();\n Toast.makeText(getActivity(),\n application\n .getString(R.string.upload_complete,\n item.name),\n Toast.LENGTH_LONG).show();\n refresh();\n }\n\n @Override\n public void failure(ClientException error) {\n dialog.dismiss();\n if (error.isError(OneDriveErrorCodes.NameAlreadyExists)) {\n Toast.makeText(getActivity(),\n R.string.upload_failed_name_conflict,\n Toast.LENGTH_LONG).show();\n } else {\n Toast.makeText(getActivity(),\n application\n .getString(R.string.upload_failed,\n filename),\n Toast.LENGTH_LONG).show();\n }\n }\n}\n\noneDriveClient\n .getDrive()\n .getRoot()\n .getItemWithPath(itemPath)\n .getCreateSession(new ChunkedUploadSessionDescriptor())\n .buildRequest()\n .post()\n .createUploadProvider(oneDriveClient, fileStream, fileSize, Item.class)\n .upload(Collections.singletonList(uploadOptions),\n callback,\n chunkSize,\n maxRetry);\n```\n" }, { "path": "docs/overview.md", "content": "# Overview for the OneDrive SDK for Android\nThe OneDrive SDK for Android is designed to look just like the OneDrive API.\n\n## OneDriveClient\nA `OneDriveClient` is always associated with a authentication session. This can be created by using the **Builder** subclass of the `OneDriveClient` implementation, `loginAndBuildClient(..)`. All requests use this object to send information to the service and it should be constructed once for your applications life cycle.\n\n## Resource model\nResources, like [items](/docs/items.md) or drives, are represented by `Item` and `Drive`, respectively. These objects contain properties that represent the properties of a resource. These objects can't make calls against the service-they are purely models.\n\nTo get the name of an item you address the `name` property. It is possible for any of these properties to be null at any time. To check if an item is a folder you address the `folder` property. If the item is a folder an `ODFolder` facet on that object will be returned, and it contains all of the properties described by the [folder](https://github.com/OneDrive/onedrive-api-docs/blob/master/facets/folder_facet.md) facet.\n\nSee [Resource model](https://github.com/onedrive/onedrive-api-docs/#resource-model) for more info.\n\nThe resources that are generated map to the json model described by the $metadata service document. There are items that might not be exposed because they expire very quickly or represent functionality that is not featured in this SDK as of yet. To access these fields use `getRawObject()` on the model items and access the specific properties that are not in the model.\n\n## Issuing requests\nTo make requests against the service, first build a request with **RequestBuilder** and then build it into a Request object, which is then sent against the service. This follows the URL scheme that the OneDrive API uses for all its resources.\n\n### Request builders\nTo generate requests you chain together calls on request builder objects. You get the first request builder from the `OneDriveClient` object. To get a drive, create a request builder by calling **OneDriveClient.getDrive**.\n\n|Task | SDK | URL |\n|:---------------|:-----------------:|:--------------------------------|\n|Get a drive | `oneDriveClient.getDrive()` | GET api.onedrive.com/v1.0/drive/|\n\n`getDrive` will return an `IDriveRequestBuilder` object. From `getDrive`, you can continue to chain the requests to get everything else in the API, like an item.\n\n|Task | SDK | URL |\n|:---------------|:----------------------------------:|:------------------------------------------|\n|Get an item | `oneDriveClient.getDrive().getItems(\"1234\")` | GET api.onedrive.com/v1.0/drive/items/1234|\n\n\nHere, `oneDriveClient.getDrive()` returns an `IDriveRequestBuilder` that contains a method `getItems(...)` to get an `IItemRequestBuilder`.\n\nSimilarly, to get thumbnails, you chain together the request builders `getThumbnails` and `getItems`.\n\n|Task | SDK | URL |\n|----------------|--------------------------------|--------------------------|\n| Get thumbnails | `... .getItems(\"1234\").getThumbnails()` | .../items/1234/thumbnails|\n\n\nHere, `oneDriveClient.getDrive().getItems(\"1234\")` returns an `IItemRequestBuilder` that contains the method `getThumbnails()`.\n\nThis returns a collection of [thumbnail sets](https://github.com/OneDrive/onedrive-api-docs/blob/master/resources/thumbnailSet.md). To index the collection directly you can call:\n\n|Task | SDK | URL |\n|-------------------|-------------------------------------|----------------------------|\n| Get thumbnail Set | `... .getItems(\"1234\").getThumbnails(\"0\")` | ...items/1234/thumbnails/0 |\n\nTo return a thumbnail set, and to get a specific [thumbnail](https://github.com/OneDrive/onedrive-api-docs/blob/master/resources/thumbnail.md), you can add the name of the thumbnail to the URL like this:\n\n|Task | SDK | URL |\n|-----------------|-----------------------------|------------------------|\n| Get a thumbnail | `... .getThumbnails(\"0\").getThumbnailSize(\"small\")` | .../thumbnails/0/small |\n\n### Requests\nOnce you have constructed the request you call the `buildRequest()` method on the request builder. This will construct the request object needed to make calls against the service.\n\nFor an item you call:\n\n```java\nfinal IItemRequest itemRequest = OneDriveClient.getDrive().getItems(\"1234\").buildRequest();\n```\n\nAll request builders have a `buildRequest()` method that can generate a `IHttpRequest` object. Request objects may have different methods on them depending on the type of request. To get an item you call:\n\n```java\nitemRequest.get(new ICallback{\n @Override\n public void success(final Item result) {\n // This will make the network request and return the item\n }\n @Override\n public void failure(final ClientException ex) {\n // or an error if there was one\n }\n});\n```\n\nYou could also chain this together with call above :\n```java\n\nOneDriveClient.getDrive().getItems(\"1234\").buildRequest().get(new ICallback{\n @Override\n public void success(final Item result) {\n // This will make the network request and return the item\n }\n @Override\n public void failure(final ClientException ex) {\n // or an error if there was one\n }\n});\n```\n\nSee [items](/docs/items.md) for more info on items and [errors](/docs/errors.md) for more info on errors.\n\n## Query options\n\nIf you only want to retrieve certain properties of a resource, you use `select` specify them. Here's how to get only the names and ids of an item:\n\n```java\noneDriveClient.getDrive().getItems(\"1234\").buildRequest().select(\"name,id\").get(new ICallback() {\n @Override\n public void success(final Item result) {\n // The item object will have null properties for everything except name and id\n }\n});\n```\n\nTo expand certain properties on resources you can call a similar `expand` method, like this:\n\n```java\noneDriveClient.getDrive().getItems(\"1234\").buildRequest().expand(\"thumbnails\").get(new ICallback() {\n @Override\n public void success(final Item result) {\n // the item object will have collection page of thumbnails for its thumbnails property if thumbnails exist.\n }\n});\n```\n\n## Additional request options\n\nIf you need to include more specific behavior during a request, there are `Option` objects that you can add when calling `buildRequest`. See a detailed list of query parameters in the [OneDrive API optional query parameters](https://dev.onedrive.com/odata/optional-query-parameters.htm) documentation.\n\nHere's an example of how to add an additional query parameter to sort the returned collection page results by size:\n\n```java\nfinal List