Event ve host-RPC referansı

Bu sayfa evoX plugin protokolünün tam yüzeyidir: hosttan plugin’e gelen eventler ve plugin’den hosta giden host-RPC çağrıları. Tüm isimler @evox/plugin-protocol içindeki gerçek sözleşmedir; renderer/plugin payload’ı authoritative değildir, kimlik ve context host tarafından türetilir.

Sözleşme kuralları

Her binding örneği yalnız kendi bindingInstanceId context’i için geçerlidir. action.willDisappear sonrası display çağrısı CONTEXT_EXPIRED ile reddedilir.
Host-assigned session.plugin.pluginId tek authoritative kimliktir; event/RPC payload’ıyla başka kimlik seçilmez.
RPC çağrıları capability gerektirir. Declared/granted olmayan çağrı CAPABILITY_DENIED döner (bkz. Capability API’leri).
Hata davranışı fail-closed’dır; kodlar için Hata kodları.

Alınan eventler (host → plugin)

client.on(<event>, handler) ile kaydedilir. Handler’lar client.start() handshake’inden önce kaydedilmelidir.

Plugin yaşam döngüsü

Event	Ne zaman
`plugin.start`	Session kuruldu, `host.hello` alındı; plugin çalışmaya hazır
`plugin.stop`	Session kapatılıyor; handler cleanup ve `client.dispose()` çağır
`plugin.suspend`	Plugin geçici askıya alındı; yeni istek gönderme
`plugin.resume`	Askıdan döndü; normal işleme devam

Cihaz

Event	Ne zaman
`device.connected`	Bir cihaz bağlandı; payload cihaz kimliği ve boyut bilgisini taşır
`device.disconnected`	Cihaz kaldırıldı

Action binding

Event	Ne zaman
`action.willAppear`	Action örneği bir tuş/dial’a görünür oldu (uygulama açılışı, profil/sayfa geçişi, kullanıcı atadı)
`action.willDisappear`	Action örneği artık görünmüyor (profil/sayfa değişimi, atama silindi)
`action.keyDown`	Kullanıcı tuşa bastı
`action.keyUp`	Kullanıcı tuşu bıraktı
`action.dialDown`	Kullanıcı dial’a bastı
`action.dialUp`	Kullanıcı basılı dial’ı bıraktı
`action.dialRotate`	Kullanıcı dial’ı çevirdi; payload yön/adım bilgisini taşır
`action.settingsChanged`	Bu binding’in ayarları değişti; güncel `settings` payload’da

Her event event.context içinde actionId ve bindingInstanceId taşır. Plugin’in tanımadığı actionId ignore edilmelidir.

client.on('action.keyDown', async (event) => {
  if (event.context?.actionId !== 'counter') return;
  await client.setTitle(event.context.bindingInstanceId, '1');
});

client.on('action.willDisappear', (event) => {
  counters.delete(event.context?.bindingInstanceId);
});

Host-RPC çağrıları (plugin → host)

SDK client üzerinden çağrılır; her biri Promise döner ve fail-closed hata verir.

Tuş/ekran gösterimi — `key.display` capability

SDK metodu	RPC	Açıklama
`client.setTitle(context, title)`	`key.setTitle`	Binding başlığını değiştirir
`client.setImage(context, image)`	`key.setImage`	Binding görselini değiştirir (manifest-hash `assetId` veya bounded PNG/JPEG/WebP descriptor)
`client.setState(context, state)`	`key.setState`	Çok durumlu action için durumu değiştirir (0’dan başlar)
`client.showSuccess(context)`	`key.showSuccess`	Geçici başarı işareti gösterir
`client.showError(context)`	`key.showError`	Geçici hata işareti gösterir

await client.setTitle(context.bindingInstanceId, 'Hazır');
await client.showSuccess(context.bindingInstanceId);

Raw dosya yolu veya external URL kabul edilmez.

Ayar kalıcılığı

SDK metodu	RPC	Açıklama
`client.getSettings(context?)`	`settings.get`	Binding’e (veya context’siz plugin geneline) ait kalıcı ayarı okur
`client.patchSettings(settings, context?)`	`settings.patch`	Ayarı kısmi günceller; değişiklik `action.settingsChanged` ile geri yayılır

Token/password/client secret’ı normal ayara yazmayın. Credential için secret/OAuth API’lerini kullanın.

Plugin-scoped depolama — `storage.private` capability

SDK metodu	RPC	Açıklama
`client.storageGet(key)`	`storage.get`	Plugin’e özel bounded kotalı değeri okur
`client.storageSet(key, value)`	`storage.set`	Değeri yazar
`client.storageDelete(key)`	`storage.delete`	Değeri siler

Ağ ve credential — `network.fetch` / `secret.manage` / `oauth`

SDK metodu	RPC	Açıklama
`client.networkFetch(input)`	`network.fetch`	Declared HTTPS host/method/byte scope’unda istek
`client.networkFetchWithCredential(input)`	`network.fetchWithCredential`	Host, `{kind:'secret',name}` / `{kind:'oauth',provider}` referansını vault’tan çözüp izinli isteğe enjekte eder; raw token plugin’e dönmez
`client.hasSecret(name)`	`secret.has`	Secret var mı (byte döndürmez)
`client.deleteSecret(name)`	`secret.delete`	Secret’ı siler
`client.beginOAuth(provider)`	`oauth.begin`	OAuth akışını başlatır
`client.getOAuthStatus(provider)`	`oauth.status`	OAuth durumunu okur (token byte’ı dönmez)

Sistem — `system.openExternal` / `system.openPath`

RPC	Capability	Açıklama
`system.openExternal`	`system.openExternal`	HTTPS URL’yi varsayılan tarayıcıda açar
`system.openPath`	`system.openPath`	İzinli bir yolu sistemde açar

Bu iki çağrı protokolde tanımlı ve capability korumalıdır; ayrı bir SDK kısayol metodu olmadan generic istek yolundan kullanılır.

Notlar

Bu referans mevcut protokol sürümünü yansıtır; capability adları ve limitler Capability API’leri sayfasında normatiftir.
Public dağıtım sınırı ve T1/T2/T3 farkları için Güven katmanları ve Dağıtım durumu.

Başlangıç

Temel kavramlar

Örnekler ve dağıtım

Event ve host-RPC referansı

Sözleşme kuralları

Alınan eventler (host → plugin)

Plugin yaşam döngüsü

Cihaz

Action binding

Host-RPC çağrıları (plugin → host)

Tuş/ekran gösterimi — `key.display` capability

Ayar kalıcılığı

Plugin-scoped depolama — `storage.private` capability

Ağ ve credential — `network.fetch` / `secret.manage` / `oauth`

Sistem — `system.openExternal` / `system.openPath`

Notlar

​Sözleşme kuralları

​Alınan eventler (host → plugin)

​Plugin yaşam döngüsü

​Cihaz

​Action binding

​Host-RPC çağrıları (plugin → host)

​Tuş/ekran gösterimi — key.display capability

​Ayar kalıcılığı

​Plugin-scoped depolama — storage.private capability

​Ağ ve credential — network.fetch / secret.manage / oauth

​Sistem — system.openExternal / system.openPath

​Notlar

Sözleşme kuralları

Alınan eventler (host → plugin)

Plugin yaşam döngüsü

Cihaz

Action binding

Host-RPC çağrıları (plugin → host)

Tuş/ekran gösterimi — `key.display` capability

Ayar kalıcılığı

Plugin-scoped depolama — `storage.private` capability

Ağ ve credential — `network.fetch` / `secret.manage` / `oauth`

Sistem — `system.openExternal` / `system.openPath`

Notlar