An object that manages file and data transfers between participants
joined in a group session.
A ``GroupSessionJournal`` object lets you transfer files
and other data objects between participants of a shared activity. A journal object
isn’t a replacement for a ``GroupSessionMessenger`` object,
which you use to transfer time-sensitive messages and commands
between participants. Instead, use it to associate files and other data objects
with the activity. For example, you might share images that people drag
into your app as part of the activity. The journal makes these data objects
available to all participants, regardless of when they joined the session.
After your app joins an activity and receives a session object, create
a ``GroupSessionJournal`` object and store a strong reference
to it. To add a file or data object to the group's journal, call the ``add(_:)``
or ``add(_:metadata:)`` method with the data you want to share. The types you
specify must adopt the <doc://com.apple.documentation/documentation/coretransferable/transferable>
protocol from the Core Transferable framework. The journal object
uses that protocol to package a version of your data suitable for sending
to other devices.
To receive data that a participant added to the journal, configure a task
to listen for asynchronous updates to the ``attachments`` property of your
``GroupSessionJournal`` object. When someone adds or removes an attachment,
the journal updates the array and executes your task. Load the contents
of an attachment using the ``Attachment/load(_:)`` method of that type. You
can also retrieve any attachment-specific metadata, such as a shared ID or
display name, that you included with the attached file. The following example
creates a task that waits on a custom image type. The `journal`
variable contains a previously configured ``GroupSessionJournal``
object.
```
let attachmentListener = Task {
for await attachments in journal.attachments {
for attachment in attachments {
let receivedItem = try await attachment.load(MyImageItem.self)
// Do something with the item you receive.
}
}
}
```
Members (5)
get · iOS 17.0+
attachments
TypeScript
get attachments(): GroupSessionJournal_Attachments
Swift declaration
final var attachments: GroupSessionJournal.Attachments { get set }
The currently available attachments for you to download
and incorporate into your app.
This property contains an asynchronous sequence that you
monitor while the current session is active. To monitor this
sequence, configure an asynchronous task and iterate over the
contents of the ``GroupSessionJournal/Attachments`` type.
For an example of how to configure this task, see the overview for
``GroupSessionJournal``.
The system updates this array whenever a participant adds or
removes an attachment. Iterate over the array and update your
app's data structures to match the current contents.
set · iOS 17.0+
attachments
TypeScript
set attachments(value: GroupSessionJournal_Attachments)
Swift declaration
final var attachments: GroupSessionJournal.Attachments { get set }
The currently available attachments for you to download
and incorporate into your app.
This property contains an asynchronous sequence that you
monitor while the current session is active. To monitor this
sequence, configure an asynchronous task and iterate over the
contents of the ``GroupSessionJournal/Attachments`` type.
For an example of how to configure this task, see the overview for
``GroupSessionJournal``.
The system updates this array whenever a participant adds or
removes an attachment. Iterate over the array and update your
app's data structures to match the current contents.
Adds the specified item and metadata to the journal and begins transferring the
data to the other participants' devices so they can access it.
- Parameters:
- item: The item to send to other session participants. The type
you specify must conform to the <doc://com.apple.documentation/documentation/coretransferable/transferable>
protocol. For more information about creating transferable types,
see <doc://com.apple.documentation/documentation/CoreTransferable>.
- metadata: Custom metadata to include with the item. Specify a
<doc://com.apple.documentation/documentation/swift/codable> type that contains
information to help your app interpret or process the item on other
devices. For example, you might include app-specific details that aren't
part of the item's intrinsic data format.
- Returns: An attachment object you can remove by passing it to the ``remove(attachment:)`` function.
Call this method when you want to send a file or codable data type to the
other participants of an activity. The method runs asynchronously and can return
before the upload operation finishes.
final func add<ItemType>(_ item: ItemType) async throws -> GroupSessionJournal.Attachment where ItemType : Transferable
Adds the specified item to the journal and begins transferring the
item's data to the other participants' devices so they can access it.
- Parameters:
- item: The item to send to other session participants. The type
you specify must conform to the <doc://com.apple.documentation/documentation/coretransferable/transferable>
protocol. For more information about creating transferable types,
see <doc://com.apple.documentation/documentation/CoreTransferable>.
- Returns: An attachment object you can remove by passing it to the ``remove(attachment:)`` function.
Call this method when you want to send a file or codable data type to the
other participants of an activity. The method runs asynchronously and can return
before the upload operation finishes.
final func remove(attachment: GroupSessionJournal.Attachment) async throws
Removes the specified attachment from the journal on all sessions.
- Parameters:
- attachment: The attachment object associated with the item.
You receive this object when you call the ``add(_:)`` or ``add(_:metadata:)``
method.
Call this method to remove an attachment that is no longer relevant. For example,
you might remove an attachment containing a photo in response to someone
deleting that photo from the activity. When you remove an attachment, the
journal object updates the array of attachments and sends it to all
participants. Remove any attachments from your app that aren't still in the
array.
Skipped declarations
1 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
GroupSessionJournal.init(session:)
This declaration needs Swift generic type arguments. (no canonical witness for Activity)
