| // Copyright 2020 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library fuchsia.examples.docs; |
| |
| using fuchsia.math; |
| using zx; |
| |
| // [START ordinals] |
| protocol A { |
| @selector("C") |
| B(struct { |
| s string; |
| b bool; |
| }); |
| }; |
| // [END ordinals] |
| |
| // [START semantics] |
| type Ipv4Address = struct { |
| octets array<uint8, 4>; |
| }; |
| // [END semantics] |
| |
| type SuccessValue = struct {}; |
| |
| // [START errors] |
| // Only erroneous statuses are listed |
| type MyErrorCode = strict enum { |
| MISSING_FOO = 1; // avoid using 0 |
| NO_BAR = 2; |
| }; |
| |
| protocol Frobinator { |
| Frobinate() -> (struct { |
| value SuccessValue; |
| }) error MyErrorCode; |
| }; |
| // [END errors] |
| |
| // [START empty-error-enum] |
| type MyEmptyErrorCode = flexible enum {}; |
| |
| protocol Frobinator2 { |
| Frobinate() -> (struct { |
| value SuccessValue; |
| }) error MyEmptyErrorCode; |
| |
| BadFrobinate() -> (struct { |
| value SuccessValue; |
| }) error flexible enum {}; // avoid anonymous enum |
| }; |
| // [END empty-error-enum] |
| |
| // [START optional-error] |
| type MyStatusCode = strict enum { |
| OK = 0; // The success value should be 0, |
| MISSING_FOO = 1; // with erroneous status next. |
| NO_BAR = 2; |
| }; |
| |
| protocol Frobinator3 { |
| Frobinate() -> (struct { |
| value box<SuccessValue>; |
| err MyStatusCode; |
| }); |
| }; |
| // [END optional-error] |
| |
| // [START constants] |
| const MAX_BATCH_SIZE int32 = 128; |
| |
| protocol Sender { |
| Emit(struct { |
| batch vector<uint8>:MAX_BATCH_SIZE; |
| }); |
| }; |
| // [END constants] |
| |
| // [START bits-hex] |
| type InfoFeaturesHex = strict bits : uint32 { |
| WLAN = 0x00000001; // If present, this device represents WLAN hardware |
| SYNTH = 0x00000002; // If present, this device is synthetic (not backed by h/w) |
| LOOPBACK = 0x00000004; // If present, this device receives all messages it sends |
| }; |
| // [END bits-hex] |
| |
| // [START bits-binary] |
| type InfoFeaturesBits = strict bits : uint32 { |
| WLAN = 0b00000001; // If present, this device represents WLAN hardware |
| SYNTH = 0b00000010; // If present, this device is synthetic (not backed by h/w) |
| LOOPBACK = 0b00000100; // If present, this device receives all messages it sends |
| }; |
| // [END bits-binary] |
| |
| // [START pipelining-1] |
| // GOOD: |
| protocol GoodFoo { |
| GetBar(resource struct { |
| name string; |
| bar server_end:Bar; |
| }); |
| }; |
| |
| // BAD: |
| protocol BadFoo { |
| GetBar(struct { |
| name string; |
| }) -> (resource struct { |
| bar client_end:Bar; |
| }); |
| }; |
| // [END pipelining-1] |
| |
| type CodecParams = struct {}; |
| |
| protocol Codec {}; |
| |
| // [START pipelining-2] |
| protocol CodecProvider { |
| TryToCreateCodec(resource struct { |
| params CodecParams; |
| codec server_end:Codec; |
| }) -> (struct { |
| succeed bool; |
| }); |
| }; |
| // [END pipelining-2] |
| |
| // [START pipelining-3] |
| protocol Codec2 { |
| -> OnReady(); |
| }; |
| |
| protocol CodecProvider2 { |
| TryToCreateCodec(resource struct { |
| params CodecParams; |
| codec server_end:Codec2; |
| }); |
| }; |
| // [END pipelining-3] |
| |
| type Args = struct {}; |
| |
| // [START hanging-gets] |
| protocol FooProvider { |
| WatchFoo(struct { |
| args Args; |
| }) -> (resource struct { |
| foo client_end:Foo; |
| }); |
| }; |
| // [END hanging-gets] |
| |
| // [START throttle-push] |
| protocol Listener { |
| OnBar(struct { |
| args Args; |
| }) -> (); |
| }; |
| // [END throttle-push] |
| |
| // [START events-1] |
| protocol DeathWish { |
| -> OnFatalError(struct { |
| error_code zx.status; |
| }); |
| }; |
| // [END events-1] |
| |
| // [START events-2] |
| protocol NetworkScanner { |
| ScanForNetworks(); |
| -> OnNetworkDiscovered(struct { |
| network string; |
| }); |
| -> OnScanFinished(); |
| }; |
| // [END events-2] |
| |
| type InputEvent = struct {}; |
| |
| // [START ack-1] |
| protocol View1 { |
| -> OnInputEvent(struct { |
| event InputEvent; |
| }); |
| NotifyInputEventHandled(); |
| }; |
| // [END ack-1] |
| |
| type FocusChangedEvent = struct {}; |
| |
| // [START ack-2] |
| protocol View2 { |
| -> OnInputEvent(struct { |
| event InputEvent; |
| seq uint64; |
| }); |
| -> OnFocusChangedEvent(struct { |
| event FocusChangedEvent; |
| seq uint64; |
| }); |
| NotifyEventsHandled(struct { |
| last_seq uint64; |
| }); |
| }; |
| // [END ack-2] |
| |
| type Image = struct {}; |
| |
| // [START feed-forward] |
| protocol Canvas { |
| Flush() -> (struct { |
| code zx.status; |
| }); |
| Clear(); |
| UploadImage(struct { |
| image_id uint32; |
| image Image; |
| }); |
| PaintImage(struct { |
| image_id uint32; |
| x float32; |
| y float32; |
| }); |
| DiscardImage(struct { |
| image_id uint32; |
| }); |
| PaintSmileyFace(struct { |
| x float32; |
| y float32; |
| }); |
| PaintMoustache(struct { |
| x float32; |
| y float32; |
| }); |
| }; |
| // [END feed-forward] |
| |
| type MyStatus = struct {}; |
| |
| // [START command-union] |
| type PokeCmd = struct { |
| x int32; |
| y int32; |
| }; |
| |
| type ProdCmd = struct { |
| message string:64; |
| }; |
| |
| type MyCommand = strict union { |
| 1: poke PokeCmd; |
| 2: prod ProdCmd; |
| }; |
| |
| protocol HighVolumeSink { |
| Enqueue(struct { |
| commands vector<MyCommand>; |
| }); |
| Commit() -> (struct { |
| result MyStatus; |
| }); |
| }; |
| // [END command-union] |
| |
| // [START paginate-write-1] |
| protocol Foo1 { |
| AddBars(resource struct { |
| bars vector<client_end:Bar>; |
| }); |
| UseTheBars() -> (struct { |
| args Args; |
| }); |
| }; |
| // [END paginate-write-1] |
| |
| // [START paginate-write-2] |
| protocol BarTransaction { |
| Add(resource struct { |
| bars vector<client_end:Bar>; |
| }); |
| Commit() -> (struct { |
| args Args; |
| }); |
| }; |
| |
| protocol Foo2 { |
| StartBarTransaction(resource struct { |
| transaction server_end:BarTransaction; |
| }); |
| }; |
| // [END paginate-write-2] |
| |
| // [START paginate-read-1] |
| protocol EventBasedGetter { |
| GetBars(); |
| -> OnBars(resource struct { |
| bars vector<client_end:Bar>; |
| }); |
| -> OnBarsDone(); |
| }; |
| // [END paginate-read-1] |
| |
| // [START paginate-read-2] |
| protocol BarIterator { |
| GetNext() -> (resource struct { |
| bars vector<client_end:Bar>; |
| }); |
| }; |
| |
| protocol ChannelBasedGetter { |
| GetBars(resource struct { |
| iterator server_end:BarIterator; |
| }); |
| }; |
| // [END paginate-read-2] |
| |
| type Entry = struct {}; |
| |
| // [START paginate-read-3] |
| type Token = struct { |
| opaque array<uint8, 16>; |
| }; |
| |
| protocol TokenBasedGetter { |
| // If token is null, fetch the first N entries. If token is not null, return |
| // the N items starting at token. Returns as many entries as it can in |
| // results and populates next_token if more entries are available. |
| GetEntries(struct { |
| token box<Token>; |
| }) -> (struct { |
| entries vector<Entry>; |
| next_token box<Token>; |
| }); |
| }; |
| // [END paginate-read-3] |
| |
| // [START eventpair] |
| protocol Exporter { |
| ExportThing(resource struct { |
| client_assigned_id uint32; |
| export_token zx.handle:EVENTPAIR; |
| }); |
| }; |
| |
| protocol Importer { |
| ImportThing(resource struct { |
| some_other_client_assigned_id uint32; |
| import_token zx.handle:EVENTPAIR; |
| }); |
| }; |
| // [END eventpair] |
| |
| // [START empty] |
| protocol FooController {}; |
| // [END empty] |
| |
| type ColorCorrection = struct {}; |
| |
| // [START settings] |
| type Settings = table { |
| 1: magnification_enabled bool; |
| 2: magnification_zoom_factor float32; |
| 3: screen_reader_enabled bool; |
| 4: color_inversion_enabled bool; |
| 5: color_correction ColorCorrection; |
| 6: color_adjustment_matrix array<float32, 9>; |
| }; |
| // [END settings] |
| |
| // [START settings-partial] |
| protocol TheManagerOfSomeSorts { |
| /// Description how the update modifies the behavior. |
| /// |
| /// Only fields present in the settings value will be changed. |
| Update(struct { |
| settings Settings; |
| }) -> (struct { |
| args Args; |
| }); |
| }; |
| // [END settings-partial] |
| |
| // [START settings-replace] |
| protocol TheManagerOfOtherSorts { |
| /// Description how the override modifies the behavior. |
| /// |
| /// This replaces the setting. |
| Replace(struct { |
| settings Settings; |
| }) -> (struct { |
| args Args; |
| }); |
| }; |
| // [END settings-replace] |
| |
| // [START enum-variants-for-union] |
| type MyCommandVariant = strict enum { |
| POKE = 1; |
| PROD = 2; |
| // ... |
| }; |
| |
| protocol HighVolumeSinkContinued { |
| SupportedCommands() -> (struct { |
| supported_commands vector<MyCommandVariant>; |
| }); |
| }; |
| // [END enum-variants-for-union] |
| |
| // [START bits-fields-for-table] |
| type MetadataFields = flexible bits { |
| VERSION = 0b1; |
| COUNT = 0b10; |
| }; |
| |
| type Metadata = table { |
| 1: version string; |
| 2: count uint32; |
| // ... |
| }; |
| |
| protocol MetadataGetter { |
| Get(struct { |
| fields MetadataFields; |
| }) -> (struct { |
| metadata Metadata; |
| }); |
| }; |
| // [END bits-fields-for-table] |
| |
| // [START service-hub-1] |
| // BAD |
| @discoverable |
| protocol ServiceHub { |
| GetFoo(resource struct { |
| foo server_end:Foo; |
| }); |
| GetBar(resource struct { |
| bar server_end:Bar; |
| }); |
| GetBaz(resource struct { |
| baz server_end:Baz; |
| }); |
| GetQux(resource struct { |
| qux server_end:Qux; |
| }); |
| }; |
| // [END service-hub-1] |
| |
| // [START service-hub-2] |
| @discoverable |
| protocol Foo {}; |
| |
| @discoverable |
| protocol Bar {}; |
| |
| @discoverable |
| protocol Baz {}; |
| |
| @discoverable |
| protocol Qux {}; |
| // [END service-hub-2] |
| |
| // [START boolean-enum] |
| type FileType = strict enum { |
| UNKNOWN = 0; |
| GIF = 1; |
| }; |
| // [END boolean-enum] |
| |
| // [START absence-1] |
| // BAD |
| protocol View3 { |
| ReplaceHitRegion(struct { |
| id uint64; |
| // Set to { -1, -1 } to remove. |
| size fuchsia.math.Rect; |
| }); |
| ReplaceName(struct { |
| // Set to "" to remove. |
| name string; |
| }); |
| }; |
| // [END absence-1] |
| |
| // [START absence-2] |
| protocol View4 { |
| ReplaceHitRegion(struct { |
| id uint64; |
| size box<fuchsia.math.Rect>; |
| }); |
| ReplaceName(struct { |
| name string:optional; |
| }); |
| }; |
| // [END absence-2] |