Inbox

[Previous << Contracts](https://qiita.com/flowcadence/items/c8661fbf9eae32ce5926)
[Next >> Attachments](https://qiita.com/flowcadence/items/4b41229869c45bc8a4df)

https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a#cadenceの言語仕様を学ぶ

Accountにはインボックス(Inbox)があり、特定のアカウントに[Capability](https://qiita.com/flowcadence/items/b70151356f4e548f2c91)を利用可能にすることができます。インボックスは2つのアカウント間の初期接続(initial connection)をセットアップし、アカウント間でのデータ転送や処理の実行に利用できる、Capabilityを”自給(bootstrap)”する便利な方法を提供します。

アカウントは、`Account.Inbox`型の`inbox`フィールドを通じてこのインボックス機能を提供しています。

<h1 id="Account.Inbox">Account.Inbox</h1>

```ruby
access(all)
struct Inbox {

    /* Publishes a new Capability under the given name,
       to be claimed by the specified recipient. */
    access(Inbox | PublishInboxCapability)
    fun publish(_ value: Capability, name: String, recipient: Address)

    /** Unpublishes a Capability previously published by this account.
      *
      * Returns `nil` if no Capability is published under the given name.
      *
      * Errors if the Capability under that name does not match the provided type.
      */
    access(Inbox | UnpublishInboxCapability)
    fun unpublish<T: &Any>(_ name: String): Capability<T>?

    /** Claims a Capability previously published by the specified provider.
      *
      * Returns `nil` if no Capability is published under the given name,
      * or if this account is not its intended recipient.
      *
      * Errors if the Capability under that name does not match the provided type.
      */
    access(Inbox | ClaimInboxCapability)
    fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?
}

entitlement Inbox

entitlement PublishInboxCapability
entitlement UnpublishInboxCapability
entitlement ClaimInboxCapability
```

<h1 id="Publishing-a-capability-to-the-account-inbox">Publishing a capability to the account inbox</h1>

あるアカウント（提供者）が別のアカウント（受領者）にCapabilityを提供したい場合、`publish`関数を使用してこれを行うことができます。
```ruby
access(Inbox | PublishInboxCapability)
fun publish(_ value: Capability, name: String, recipient: Address)
```

`publish`関数を使用するにはEntitlement(権限)で承認された参照(reference)を通じてアカウントにアクセスする必要があります。それは、大まかな粒度の`Inbox`Entitlementである`auth(Inbox) &Account`か、細かな粒度の`PublishInboxCapability`Entitlementである`auth(PublishInboxCapability) &Account`です。

この関数は、引数の文字列を識別子(ID)にして、指定されたCapabilityを、後で受領者のアカウントに要求されることによって、渡します。しかし、受領者がCapabilityを要求するまでは提供者のアカウントに保存され、そのCapabilityは提供者側のアカウントのストレージ使用量に影響します。

この関数を呼び出すと`InboxValuePublished`イベントが発行され、そのイベントには提供者と受領者側のアドレス、渡される予定のCapabilityの名前と型が含まれています。このイベントの詳細については、[Core Events](https://qiita.com/flowcadence/items/5e0aea26c0ce24fab7e9#inbox-value-published)ページを参照してください。


<h1 id="claiming-a-capability-from-the-account-inbox">Claiming a capability from the account inbox</h1>

Capabilityの受領予定者は`claim`関数を使用して、提供者側に対してCapabilityを要求することができます。
```ruby
access(Inbox | ClaimInboxCapability)
fun claim<T: &Any>(_ name: String, provider: Address): Capability<T>?
```
`claim`関数を使用するにはEntitlement(権限)で承認された参照(reference)を通じてアカウントにアクセスする必要があります。それは、大まかな粒度の`Inbox`Entitlementである`auth(Inbox) &Account`か、細かな粒度の`ClaimInboxCapability`Entitlementである`auth(ClaimInboxCapability) &Account`です。

もし、指定された名前でCapabilityが提供者側のInboxに保存されてあり、呼び出し元の受領者側が意図した受領者であり、引数の型が合致する場合、この関数は提供者側のInboxからそのCapabilityを取り除き、それを返します。

提供者側のInboxに指定された名前でCapabilityが保存されていない場合、またはこの関数を実行した受領予定者が意図した受領者でない場合、この関数は`nil`を返します。もしCapabilityの型が引数の型のサブタイプでない場合、プログラムは中断します。

:::note
💡TIP
Capabilityは一度しかclaimできません。
:::
`claim`関数を実行すると、`InboxValueClaimed`というイベントが発行されます。このイベントには、提供者と受領者の両方のアドレス、および要求されたCapabilityの名前が含まれます。このイベントの詳細については、[Core Eventページ](https://qiita.com/flowcadence/items/5e0aea26c0ce24fab7e9#inbox-value-claimed)を参照してください。

<h1 id="unpublishing-a-capability-from-the-account-inbox">Unpublishing a capability from the account inbox</h1>

もし、何らかの理由で提供者が受領者にCapabilityを貸すことを望まなくなった場合、`unpublish`関数を使用してCapabilityを非公開にすることができます。

```ruby
access(Inbox | UnpublishInboxCapability)
fun unpublish<T: &Any>(_ name: String): Capability<T>?
```
`unpublish`関数を実行するにはEntitlement(権限)で承認された参照(reference)を通じてアカウントにアクセスする必要があります。それは、大まかな粒度の`Inbox`Entitlementである`auth(Inbox) &Account`か、細かな粒度の`UnpublishInboxCapability`Entitlementである`auth(UnpublishInboxCapability) &Account`です。

もし、提供者のInboxに指定された名前で保存されたCapabilityがあり、それが指定された引数の型に適合する場合、この関数はInboxからそのCapabilityを取り除いて返します。

もし、提供者のInboxに指定された名前で保存されたCapabilityがない場合、この関数は`nil`を返します。Capabilityの型が指定された引数の型のサブタイプでない場合、プログラムは中断します。

`unpublish`関数を実行すると、提供者側のアドレスと非公開化されたCapabilityの名前を含むイベント`InboxValueUnpublished`が発行されます。このイベントの詳細については、[Core Eventsページ](https://qiita.com/flowcadence/items/5e0aea26c0ce24fab7e9#inbox-value-unpublished)を参照してください。

翻訳元

https://cadence-lang.org/docs/language/accounts/inbox

***
<b>[Previous << Contracts](https://qiita.com/flowcadence/items/c8661fbf9eae32ce5926)
</b>

[Flow blockchain / Cadence version1.0ドキュメント](https://qiita.com/flowcadence/items/3073d69c6e9895e68b5a) (Inbox)

<b>[Next >> Attachments](https://qiita.com/flowcadence/items/4b41229869c45bc8a4df)</b>