onscryn

SDK API reference

10 min read

The SDK is a flat C interface exported by Onscryn.Capture.dll and declared in onscryn_capture.h. Every call below is a plain function, so it works from C, C++, .NET and any other language that can call a C library. Functions that can fail return 1 on success and 0 on failure unless stated.

Functions

Grouped by purpose. All are cdecl, and the header declares them for you in C and C++.

Every SDK function, grouped by purpose
FunctionWhat it doesParametersReturns
Onscryn_StartStarts the SDK for this processPointer to the options struct1 on success, 0 on failure
Onscryn_StopStops the SDK and closes its connectionNoneNothing
Onscryn_ActiveTells you whether the SDK is runningNone1 if running
Onscryn_SetCallbacksSets the events you want to receivePointer to the callbacks structNothing
Onscryn_AcquireSurfaceGives you the device context to draw a frame intoWindow handle, width, heightA device context, or null
Onscryn_InvalidateReports the part of the surface that changedWindow handle, a rectangle or null for everythingNothing
Onscryn_PresentSends the changed frame to the viewerWindow handleNothing
Onscryn_SetSurfaceRectSays which screen rectangle the surface covers, so pointer positions map correctlyScreen x, y, width, height. A width or height of zero or less clears itNothing
Onscryn_TakeScreenshotWrites the current surface to a bitmap fileWindow handle, output path1 on success
Onscryn_SuspendStops sending frames but keeps the connection and your drawingNoneNothing
Onscryn_ResumeResumes sending, including everything that changed meanwhileNoneNothing
Onscryn_IsSuspendedTells you whether sending is pausedNone1 if suspended
Onscryn_SetCursorTypeSets the cursor shape the viewer showsA cursor value from 0 to 12Nothing
Onscryn_SetCursorImageGives the viewer the app's real cursor imageBGRA pixels, width, height (up to 128), hotspot x and y. Zero size clears itNothing
Onscryn_SetDragTuningTunes how a dragged window's title bar follows the pointerSettle milliseconds (default 70), maximum interval (default 0)Nothing
Onscryn_SendFileDelivers a file on the host to the viewer's browserFull path, download name or null, MIME type or null1 on success
Onscryn_OpenUrlAsks the browser to open a linkURL1 on success
Onscryn_SendClipboardPuts text on the viewer's clipboardText1 on success
Onscryn_EnablePrintingMakes the Onscryn Printer the default and delivers its PDFs to the browserPrinter name, or null for the default name1 ready, 2 watching but printer not installed, 0 failed
Onscryn_ShowVirtualKeyboardAsks the browser to show its on-screen keyboard (best effort)None1 if queued
Onscryn_SendUiTreeSends your own UI tree as JSON, if you turned the automatic one offJSON text1 on success
Onscryn_RegisterActionRegisters a named action that workflows can callName (ASCII), description (ASCII), handler, user pointer1 on success, 0 if the name is empty or reserved or the handler is null
Onscryn_SendActionResultAnswers a call to a named actionThe call's id, success flag, result JSON1 on success
All functions use the cdecl convention. Strings are UTF-16 unless noted.

Callbacks

Pass a callbacks struct to Onscryn_SetCallbacks. Every member is optional, and the user pointer is handed back to each callback unchanged. Callbacks arrive on SDK threads. Keep the structure and every delegate alive for the life of the process.

The events the SDK can report to your app
CallbackWhen it firesWhat you receive
on_browser_resizeThe viewer's browser window changed sizeWidth and height
on_inputA mouse or keyboard event arrivedA pointer to an input event
on_closeOnscryn wants the app to close, for example because the session endedNothing
on_clipboardThe user pasted text from their browserThe text
on_uploadThe user uploaded a fileFile name, bytes, length
on_dropThe user dropped a file onto the pictureFile name, bytes, length, and the drop position from 0 to 1 across and down the surface
on_browserinfoOnce per session, with details of the viewer's browserJSON: screen size, orientation, browser, pixel ratio, language
on_actionA named action was called and you registered none through the registryCall id, action name, parameters as JSON
Every callback also receives the user pointer you set. Leave any you do not need as null.

Options

The struct passed to Onscryn_Start. Zero-initialize it so the defaults that suit most apps apply.

The options passed to Onscryn_Start
FieldWhat it doesDefault
instanceIdThe session's instance id, from the command lineRequired
transport0 writes frames to files for local testing, 1 streams to Onscryn0
outputDirWhere file-dump frames and logs goNone
relayPipeA custom pipe name. Leave null to use the default for the instancenull
appInvisible1 means never show a window on any desktop0
tileQualityImage quality from 1 to 10080 when unset by the app's setting
tileFormat0 for WebP, 1 for JPEG, 2 for raw BGRA0
disableAutoInjectInput1 turns off automatic delivery of browser input, so you handle it0 (automatic input is on)
disableAutoUiTree1 turns off the automatic UI tree, so you send your own0 (automatic UI tree is on)
Zero-initialize the struct. The two disable fields are inverted on purpose, so an untouched struct gives the behavior that works out of the box.

Input events

The input callback receives this structure. The type field is one of mousemove, mousedown, mouseup, dblclick, wheel, keydown, keyup or clipboard. Positions are normalized from zero to one across the window rectangle, the button is zero for left, one for middle and two for right, and the code field is the browser's key code such as KeyA or Enter.

Cursor shapes

Pass one of these values to Onscryn_SetCursorType: 0 default arrow, 1 text, 2 pointer, 3 wait, 4 progress, 5 east-west resize, 6 north-south resize, 7 and 8 diagonal resize, 9 move, 10 crosshair, 11 not allowed, and 12 none, for an app that draws its own cursor into the picture. Older viewers do not know 12 and fall back to the arrow.

Want it set up
with you?