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++.
| Function | What it does | Parameters | Returns |
|---|---|---|---|
| Onscryn_Start | Starts the SDK for this process | Pointer to the options struct | 1 on success, 0 on failure |
| Onscryn_Stop | Stops the SDK and closes its connection | None | Nothing |
| Onscryn_Active | Tells you whether the SDK is running | None | 1 if running |
| Onscryn_SetCallbacks | Sets the events you want to receive | Pointer to the callbacks struct | Nothing |
| Onscryn_AcquireSurface | Gives you the device context to draw a frame into | Window handle, width, height | A device context, or null |
| Onscryn_Invalidate | Reports the part of the surface that changed | Window handle, a rectangle or null for everything | Nothing |
| Onscryn_Present | Sends the changed frame to the viewer | Window handle | Nothing |
| Onscryn_SetSurfaceRect | Says which screen rectangle the surface covers, so pointer positions map correctly | Screen x, y, width, height. A width or height of zero or less clears it | Nothing |
| Onscryn_TakeScreenshot | Writes the current surface to a bitmap file | Window handle, output path | 1 on success |
| Onscryn_Suspend | Stops sending frames but keeps the connection and your drawing | None | Nothing |
| Onscryn_Resume | Resumes sending, including everything that changed meanwhile | None | Nothing |
| Onscryn_IsSuspended | Tells you whether sending is paused | None | 1 if suspended |
| Onscryn_SetCursorType | Sets the cursor shape the viewer shows | A cursor value from 0 to 12 | Nothing |
| Onscryn_SetCursorImage | Gives the viewer the app's real cursor image | BGRA pixels, width, height (up to 128), hotspot x and y. Zero size clears it | Nothing |
| Onscryn_SetDragTuning | Tunes how a dragged window's title bar follows the pointer | Settle milliseconds (default 70), maximum interval (default 0) | Nothing |
| Onscryn_SendFile | Delivers a file on the host to the viewer's browser | Full path, download name or null, MIME type or null | 1 on success |
| Onscryn_OpenUrl | Asks the browser to open a link | URL | 1 on success |
| Onscryn_SendClipboard | Puts text on the viewer's clipboard | Text | 1 on success |
| Onscryn_EnablePrinting | Makes the Onscryn Printer the default and delivers its PDFs to the browser | Printer name, or null for the default name | 1 ready, 2 watching but printer not installed, 0 failed |
| Onscryn_ShowVirtualKeyboard | Asks the browser to show its on-screen keyboard (best effort) | None | 1 if queued |
| Onscryn_SendUiTree | Sends your own UI tree as JSON, if you turned the automatic one off | JSON text | 1 on success |
| Onscryn_RegisterAction | Registers a named action that workflows can call | Name (ASCII), description (ASCII), handler, user pointer | 1 on success, 0 if the name is empty or reserved or the handler is null |
| Onscryn_SendActionResult | Answers a call to a named action | The call's id, success flag, result JSON | 1 on success |
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.
| Callback | When it fires | What you receive |
|---|---|---|
| on_browser_resize | The viewer's browser window changed size | Width and height |
| on_input | A mouse or keyboard event arrived | A pointer to an input event |
| on_close | Onscryn wants the app to close, for example because the session ended | Nothing |
| on_clipboard | The user pasted text from their browser | The text |
| on_upload | The user uploaded a file | File name, bytes, length |
| on_drop | The user dropped a file onto the picture | File name, bytes, length, and the drop position from 0 to 1 across and down the surface |
| on_browserinfo | Once per session, with details of the viewer's browser | JSON: screen size, orientation, browser, pixel ratio, language |
| on_action | A named action was called and you registered none through the registry | Call id, action name, parameters as JSON |
Options
The struct passed to Onscryn_Start. Zero-initialize it so the defaults that suit most apps apply.
| Field | What it does | Default |
|---|---|---|
| instanceId | The session's instance id, from the command line | Required |
| transport | 0 writes frames to files for local testing, 1 streams to Onscryn | 0 |
| outputDir | Where file-dump frames and logs go | None |
| relayPipe | A custom pipe name. Leave null to use the default for the instance | null |
| appInvisible | 1 means never show a window on any desktop | 0 |
| tileQuality | Image quality from 1 to 100 | 80 when unset by the app's setting |
| tileFormat | 0 for WebP, 1 for JPEG, 2 for raw BGRA | 0 |
| disableAutoInjectInput | 1 turns off automatic delivery of browser input, so you handle it | 0 (automatic input is on) |
| disableAutoUiTree | 1 turns off the automatic UI tree, so you send your own | 0 (automatic UI tree is on) |
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.