Trying to find some Objective-C API 1 Functionality...

[Keith B.7]

Hello,

I'm starting to convert my Objective-C Core API 1 code to API 1 and am having a few problems finding equivalent functionality in some areas. Because there's no language-specific transition guide, the only way of trying to map things across is to go through the framework header files for a number of things, and there are a *lot* of header files now. Even so, there are a number of methods I would expect to be there but cannot find.

1. Cancel all requests: in API 1, if the use cancels a sync, I could call -cancelAllRequests on DBRestClient. I can find no equivalent in API 2. Is the expection that I maintain my own array of all tasks created and iterate through them to cancel them (presumably removing them from the array in the result callback)? Or is there a simpler solution to cancelling all requests?

2. There is no equivalent of DBSession's -isLinked to quickly check whether Dropbox has already been linked. From wehat I can see, you now achieve this by checking whether DropboxClientsManager returns nil for -authorizedClient or not, is that correct?

3. In API one, to create a session you needed to pass in the app key, the app secret and the root type (full access or application directory). In API 2, it seems that you only need to pass in the app key. Is the app secret and root type no longer used?

4. Is there no way to use -getMetaData to list the contents of a directory any more? In API 1, I could call -getMetaData on a folder path. In the delegate method, I could use the -contents array property of the metadata object returned to iterate through child metadata items, thus quickly getting a list of a folder's children. This doesn't seem possible in API 2 - it seems that you now have to use -listFolder: and keep going as long as -hasMore returns YES. (On this: the callback conventions get very messy here, because you have to call -listFolderContinue: from within a callback, leading to callbacks within callbacks...)

5. Talking of getting the contents of meta-data, is there no longer a way to get a list of the subdocuments from a meta-data item. DBMetadata had the -contents NSArray property, but I can find no equivalent property on DBFILESMetadata (or its DBFILESFolderMetadata subclass) in API 2.

6. Likewise, how do I determine if a metadata item is a directory or not? In API 1, DBMetadata had the -isDirectory property. I can find no such property in API 2. The only way I can find of determining this is to check the class ([metadata isKindOfClass[DBFILESFolderMetadata class]]), but that is very clumsy so I'm sure I'm missing something obvious there. Have I missed a property somewhere?

7. It's not obvious how to call -listFolder: on the root. My instinct was to use @"/" or nil for the folder name, but the latter caused an error and the latter caused a crash. It transpires that you need to use an empty string (@"") - that might be worth noting in the header file.

8. In API 1, I wrote a category on DBRestClient that could call -loadDelta: with a subpath. This called "/delta" with a "path_prefix" set. I believe the equivalent of doing this in API 2 is: a) Save the cursor returned from DBFILESListFolderResult (after hasMore.boolValue has evaluated to NO); b) At a later date, pass that cursor into -listFolderContinue:. As I understand it, this will return a list of files changed within the folder since the last call. I assume the cursor encodes the various settings originally used on the -listFolder: call? That is, I assume that if you called -listFolder: with recursive set to YES, any time you call -listFolderContinue: in the future using that cursor or the cursor returned from successive calls to -listFolderContinue:, it will check recursively for any changes in the files and folders contained inside the folder originally specified by -listFolder: and all of its subdirectories and ancestors. Is this assumption safe?

Incidentally, why was the decision taken to use an NSNumber for boolean values? This goes against Objective-C standards and makes it very easy to introduce bugs. For instance, instead of writing listResult.hasMore, I have to be very careful to type listResult.hasMore.boolValue.

Many thanks!

Keith

[Greg-DB]

Hi Keith,

Thanks for the detailed writeup!

1. That's correct, while the API v2 Objective C SDK lets you cancel specific requests, it doesn't have a method for cancelling all open requests like the v1 Core SDK did. I'll pass this along as a feature request.

2. That's correct.

3. API v2 only uses OAuth 2, where the app secret is not required in client-side apps. The root parameter is also no longer necessary. 

4. That's right, the API v2 getMetadata method doesn't return folder contents like the API v1 metadata method did. You should use listFolder as you mentioned. This method handles folders with many files better than the v1 metadata method did, and enables you to efficiently stay up to date with further changes, via use of the cursor and listFolderContinue.

5. Yes, building on #4, especially to better handle large listings, the contents aren't directly populated in metadata objects.

6. Correct, API v2 does make use of (sub-)classes like this, so you should use isKindOfClass to check objects. 

7. Thanks for the feedback! That's correct, in API v2 root is represented as the empty string.

8. That's correct, the cursor encodes that original path.

9. There's a note about NSNumber here in the readme here.

Hope this helps! 

[Keith B.7]

Hi Greg,

Great, many thanks for the thorough reply!

For (2) and (6) I'll probably write a couple of category methods to simplify those checks, then. And d'oh, I see that the -isKindOfClass: question is in fact already answered in the "Responding to edge cases" section. I'd missed that.

So, in the same vein, I understand that now, instead of having an -isDeleted flag on the meta data object, we check for the meta-data object being of the DBFILESDeletedMetadata subclass.

On (8), I assume the recursion flag is also encoded in the cursor?

On (9), I had read that note, but was curious as to why nullability needs to be represented in checks such as .hasMore at all. Not a big deal, it's just that the unconventional nature of having an -is or -has method return an NSNumber rather than a BOOL needs careful attention.

Anyway, thanks again. So far it looks as though it shouldn't be too hard to transition everything; it's just going to take some careful restructuring and browsing of the header files!

All the best,

Keith

[Greg-DB · Accepted solution]

No problem, and yes, the recursive parameter is also in encoded in the cursor.