Transcript
[ Crowd Sounds ]
[ Applause ]
>> Good morning, and welcome.
My name is Jean-Gabriel.
I hope you've been having a
great week.
We're here to talk about file
providers, the technology
between, behind the new Files
app.
We're going to see what file
providers are and what new APIs
in iOS 11 allow you to enumerate
files from the cloud down to the
device, to modify those files on
the device and up to the cloud,
and to customize your file
provider to expose your
non-standout features.
So file providers have been
around since iOS 8, and at the
core, they materialize files for
applications.
So applications may keep
preferences to files that are
provided by file providers, and
when they need the files, file
providers fulfill the promises.
But we are here today to talk
about the new APIs, the APIs for
enumerating files from the cloud
down to the device.
So the audience for this talk is
people who have servers out
there with user documents on
those servers and want to bring
those documents to iPad and
iPhone.
So let's look at the Files app.
The Files app is a thin wrapper
around a new piece of system UI
called the document browser that
is pretty ubiquitous in the
system.
It is where the user, where
users find, organize, share,
open documents.
File providers appear here under
Locations.
These are the entry points to
your cloud storage, and iCloud
Drive is one of them.
That's good.
That means that the APIs that we
are going to go through today
are implemented by iCloud Drive,
really well tested, and you have
a reference point if you're
wondering about the expected
behavior of, say, renaming your
file when there's already a file
with the same name and the same
folder, or you can just try it
out in iCloud Drive and see how
it's supposed to behave.
It also means that your
documents, being in a file
provider just like iCloud Drive,
are first-class citizens on the
OS.
They're available everywhere
really prominently just as
iCloud Drive documents.
Actually, on this shot, iCloud
Drive is at the top, but the
user may want to reconfigure
that however they want to really
leave on your file provider.
There's on file provider in
there that I just want to make a
passing mention of.
On My iPad, that is the only
local file provider.
That is the only file provider
that doesn't show files that are
in the cloud somewhere, and it's
for apps to expose their
document, their local document
storage to other applications.
So let's see where the document
browser fits on the platform.
Well, it sits right below the
document-based applications --
the Files app that we just saw;
all the iWork apps, which
[rewrote] their document browser
to be that new piece of system
UI; and all the third-party
[adopters] in iOS 11.
On the other side of the
document browser UI are the file
providers, and the file
providers will provide files to
the system UI while the
document-based applications
pick, open one of those
documents from whichever file
provider, edit, or create new
documents.
So the reason why document-based
applications are going to adapt
is that this is a single API to
get access to all the places
where their users have their
documents.
Replaces the multiple SDKs that
they have had to adapt to until
now.
The reasons for file providers
to adopt is the privacy model,
which is really awesome here.
So document-based applications
open documents one at a time.
It's totally user-gated access.
The system UI is out of process.
Document-based applications
cannot know which files exist
next to the file that was picked
or even which file providers are
installed until the user picks
one of the documents.
There are two key APIs here:
UIDocumentBrowser
ViewController, which is in the
SDK of the document-based
applications, and
NSFileProviderExtension.
We're not here to talk about
UIDocumentBrowser
ViewController.
That was covered in the session
yesterday that I invite you to
go watch if you missed it about
building document-based
applications.
We are here to talk about the
other end of this,
NSFileProviderExtension.
So let's look again at the Files
app.
There are two main ways for the
user to go and interact with his
documents, and those correspond
to two tabs in the app.
The first tab is the Browse tab.
That is where the user goes to
find content in your cloud and
bring it down to the device.
In this mode, your file provider
extension acts as a pipe between
the system UI and your servers.
It's not even expected to work
offline, really.
Once the user has selected those
documents in the Browse tab,
they become available in the
Recents tab.
The Recents tab is the other
mode, and it is a flat list of
documents that come from the
very sources of documents and
are really relevant to the user.
That is where the user is going
to go look for the file he wants
to open.
And sure enough, it's going to
be there.
So two tabs -- Browse, Recents.
The Browse tab is for putting
new content for file providers
online for, folder, online to
folders and pick a document.
The Recents tab shows what we
call the working set, and we're
going to talk about the working
set now.
So it's not folder based and it
spans multiple file providers.
And in a working set, there are
these documents.
So recently-opened documents or
used document, favorites, tag
documents and folders, documents
shared through or by the user,
documents that were previously
downloaded to the device and are
available offline, and
recently-deleted documents.
For the user experience to be
consistent across file provider,
we ask you to put all those
files in the working set.
But you have domain-specific
knowledge.
You know what's relevant to the
user.
So you might choose to add more
to the working set, if you so
want.
However, caveat: We are actually
Smart Caching the working set on
the device.
So once something is in the
working set, you'll have to keep
it in sync.
I'll get back to that.
So in the document browser in
the Recents tab, you'll see the
working set.
And each file provider may
contribute different documents
to the working set.
We don't do that at display
time.
If we had to merge the list of
documents as they come in from
the different file provider
extensions when the UI is
onscreen, you'd have weird
animations, visual glitches.
So we don't do that.
Instead, what we do is we
enumerate a working set index
that is kept by the system when
the UI comes up.
And your file provider
extensions are not even invoked
at all.
We're going to talk about how
that index is built.
So the index is local and on the
device.
It is the aggregation of the
working set from the different
file providers.
Because the index is local, it
means the index is available
offline.
It means that offline, if I
bring up that UI, the document
browser, I will see my recent
documents.
That doesn't mean that all the
documents are local on the
device at all time and offline.
It means that [enough data] to
build the UI is cached to the
device.
Because the index is local and
available offline, it is also in
Spotlight.
So the system index is for you,
the working set in Spotlight,
and users may pick a document in
Spotlight, and that will wake
your file provider extension at
that time.
So let's talk about how you
provide files to the working set
index, which happens in the
background before the document
browser comes up.
The first thing that you are
going to have to do is sync your
working set from your servers
down to the device.
So watch those file provider
extension boxes here.
The, we're asking you to keep a
database of the metadata for all
the files in the working set on
the device.
And actually, do sync both ways
because there are local changes
and [remote] changes.
The second step is that the
working set, the system is going
to drive the enumeration of the
working set from your file
providers to build the index.
Happens in the background.
And then at a later time, when
the UI comes up, the system will
enumerate the working set index
without waking your file
provider extension to show the
Recents in the document browser.
All right, we're asking you to
do a lot of things here.
We're asking you do sync and to
do sync of a partial set of your
documents.
If you can't do partial sync,
you might want to consider
syncing all the user's documents
down to the device.
You're going to hit scaling
issues, so think carefully about
what you do there.
OK, what we saw to this point is
that there are two ways to
browse documents.
There is a Recents tab that
shows the working set, which is
synced in the background to the
device, and there is a Browse
tab, which is based on the
online enumerations of folders.
And I'm going to call Pierre to
show you how to create a file
provider extension now.
Thank you, Pierre.
>> Thank you, Jean-Gabriel.
So let's talk about creating a
file provider extension.
First, we're going to see how to
create the project, then how to
provide a single item, then
enumerate a list of items, and
then I will [hand over to Johannes] who is
going to go through you, with
you and [to see how] to modify
item, provide custom action, and
as well as do something very,
very powerful, which is provide
services to third-parties.
What does that mean?
It means that your file provider
extension can provide its own
API, so you own API to other
third-party's app.
This is really cool, so you
probably want to stay until you
see this or play it online
later.
Creating a file provider
extension is really simple if
you start from scratch.
So there is a Xcode template,
File Provider Extension.
Just click on it.
Boom, it's done.
And then the real work begin.
You have to subclass
NSFileProviderExtension.
If you already have an existing
file provider extension, in that
case, what you should do is add
the support enumeration key to
your Info.plist.
That will tell the system, look,
you probably want to take this
file extension and use the new
UI to render my document.
So the big picture during this
file provider extension subclass
that you should build.
Your file provider extension
subclass [role] is to vend
the item metadata by
implementing or returning object
implementing the NSFileProvider
protocol, NSFileProviderItem
protocol.
Those item are identified by a
string that you provide and are
materialized on disk through
file URL.
The folder contents of your file
provider is exposed by
implementing what we call an
NSFileProviderEnumerator.
That sounds complicated, but
it's not.
So, and before jumping into the
very detail, let's have a big
picture of the tasks we've been
going through and see what the
anatomy of a file provider
extension is going to look like
after we build all this.
So first task, we need to
provide the metadata for a given
item identifier.
That's straightforward if you
have a database, so you probably
want to have a database.
Then, you need to map URLs to
item identifiers.
That's probably a semicolon in
your database.
Last, you're in charge of
managing the disk storage,
whether the data corresponding
to a file is local or not.
That's the second piece of your
file provider extension.
And inside the disk storage, of
course, file can be there or
not, as shown on screen behind me.
OK, so we've seen the anatomy.
Let's jump in and provide an
item.
What does it mean to provide an
item?
First, you need to provide a
file URL.
Then, file contents, metadata,
and thumbnail for your item.
That's it.
Why do you need to provide a
file URL, you might ask?
Well, file provider manipulates
file provider item and file
provider item identifier, not
file URLs directly.
However, document-based apps do
consume file URLs, so we need to
bridge between the two, so let's
take an example.
When the user taps on the file
in the File app, the File app
only has access to your item
identifier at that point.
So before calling the
document-based app, it's
actually going to call into your
file provider extension
subclass.
The method urlForItem with
identifier is going to get
called, and so you will look in
your database, figure out the
URL for the given item
identifier, and, boom, you'll
return into the document-based
app.
Not you, the system does it
for you, but you return it to
the system which returns it to the
document-based app, and you're
done.
At that point, the
document-based app opened a file
by URL.
Under the hood, I was
talking about the database to
the URL to item identifier
mapping.
One thing you might want to do
is to actually start the item
identifier inside the file URL.
It's very convenient because you
can avoid database lookup if you
do that and you can tag items
between renames.
Last tidbit, you probably want
to keep a flat list in your disk
storage.
You don't need to replicate the
folder hierarchy because this is
quite complicated, and so you
can avoid it, so please do.
So you might say, hey, Pierre,
so we have the file URL, but
what about the file content?
Because I did not know they're
missing at that point.
So of course, we should look
into that.
So you can open the file by, so
when the document-based app
opened your app, it opened the
file by URL.
But it's not doing that state.
Like, it should use
NSFileCoordinator and read using
a file coordination request.
That is something apps using UI
documents do for free, so when
that happens, your file provider
extension is called.
More specifically, in your
subclass, startProvidingItem at
URL with completionHandler is
going to get called.
When you receive such a call, you look
into your disk storage.
You figure out that the item is not
there.
So you go in your server, through
NSURLSession most likely, and
you download the file.
The download completes.
The file is moved into your disk
storage.
Now, you can call the
completionHandler that is going
to grant the coordination to the
document-based app.
And at that point, the file is
opened.
Cool. So what happens if you
want this a second time?
Because this time, the file is
there.
But there is still going to be a
file coordinator reader request
issued.
And at that point, this is
pretty cool.
Your file provider extension
subclass is going to get called
again.
So that's very powerful for you
to track usage on your files.
But this time, the file is here,
so what do you need to do?
Well, you just
completionHandler, and you're
done.
It's very powerful, but at the
same time, it means that your
file provider extension might
be, might delay file loading.
So you better be fast when you
implement startProvidingItem if
the file is already local.
OK, so the coordination is
granted, and you've seen this
before.
The file is now opened.
Second part.
In the Files app, the metadata
of your files are prominent.
And the way it works is that for
each item that the files have
displayed, your file provider is
going to be called, and the
specific method this time is
called itemForItemIdentifier,
which returns an
NSFileProviderItem.
That item should be constructed
from your database.
So you look at your database,
you get an NSFileProviderItem,
and you return it.
OK, that was simple, but I did
not actually go into the detail
of what is an
NSFileProviderItem.
So as I told you a bit earlier,
it's a protocol.
And with most protocols, you have
required properties as well as
optional properties.
So let's go into the detail of
the required properties that
your object conforming to
NSFileProviderItem must
implement.
So the first properties are
obviously the itemIdentifier, so
that's a simple string.
Then, you have the
typeIdentifier, and that is the
UTI, indicating whether the file
is a PDF, an image, or a folder.
And last but not least, you have
the filename, which is pretty
prominent in the UI.
So now that we've seen the
required properties, that's all
you really need to implement, we
can move on to the optional
properties that we strongly
encourage you to also implement.
For instance, in this particular
screenshot here, there is the
shared status that is displayed
just below the filename.
That shared status is displayed
onscreen if you set the isShared
property.
And to go along with the shared
status, you have the
ownerNameComponents that you can
specify.
And now, you can see on my
document slide, "Shared by
Amaury," which is pretty good to
know.
Then, you have additional states
such as isDownloaded -- that
lets, display a small down arrow
-- isUploading and uploadError.
So the uploadError is
interesting because if your user
doesn't have enough quota
to actually upload the file, you
probably won't position that
error.
OK, there are a lot of
additional properties.
Unfortunately, we don't have
time to go through all of them.
So we're just going to move on,
but I encourage you to read our
documentation, which is pretty
good on the subject, as well as
our header files.
Well, so we've seen the
metadata, but there is one last
piece of metadata we did not
talk about, and it's a fairly
big one, so it used a different
pipeline.
It's the thumbnail.
So when the Files app displays
your file, especially if the
file is not local -- in that
case, there is no way we can
generate a thumbnail out of that
file -- what we are going to do
is to ask your file provider
extension to fetch the
thumbnails for a list of files.
In that case, you can go on your
server, ask it to download the
thumbnail associated to the
file.
When the download completes, you
hand back the thumbnail data.
And at this point, we just
display the thumbnail.
So I'm going to go into detail
of how that fetch thumbnail
function works because it's a
bit more involved than the other
one.
So first, what you have onscreen
if your file provider extension
subclass.
And so we did, it's a file
provider extension subclass
called MyFileProviderExtension.
And there, you want to override
the fetchThumbnail function.
It takes a list of item
identifiers.
Why a list?
Because we want to do batching
for performance reasons so that
we don't hit the server
for every thumbnail.
Then, you have a requestedSize,
a perThumbnailCompletionHandler,
and then an overall
completionHandler.
The first thing you want to do
is to actually create a progress
object.
The reason why is not so much
for reporting, but more for
consideration purposes so that
if the thumbnail request is
canceled because the user
dismissed the Files app, then
you would be aware and you would
be able -- and you must,
actually -- cancel your
thumbnail request.
So now, imagine you download the
files from your server using a
download task.
For each thumbnail, you get the
file UI that you would have
downloaded and you map it.
So be sure to not allocate
memory there.
So I encourage you to use the
alwaysMapped option.
Finally, you call your
perThumbnailCompletionHandler,
and that's not the real finally,
the real finally is this one.
You actually call the overall
completionHandler.
So remember one thing: You must
call it in case of success,
failure, cancellation always.
And now, you can return the
progress object so that the
system knows how to cancel your
thumbnail request.
Boom, well done.
We provided an item, so we're
happy.
But now, let's move on to the
next topic, which is enumerating
items.
So for that, enumerating items
means actually providing data to
the screenshots or to the Files
app that I have on screenshot
beside me.
And we are going to see how to
paginate items, sync changes,
render push notification, and
then signal changes.
So enumerating item works this
way.
The Files app starts up,
requests a page of item.
Your file provider extension
return the first page.
It's all over.
There's still some room
onscreen, so it's going to ask
for another page.
And so on and so forth until it
does everything.
The question you might ask is,
why do we paginate?
What's the sense of all this?
So what you have to know is that
your extension is granted a tiny
fraction of the memory your app
is granted.
If your app is in blue there,
your extension is in gray.
You can't even see it onscreen.
What you also have to know is
that above this limit of, if you
allocate more memory than what
you have available, your
extension is terminated.
So we strongly encourage you --
and this is what pagination is
all about -- to avoid peak in
your memory allocation.
I just want to go through some
other tips that we found useful
and that you might also find
useful.
Avoid using all data task.
Instead, prefer the download and
upload task because they
manipulate files, so they don't
require memory allocation.
Use dispatch queues with an
autoreleasepool frequency of always.
Otherwise, you can get memory
peak due to too many allocation
in your autoreleasepool.
And finally, as always, if you
have a long running while or for
loop, be sure to add an
autoreleasepool keyword.
So in any case, we don't have
time to go into more details, so
check out this super session
from a while back, and there are
some other you can probably
check out online.
OK, let's go back to enumerating
items.
So on your Files app, you've
opened a folder.
And it's going to call your file
provider extension subclass and
ask you to provide an enumerator
for a given item identifier.
Hand waving: you will
locate your NSFileProvider
enumerator and return it to us.
The Files app is going to store
that enumerator.
And the next thing it's going to
do is to ask you to provide the
initial page of item.
You get a callback on your
enumerator this time, which is
called enumerateItems for
observer, startingAt page.
You figure out the items in your
first page.
You return them.
And you say you're done
enumerating.
There is my second page.
We're done.
We've enumerated a page.
If the Files app wants to
have more items, it will
continue to ask
for more pages using the exact
same mechanism.
Let's go through the different
methods we've seen.
So first method is in your
subclass of
NSFileProviderExtension.
It's called enumerator
forContainer itemIdentifier, and
it returns an object conforming
to NSFileProviderEnumerator.
The itemIdentifier can be one of
workingSet if we're enumerating
the Recents, as Jean-Gabriel was
describing earlier, or the
rootContainer.
Finally, it can also be any of
your folder item identifiers
that you've previously returned.
The other function that we saw
is this time on
NSFileProviderEnumerator.
It's enumerateItems for
observer, startingAt page.
The observer is a system, as we
saw earlier, is a system object
presenting, receiving your items
and the next page.
The page is a simple data blob.
It has a type, but it's a simple
data blob that you're free to
decide what's inside, and you're free
to decide what's inside, as long
as it doesn't go above 500
bytes.
What you generally put there is
like a page index -- 1, 2, 3, 4,
5 -- or an item of sets
100, 200, et cetera.
For the first page, it can be
one of any initial page sorted
by date or sorted by name,
depending on what the UI is
displaying.
OK, so let's go back to this
slide that you've seen before.
One crucial thing we've just
added is the ability to
enumerate folders and the
working set.
So we have two kinds of
enumerator, of enumerators, as
you can see onscreen.
And I just want to go back -- or
actually, highlight the
differences between the two.
So for folder enumerator, what
you typically do is enumerate
the cloud directly.
That's it.
You can do caching, however, if
you want.
It's up to you.
You decide.
However, for the working set,
it's very different.
You need to enumerate your own
local copy of the working set.
So not the cloud.
Just your working set.
The main reason for that is that
your working set must work
offline.
The item is the working set, in
the working set must be
available offline and work
offline.
I just want to reiterate on this
because this is something that
is not obvious.
So I'll say it again.
The working set should never
read the cloud.
The folder enumerator, it's OK.
And the working set should
always read the database, and
the folders, it's OK if you want
to cache them.
It's fine.
I hope it's clear.
Now, let's move on to the next
topic, which is syncing changes.
So for that, on your cloud
server, you are probably doing
it anyway, but you need to
assign version numbers to your
items.
So here are some version numbers
on my items in the cloud.
The maximum known version number
is what we call the sync anchor.
So here it's 14.
On changes, you need to bump the
file version number.
So here, for instance, 15.
The count sync anchor -- oh, I
went a bit fast, but it's OK.
I did a new file, which is,
which gave the version number
16.
And this time, we bumped the
sync anchor to 16.
And remember, it was 13 at the
beginning, and then I went a bit
fast, but you can see that now.
Then, if you, if we go back to
the Files app in your file
provider extension enumerator,
what is going to happen -- and I
lied to you earlier.
Before enumerating, what we are
going to do is to ask your
enumerator to provide its
current sync anchor.
So that's before enumerating the
pages.
So this is trivial, you just
have your sync anchor.
You return it back to the Files
app, and the Files app is going
to store it.
After that, we'll just fetch the
pages as we did before, and
we're in sync.
When a new file is added on your
server, you add a new file here
in green, you bump your sync
anchor, it becomes 14, and you
emit a push.
The Files app receives the push.
Your enumerator is called with
this new function,
enumerateChanges.
So before, it was enumerateItem,
and now, it's enumerateChanges.
And it's passing you the
previous sync anchor it has.
So here it's the current
version, it's the version 13, so
it's passing you 13.
When your enumerator gets that
callback, it fetches the new
item, which is here, 14, the
item with the change number 14.
It sent it back to the observer,
and then it called
finishEnumerating up to the new
version here.
This is 14.
And you don't have anymore
change coming, so you just say,
moreComing false.
OK, and now we're ready to
display the update.
Oh, we forgot one thing, which
is the Files app actually remembers the
new sync anchor.
So I went very fast on push
notification, and it's actually
interesting because for this
time, the push notification
doesn't go to your file provider
extension.
It goes to the file provider
daemon, actually.
And so when receiving your push,
the file provider daemon is
going to initiate the
enumerateChanges code on your
enumerator, and at that point,
you can return the item.
Under the hood, what you
have to know for push is -- and
I will go briefly into this --
your PKPushType must be a
PKPushType file provider.
The topic name is your
bundle-identifier plus a suffix,
pushkit.fileprovider.
And your payload must include a
container identifier, which
refers to one of the possible
enumerator.
For more on push notification,
check out this session,
Introduction to Notification,
from last year.
So we've seen pushes, but you
might ask, what if I have some
changes and I want to tell the
system about it, but I don't
have a push for it?
In that case, you would want to
code the file provider daemon
and just say, oh, I have a
change.
Well, we have a function just
for that, which is called,
NSFileProvider signalChanges
forContainer.
When receiving such a code, the
file provider daemon is going to
enumerate changes just like it
would do for pushes.
So let me go back to that
method.
The signalChanges method, when
should you call it?
So first, you can tell, you can
call it for the initial set of
files.
Imagine you just installed your
app and you already have some
files in your file provider
extension that you want the
system to know about.
Then, in case of changing
account -- for instance, the
user is logging out, logging in
to a new account -- you would
want to tell the system to
reload after this account change
because usually there were no
pushes.
More generally, you would want
to call that for any change
without a push, including the
one made locally.
So let me go back to one thing,
which is earlier we saw that
your file provider needs to
implement startProviding
itemAtURL.
If the file is not local at that
point, you need to tell the
system that, well, this file is
not downloading.
If it is, what you should do is
you should signal for changes in
the working set if the item is
in the working set.
Same thing if you have an
enumerator running for the
parent, you should call
signalChanges on the
parentItemIdentifier.
Well, so under the hood, signal
changes can be called from both
your app and your file provider
extension, so it's very
convenient.
You must call signalChanges even
for system-initiated changes.
This is exactly what I was
describing earlier.
You could say the system could
infer that the file has changed.
No, we don't do that.
We let you explicitly tell us
that you know about this change.
But don't worry about it.
signalChanges is very, very
cheap.
So now, we've seen all these
three topics on screen: creating
the project, providing an item,
and enumerating items.
So now, it's time for Johannes
to come on stage and cover the
last topics.
[ Applause ]
>> Thank you, Pierre.
So we've seen how to get your
items into the Files app or into
the document browser.
But of course, that is only part
of what you are interested in
doing or what your users are
interested in doing.
An equally important part is
that your users are able to
modify files.
And to modify files, there are
various possibilities how you
can modify files in the Files
app and using other
technologies.
So in the Files app, as an
example, bring up this menu
controller here as a user, and
this menu controller gives the
users a variety of options to
modify files or to perform
actions on files.
One of these actions, for
example, is the Info option
here, and that simply brings up
a nice Info panel.
And that is backed by
information that you're already
providing.
That's the item method that
you're already implementing.
Other options are, for example,
the Share action here, and that
is backed by a well-known old
friend, the
UIActivityViewController.
And of course, you're able to
simply add activities using
activity plug-ins, and that's
another way for you to expose
actions on these items.
But then, there are other
possible options that are not
backed by any existing system UI
so far.
For example, renaming items.
Renaming items brings up a nice
UI in the Files app, but we're
not so far exposing a way to
actually tell you about the
rename.
And that is what this part of
the session is about.
To back a rename or something
like that, we expose a wide
variety of options, and these
options are moving files around,
creating files -- for example,
if you, if the user hits the
little + button, that shows up
in the document browser view
controller, or if the user drag
and drops a file into the Files
app or into the document browser
in another application.
Last but not least, modifying
attributes on files.
So if the user performs a
tagging operation or looks at a
file and thus wants to modify
the last use date of the file.
And all of these are actions
that are backed by, that back
user operations.
And you are, your extension is
implementing these.
All right, so that is awfully
abstract, so let's have a look
at one of these actions and how
you implement it.
All right, and as our example,
we're going to use the Import
Document action.
But all of the actions are
actually implemented in a very
similar way.
The Import Document action is a
nice one because it deals with a
new file, but most of these
actions are kind of similar.
They have slightly different
parameters and, of course, have
slightly different semantics,
but everything I'm going to tell
you in this session is going to
count for pretty much all of the
actions.
So the Import Document action
works this way.
The system gives you an existing
file URL, so that's a file on
disk, and this file is any
location that the system gives
you, it's possibly in the Temp
folder or wherever the
application that, for example,
performs a create operation
stores its templates, but in any
case, this file is basically for
you to use.
You can go and move this file
into your file provider storage.
So this is, this file is now
under your control.
It's in your container.
At this point, you need to
schedule a background upload so
that this file from your
container actually gets uploaded
into your cloud.
And last but not least, you call
the completion handler.
This is very important, and this
is a very important part of
this.
We just scheduled a background
upload, but we did not wait for
the background upload to finish
until we call the completion
handler.
So the file is actually being
uploaded in the background,
meaning that the user does not
have to wait for this file to be
actually fully uploaded until
you tell the system, hey, I got
this.
I've got this file under my
control.
I'll scheduled the upload.
This file will be in the cloud
at some point.
So the user doesn't have to wait
for this upload of the file that
can be potentially many
megabytes.
So that's how the general flow
of this looks.
Let's have a look at how the
data flow of this operation
looks.
So as I said, the initial
impetus for this operation is
that the user created, or
pasted, or dropped a file into
the, into a container in your
file provider.
And at that point, the Import
Document action on your file
provider extension subclass gets
called.
You make a database entry.
You make sure that the file is
getting uploaded.
So you schedule the upload.
Now, we're done, right?
We can call the
completionHandler.
But as Pierre has told, the
system does not automatically
infer that this file basically
has changed.
So one important bit here is
that you at this point signal us
to tell us, hey, there are
changes on this container.
We need to re-enumerate this
container.
This is important so that the
user gets immediate feedback.
So the next step is actually
that you tell us there are
changes here.
And at that point, we simply
make a note.
We say, OK, for this container
-- and keep in mind, the user is
probably looking at this
container, right?
They just hit the little +
button there.
Of course, they hit the + button
in the container that they're
looking at, so they want to see
these changes.
So you told the system, changes
are pending.
Now, you tell the system, call
the completionHandler.
We're done with this operation.
The system gets unblocked.
And at this point, the system
can go and call, turn around,
and enumerate changes.
You tell us, sweet, we just
added this item, and it's now
uploading, probably.
And you return the changed item
to us as part of a change set.
And we can update our UI and
show a little uploading error in
the corner of the item.
So the user gets immediate
feedback that their data is safe
in your cloud.
So let me reiterate that.
Operations are expected to
finish immediately, and thus,
you need to defer long-running
tasks, such as uploads, to the
background using NSURLSession.
So now, we've got this item
uploading, and that's great,
but, of course, at some point,
this upload is going to finish
and we want to tell the user
about the new status of the
file.
So let's go into that.
The way that works is that
NSURLSession at some point will
notice, hey, this upload
succeeded.
Sweet, the item is in the cloud.
And the way this, the way
NSURLSession tells you about
that is that it calls a
callback, an NSURLSession
background callback, on your
parent application.
Your parent application at this
point can go and update the
database entry.
It sets a little flag in your
database that says, this file is
uploaded.
It's no longer dirty on
disk.
Our upload succeeded.
We don't have to retry this
upload.
And we should inform the user
that this upload is finished.
So as Pierre mentioned, the
signalChanges method can be
called both by your extension
and the parent application, and
this is why.
Now, you tell us there are
changes on this container.
And at this point, the same old
dance happens.
The system notes that changes
are pending, it re-enumerates
your, the, your working set, and
at this point, you can return
in, from your file provider
extension that this item is
properly uploaded using the
isUploaded key on the
NSFileProviderItem protocol.
Now, sometimes uploads fail.
For example, your server might
tell us, hey, this user is out
of quota.
And in this situation, the same
dance happens, basically.
So NSURLSession D is going to
tell your parent application,
hey, this upload failed.
That's too bad.
You're going to have to handle
this somehow.
So again, we make a database
entry.
We signal the system.
The system notes that changes
are pending.
The system re-enumerates.
And we can return the updated
item.
Now, this updated item should
reflect the fact that this item
is now in an error state, so to
turn an update error, an upload
error that is reflecting what
actually here.
All right, let's get into a bit
more detail.
As I said, you mark the item as
being in an error status by
using the upload error property
on the item properties.
You signal re-enumeration so
that the user can see that this
item's in an error state.
And then, how you actually
continue in this error state
depends completely on the kind
of error that you're looking at.
So some, not all errors are the
same thing.
There's the possibility that
you're running into an
intermittent error.
For example, the user was, I
don't know, camping out in the
jungle for two weeks, and
NSURLSession D just gave up
because there was no Wi-Fi, no
wireless connection.
In this situation, the easiest
thing to do is tell the user,
hey, your data wasn't uploaded,
but we're on it.
We re-enqueue the, your
NSURLSession task.
We still mark this item as being
in an error state, as not being
up to date in the cloud, but we
simply retry.
There's nothing that the user
has to do.
In the error description, you
can possibly tell the user, hey,
maybe go online or something
like that, but that's pretty
much it.
There's also the possibility
that you're running into a
persistent error, and that is
different.
In a persistent error case,
like, for example, the user's
out of quota, what you need to
do is tell the user, hey, you're
out of quota.
You got to go and buy more quota
on our web page.
And in that situation, basically
what you give us is a, an error
that suggests a recovery option.
Now, last but not least, there's
the possibility for
authentication errors, and these
are kind of special.
The user has to do something
specific to your application.
For example, re-authenticate.
Well, that's actually the only
possibility in that situation,
probably.
And for that possibility, a
custom action will be called by
the system.
So what's a custom action?
Well, conveniently, that's our
next section, and let's have a
look at, back at this menu view
controller here, menu controller
here.
We've seen these system-provided
actions here, and the way these
work is that the user just taps
them and is backed by an action
that is internally backed by
your provider.
But we also offer another
opportunity for you to customize
this, which is to introduce a
custom action in this situation.
So that's a action, and this one
here is called Custom on the
slide, but it can be whatever
name you want.
And the way this works is that
you expose an operation, a UI
operation, that is scoped to
your file provider extension.
You provide an interface for
this operation that is backed by
a new type of UI extension.
And this is a separate process
that's running on the system,
and it's backed by a subclass of
FPUIActionExtension
ViewController.
So how do we do that?
Well, first of all, we list the
possible number of actions in
the info.plist of our extension,
and this is really easy.
We have an action name, we have
an identifier, and we have an
activation rule.
And this activation rule is used
to figure out which of these
actions applies to which items.
So in this example on the slide,
we're simply using a true
predicate, which means that this
action is, that every item in
your provider's eligible for
this specific action.
But you can basically go wild on
this.
You can expose different keys on
your items and use these for
matching in your activation
rule.
So how does this work?
Well, the user long presses on
an item in the Files app or in
the document browser, and at
this point, we consult the
index, not your extension.
We don't even bring that up.
We consult the index of the item
that you previously returned to
us.
We look at the attributes and we
match this predicate against the
attributes.
At this point, we know whether
this predicate returns a yes or
a no, and we can simply display
the action if it returns a yes.
OK, so now, the user sees this
action, and probably they tap on
it.
So the user taps on the action.
What happens now?
Well, we bring up your UI
extension, and your UI extension
gets a call to its
prepareForAction method.
What this gets, what this does
is it, we hand it a set of items
plus the actionIdentifier that
the user actually chose, and you
can go and present whatever UI
you have for this action.
You return from this method.
We present your view controller.
It slides up nicely in the Files
app.
And that's it.
At this point, you know which
items you're performing these
actions on.
For example, and you can do
whatever is necessary to perform
these actions.
And these actions are completely
custom, so, of course, it's
completely up to you what is
happening here.
At some point, the user will be
done with this action.
Maybe you're implementing a Done
button.
Maybe this is, there's some
natural end to this action.
But at any rate, you call the
completeRequest method on the
extension context, and the
system simply dismisses your UI.
But that's just custom actions.
As I promised earlier, there's a
special case for authentication
actions, so look at that.
Authentication actions are
called exactly the same way as
custom UI actions are called,
except they're called in a
special case, and that's when
you to us return an
authentication error.
So if you return an
authentication error, what
happens is that we call the
prepareForAuthentication method
on your FPUI extension,
ActionExtensionViewController.
And everything from there on
flows just the same way.
You call, you can call, you can
display whatever UI is necessary
for authenticating.
At some point, the user has
authenticated.
You can call the dismiss method,
the view controller dismisses,
and you're now authenticated,
and we will simply retry.
So those are actions, and those
are very nice, but all said and
done, they are only showing up
in the, either the document
browser view controller or the
Files app.
And that is great.
That is a great way for you to
expose something to your user,
but sometimes you need something
more, and for that, we have this
concept of Services.
What's a Service?
Well, as I said, there's caveats
for the custom actions.
But sometimes you need
programmatic access to specific
files.
And if you're currently
publishing an SDK, for example,
this is where you export,
expose, where you can expose the
same functionality that your SDK
is currently exposing.
Services are a way for you to
expose functionality directly on
an item, so let's have a look at
how that goes.
First, you need to define what
your service is.
And at the base level, a service
is simply a name that's an
identifier that you give the
service plus an Objective-C
protocol.
And this is basically any old
Objective-C protocol.
There's some caveats here that
we'll go into real soon.
The protocol must be known to
you and to the developer that's
using it.
So both of you need to determine
what the protocol is.
And this is because the
developer using this is going to
perform method calls on an
object that is exposed by you,
effectively.
So if the signatures don't
match, nothing will happen.
This will just result in an
error.
And when I say they're
performing method calls, the way
this works is actually that this
is implemented using NSXPC,
which is a great technology for
interprocess communication.
And that means that the usual
XPC rules apply.
So all the parameters that are
passed through this protocol
have to be secure codable.
And of course, the classes have
to be available in both your
extension and the app that's
calling this.
And you cannot directly return
any objects from this protocol.
So you have to return, if you
want to return something, you
have to call back via completion
block.
Now, the rules for this are
somewhat interesting, and
there's, was a session in 2012
that goes into way more detail
than I can go, possibly go into
here today.
So I encourage you to have a
look at that session.
All right, let's quickly go
through the data flow that is
happening here because that is,
that warrants having a look at.
Your third-party application
goes and basically inquires on
an URL, what are the services
that are exposed on this URL?
And at this point, your
extension gets a call to answer,
hey, what are the supported
services on this item?
It returns an array of service
sources, and a service source is
not a service itself.
It's an object that can create a
service, effectively, that can
create an XPC listener endpoint.
We return these services as
services to the application.
So on the service object, the
application can go and then
create a proxy object.
Let's have a look at that, how
that works.
So the third-party application
uses that service after it's
looked at which services are
available.
Of course, they can be any
number of services, right?
So it looks at the identifiers
of these services, figures out
which one it wants to use, and
creates a messenger.
At this point, we are asking
your extension on the service
source to make a listener
endpoint.
So it returned that.
A ListenerEndpoint, that's an
existing NSXPC class, although
it's currently only exposed on
macOS.
We're now bringing it to iOS.
At this point, the third-party
application can grab the remote
proxy on this messenger, and
that calls on your listener
delegate the
shouldAcceptConnection callback.
At this point, you can call, you
can configure this connection
and return this connection to
the system.
So in this case, for example,
you provide a proxy object that
is being exported by our
extension.
And from there on out, we can go
and call whatever methods are
defined in our protocol on this
remote proxy object in our
third-party application.
And all of these calls will be
translated into calls in our
extension.
This is a, an extremely powerful
mechanism for you to expose
basically any old possible SDK
operations on your extension.
As a, as an aside, we don't
expect everyone to implement
this, and it's perfectly fine if
your first version does not use
this mechanism at all.
This is a very advanced topic,
so if you only, if all you
implement is enumeration and the
usual file provider actions,
we're already super happy.
All right.
Let's summarize what we've seen
today.
We've seen what a file provider
is, and how we can use a file
provider to back the
enumerations in the Files app,
and how to use it to show files
in the document browser.
We've seen how you use
enumerations to expose items to
both of these controls and how
you can enumerate the working
set, how you can enumerate
changes to the working set, and
how you can push changes to the
working set.
And finally, we've seen how you
can implement actions to modify
stuff in your hierarchy and how
you can then go even further,
and customize these actions, and
even implement services that are
completely custom to your
provider, and expose those to
third-party apps.
For more information, we have a
page on the developer.apple.com
and we have a list of related
sessions that go into way more
detail than we can possibly do
here on some of the technologies
used.
And with that, I hope you are
having a great conference.
Thank you very much.
[ Applause ]