Class SnapServer

Represents a connection to an Snap Server instance that can be used to control interactions with the server.

Hierarchy

SnapServer

Constructors

constructor

new SnapServer(server_id): SnapServer
Constructs a new instance of the Snap client object ready to connect to the given instance id

This should match the id of the server instance that is running which is the default case when using the Snap Server API, SnapServer.start
Parameters
- server_id: string
  
  The instance of the server that will be started or connected to
Returns SnapServer
Example
```
const server = new Snap.SnapServer('test');
```

Properties

`Optional` client

client?: ChannelClient

emitter

emitter: EventEmitter = ...

`Optional` need_to_reset_layout

need_to_reset_layout?: boolean

server_id

server_id: string

The instance of the server that will be started or connected to

`Optional` snap_identity

snap_identity?: Identity_5

Methods

addEventListener

addEventListener<TEventName>(eventName, handler): void
Adds an event handler for the given event
Type Parameters
- TEventName extends "all-events" | "client-registered" | "client-unregistered" | "move-size-completed" | "clients-attached" | "client-detached" | "groups-changed" | "client-activated" | "client-deactivated"
Parameters
- eventName: TEventName
  
  The name of the event to listen for SnapServerEventTypes
- handler: ((...eventArg) => void)
  
  The handler to call when the event is fired
  - - (...eventArg): void
    - Parameters
      
      Rest ...eventArg: SnapServerEventTypes[TEventName]
      Rest
      
      Returns void
Returns void
void

See
SnapServerEventTypes

applySnapshot

applySnapshot(snapshot): Promise<void>

Given a snapshot, extracts the Snap layout, if any, and applies it to the current Snap Server

Parameters

snapshot: SnapSnapshot

The OpenFin.Snapshot to apply

Returns Promise<void>

Example

This example shows how to implement a snapshot override that decorates a snapshot with the current Snap layout

  fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...overrideArgs) => {
     try {
       class WithSnap extends PlatformProvider {
         async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]): Promise<OpenFin.Snapshot> {
           const snapshot = await super.getSnapshot(...args);
           const snapSnapshot = await SnapServer.decorateSnapshot(snapshot);
           return snapSnapshot;
         }
          async applySnapshot(...args: [OpenFin.ApplySnapshotPayload, OpenFin.ClientIdentity]): Promise<void> {
           await SnapServer.prepareToApplySnapshot();
           await super.applySnapshot(...args);
           await SnapServer.applySnapshot(args[0].snapshot);
         }
       }
       return new WithSnap(...overrideArgs);
     } catch (error) {
       return new PlatformProvider();
     }
   },
});

attachWindows

attachWindows(targetClientId, toAttachClientId, targetSide, offset): Promise<void>
Attaches two windows together on a specified side and at a specified offset
Parameters
- targetClientId: string
  
  The client id of the window to attach to
- toAttachClientId: string
  
  The client id of the window to attach
- targetSide: AttachSide
  
  The side of the target window to attach to
- offset: number
  
  The offset from the target window side to attach to
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there are two windows with the client ids 'my-client-id-1' and 'my-client-id-2'
await server.attachWindows('my-client-id-1', 'my-client-id-2', 'left', 0);
```

`Private` build_command_line

build_command_line(options?): Promise<string>
Parameters
- Optional options: ServerOptions
  Optional
Returns Promise<string>

connect

connect(): Promise<void>
Connects to an already running Snap Server instance

Use this if the Snap server has been manually started or when wanting to interact with Snap from another part of an application. For example the Snap server was started as part of a platform provider and a view would like to also interact with Snap.

Returns Promise<void>
Promise
Example
Shows how to connect to an already running Snap Server instance with the id 'test'
```
const server = new Snap.SnapServer('test');
await server.connect();
```

decorateSnapshot

decorateSnapshot(snapshot): Promise<SnapSnapshot>

Given a snapshot, decorates it with the current Snap layout and returns it

Parameters

snapshot: Snapshot

The OpenFin.Snapshot to decorate

Returns Promise<SnapSnapshot>

A Promise resolving to an instance of SnapSnapshot which contains both the original snapshot and the Snap layout

Example

This example shows how to implement a snapshot override that decorates a snapshot with the current Snap layout

  fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...overrideArgs) => {
     try {
       class WithSnap extends PlatformProvider {
         async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]): Promise<OpenFin.Snapshot> {
           const snapshot = await super.getSnapshot(...args);
           const snapSnapshot = await SnapServer.decorateSnapshot(snapshot);
           return snapSnapshot;
         }
          async applySnapshot(...args: [OpenFin.ApplySnapshotPayload, OpenFin.ClientIdentity]): Promise<void> {
           await SnapServer.prepareToApplySnapshot();
           await super.applySnapshot(...args);
           await SnapServer.applySnapshot(args[0].snapshot);
         }
       }
       return new WithSnap(...overrideArgs);
     } catch (error) {
       return new PlatformProvider();
     }
   },
});

`Private` defaultClientIdMapper

defaultClientIdMapper(existingClientId): string
Parameters
- existingClientId: string
Returns string

detachFromGroup

detachFromGroup(clientId): Promise<void>

Detaches the given window from any other windows it is attached to

Parameters

clientId: string

The client id of the window to detach

Returns Promise<void>

Promise

Example

const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the client id 'my-client-id'
await server.detachFromGroup('my-client-id');

`Private` emit_event

emit_event<TEventName>(eventName, ...eventArg): void
Type Parameters
- TEventName extends "all-events" | "client-registered" | "client-unregistered" | "move-size-completed" | "clients-attached" | "client-detached" | "groups-changed" | "client-activated" | "client-deactivated"
Parameters
- eventName: TEventName
- Rest ...eventArg: SnapServerEventTypes[TEventName]
  Rest
Returns void

enableAutoWindowRegistration

enableAutoWindowRegistration(): Promise<(() => Promise<void>)>

Listens for new windows being created within the platform automatically registers them with the Snap Server

Returns Promise<(() => Promise<void>)>

A function that can be called to stop listening for new windows

Example

Setup for automatic registration of new windows and creates a new window

const server = new Snap.SnapServer('test');
await server.connect();
server.enableAutoWindowRegistration();

// The following new Window will automatically be registered with Snap
const newView = await fin.Platform.wrapSync(fin.Platform.getCurrentSync().identity).createView({
   name: 'new-view',
   url: 'https://my-own-content.com',
});

`Private` getAppAssetExecutablePath

getAppAssetExecutablePath(appAssetInfo): Promise<string>
Get the executable path for an app asset.
Parameters
- appAssetInfo: {
      alias: string;
      target: string;
      version: string;
  }
  
  The app asset information.
  - alias: string
    
    The app asset alias information.
  - target: string
    
    The app asset target information.
  - version: string
    
    The app asset version information.
Returns Promise<string>
The native path for the asset.

getAttached

getAttached(clientId): Promise<string[]>
Gets a list of windows that are attached to the given window
Parameters
- clientId: string
  
  The client id of the window to get the attached windows for
Returns Promise<string[]>
string[] - A promise resolving to a list of client ids of the attached windows
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the client id 'my-client-id'
const attachedWindows = await server.getAttached('my-client-id');
```

getLayout

getLayout(): Promise<SnapLayout>
Retrieves the current layout

Returns Promise<SnapLayout>
The layout object

`Private` handleNewWindow

handleNewWindow(event): Promise<void>
Parameters
- event: NamedEvent
Returns Promise<void>

`Private` handleSnapEvents

handleSnapEvents(payload, identity): void
Parameters
- payload: any
- identity: Identity_5
Returns void

hasAttachments

hasAttachments(clientId): Promise<boolean>

Checks if the given window has any attachments

Parameters

clientId: string

The client id of the window to check

Returns Promise<boolean>

Promise - True if the window has attachments, false otherwise

Example

const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the client id 'my-client-id'
const hasAttachments = await server.hasAttachments('my-client-id');

launch

launch(options): Promise<LaunchResult>
Launches a new process and registers it with the Snap Server
Parameters
- options: LaunchOptions
  
  a set of options specifying the process to launch LaunchOptions
Returns Promise<LaunchResult>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();
await server.launch({
  path: 'C:\\Windows\\System32\\notepad.exe',
  client_id: 'my-notepad-client-id',
});
```

once

once<TEventName>(eventName, handler): void
Adds an event handler for the given event that will only be called once
Type Parameters
- TEventName extends "all-events" | "client-registered" | "client-unregistered" | "move-size-completed" | "clients-attached" | "client-detached" | "groups-changed" | "client-activated" | "client-deactivated"
Parameters
- eventName: TEventName
  
  The name of the event to listen for
- handler: ((...eventArg) => void)
  
  The handler to call when the event is fired
  - - (...eventArg): void
    - Parameters
      
      Rest ...eventArg: SnapServerEventTypes[TEventName]
      Rest
      
      Returns void
Returns void
void

See
SnapServerEventTypes

prepareToApplySnapshot

prepareToApplySnapshot(snapshotPayload?, customClientIdMapper?): Promise<void>
Prepares the Snap server to apply a new snapshot, potentially modifying the given payload
Parameters
- Optional snapshotPayload: ApplySnapshotPayload
  
  The payload for applySnapshot
  
  Optional
- Optional customClientIdMapper: ((id) => string)
  
  An optional mapper function for renaming any client IDs in the snapshot that are already in use in Snap. If not provided, then a default mapper function will be used when necessary, whose logic is as follows: For IDs containing three or more parts separated by a '/', the last part will be replaced with a new GUID. For other IDs, the the entire ID will be replaced with a new GUID. For example, <prefix>/<appId>/<instanceId> would be replaced with <prefix>/<appId>/<a new GUID>, and <another client ID> would be replaced with <a new GUID>. Client IDs referenced in the snapshot payload that are not already in use in Snap will be unchanged.
  
  Optional
  - - (id): string
    - Parameters
      
      id: string
      
      Returns string
Returns Promise<void>
Promise
Example
This example shows how to implement a snapshot override that decorates a snapshot with the current Snap layout
```
  fin.Platform.init({
    overrideCallback: async (PlatformProvider, ...overrideArgs) => {
     try {
       class WithSnap extends PlatformProvider {
         async getSnapshot(...args: [undefined, OpenFin.ClientIdentity]): Promise<OpenFin.Snapshot> {
           const snapshot = await super.getSnapshot(...args);
           const snapSnapshot = await SnapServer.decorateSnapshot(snapshot);
           return snapSnapshot;
         }
           async applySnapshot(payload: OpenFin.ApplySnapshotPayload, identity?: OpenFin.Identity): Promise<void> {
             await snapServer.prepareToApplySnapshot(payload);
             await super.applySnapshot(payload, identity);
             await snapServer.applySnapshot(payload.snapshot);
           }
       }
       return new WithSnap(...overrideArgs);
     } catch (error) {
       return new PlatformProvider();
     }
   },
});
```

registerWindow

registerWindow(clientId, windowHandle): Promise<void>
Registers the given platform native window handle with the Snap Server
Parameters
- clientId: string
  
  The client id to register the window with
- windowHandle: string
  
  The native window handle to register
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

// Assuming there is a window with the native id '0x0000000000001234'
await server.registerWindow('my-client-id', '0x0000000000001234');
```

removeEventListener

removeEventListener<TEventName>(eventName, handler): void
Removes an event handler for the given event
Type Parameters
- TEventName extends "all-events" | "client-registered" | "client-unregistered" | "move-size-completed" | "clients-attached" | "client-detached" | "groups-changed" | "client-activated" | "client-deactivated"
Parameters
- eventName: TEventName
  
  The name of the event to remove the handler for
- handler: ((...eventArg) => void)
  
  The handler to remove
  - - (...eventArg): void
    - Parameters
      
      Rest ...eventArg: SnapServerEventTypes[TEventName]
      Rest
      
      Returns void
Returns void
void

See
SnapServerEventTypes

`Private` replaceCustomDataClientId

replaceCustomDataClientId(input, oldClientId, newClientId): void
Parameters
- input: any
- oldClientId: string
- newClientId: string
Returns void

setLayout

setLayout(layout, reset?): Promise<void>
Restores the given layout
Parameters
- layout: SnapLayout
  
  The layout object to restore
- reset: boolean = true
  
  Whether existing snap connections should be reset
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.connect();

const myLayout = { ... }
await server.setLayout(myLayout);
```

start

start(options?): Promise<void>
Starts a new instance of Snap Server and connects to it passing an optional set of parameters
Parameters
- Optional options: ServerOptions
  
  Options for the started server ServerOptions
  
  Optional
Returns Promise<void>
Promise
Example
```
const server = new Snap.SnapServer('test');
await server.start();
```

stop

stop(): Promise<void>
Shuts down the connected Snap Server instance

Returns Promise<void>
Promise

Class SnapServer

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

server_id: string

Returns SnapServer

Example

Properties

Optional client

emitter

Optional need_to_reset_layout

server_id

Optional snap_identity

Methods

addEventListener

Type Parameters

TEventName extends "all-events" | "client-registered" | "client-unregistered" | "move-size-completed" | "clients-attached" | "client-detached" | "groups-changed" | "client-activated" | "client-deactivated"

Parameters

eventName: TEventName

handler: ((...eventArg) => void)

Parameters

Rest ...eventArg: SnapServerEventTypes[TEventName]

Returns void

Returns void

See

applySnapshot

Parameters

snapshot: SnapSnapshot

Returns Promise<void>

Example

attachWindows

Parameters

targetClientId: string

toAttachClientId: string

targetSide: AttachSide

offset: number

Returns Promise<void>

Example

Private build_command_line

Parameters

Optional options: ServerOptions

Returns Promise<string>

connect

Returns Promise<void>

Example

decorateSnapshot

Parameters

snapshot: Snapshot

Returns Promise<SnapSnapshot>

Example

Private defaultClientIdMapper

Parameters

existingClientId: string

Returns string

detachFromGroup

Parameters

clientId: string

Returns Promise<void>

Example

Private emit_event

Type Parameters

TEventName extends "all-events" | "client-registered" | "client-unregistered" | "move-size-completed" | "clients-attached" | "client-detached" | "groups-changed" | "client-activated" | "client-deactivated"

Parameters

eventName: TEventName

Rest ...eventArg: SnapServerEventTypes[TEventName]

Returns void

enableAutoWindowRegistration

Returns Promise<(() => Promise<void>)>

Example

Private getAppAssetExecutablePath

Parameters

appAssetInfo: { alias: string; target: string; version: string; }

alias: string

target: string

version: string

`Optional` client

`Optional` need_to_reset_layout

`Optional` snap_identity

`Rest` ...eventArg: SnapServerEventTypes[TEventName]

`Private` build_command_line

`Optional` options: ServerOptions

`Private` defaultClientIdMapper

`Private` emit_event

`Rest` ...eventArg: SnapServerEventTypes[TEventName]

`Private` getAppAssetExecutablePath

appAssetInfo: {
alias: string;
target: string;
version: string;
}

`Private` handleNewWindow

`Private` handleSnapEvents

`Rest` ...eventArg: SnapServerEventTypes[TEventName]

`Optional` snapshotPayload: ApplySnapshotPayload

`Optional` customClientIdMapper: ((id) => string)

`Rest` ...eventArg: SnapServerEventTypes[TEventName]

`Private` replaceCustomDataClientId