SDK · ABI 1.0

把截图能力嵌进你的程序

一个 dll,7 个 C 函数。框选、自动选窗、控件检测、标注、长截图这些界面部分都白送——你只负责决定图往哪去:剪贴板,还是磁盘上的文件。

与 exe 同源

dll 和绿色版是同一份代码、同一套皮肤,用户看到的框选界面和主程序一模一样,不会出现"嵌进来的是另一个软件"的割裂感。

界面一致无需安装

静默出图

指定 XSNIP_MODE_FILE 加一个目录,框完直接落盘,不弹保存框、不碰剪贴板。批量化截图工具不需要为每一张都问一次用户。

不弹窗PNG / WebP / PDF

C ABI,不锁语言

纯 C 导出、__cdecl、UTF-16 路径。C / C++ / C# / Delphi / Go(cgo) 都能直接调,xsnip.def 里就 10 行符号,没有 C++ 修饰名。

P/Invoke 友好x86 + x64
Get

加微信,找作者要包

SDK 不在站上公开下载,也没有自动回复的下载链接。加微信说一句你要做什么,我直接把当前最新的包发给你——省得拿到过期版本,ABI 有变动也好通知到你。

点击显示二维码

微信扫码

备注一句「xsnip SDK」。工作日一般当天回,晚上和周末可能慢一点;赶着上线先把时间点说清楚。

顺手告诉我三件事

这三条决定我发哪个包,一次说清能省一个来回:

  • 宿主语言 —— C/C++、C#、Delphi、Go(cgo)…,我按你的语言给对应的声明写法
  • 位数 —— 宿主 32 位就拿 x86 的 dll,64 位拿 x64,两者不能混用
  • 要不要符号 —— 发布包不带 pdb(各 14 MB),要调试再单独发
不公开下载免费商用
包内文件用途
xsnip.dll运行时。跟宿主 exe 放同一目录,或放进系统 PATH;皮肤、图标全部内嵌,不需要附带别的资源。
xsnip_c.h唯一对三方承诺稳定的头文件。接入时只需要它,别 include 工程内部的 xsnip.h。
xsnip.libMSVC 导入库。MinGW / 非 MSVC 编译器直接 LoadLibrary + GetProcAddress,或按 xsnip.def 自己生成 .a。
xsnip.def导出表,7 个函数、无修饰名。C# / Delphi 写声明时对着它核对名字与调用约定。
NOTEdll 没有签名,某些杀软对"刚下载的 dll 被别的程序加载"会拦一下,加白名单即可。位数必须和宿主一致:32 位进程加载 x64 dll 会直接报 193(%1 不是有效的 Win32 应用程序)。
Quick start

三步跑通

建会话 → 发起截图 → 销毁。项目属性里加一句 xsnip.lib;user32.lib,把 xsnip.dll 和 xsnip_c.h 放好就能编。

C++ · 最小可用xsnip_demo.cpp
// cl xsnip_demo.cpp xsnip.lib user32.lib
#include <windows.h>
#include <stdio.h>
#include "xsnip_c.h"

static HANDLE g_done;

// 回调跑在截图工作线程上:这里只做通知,别碰宿主 UI
static void XSNIP_CALL OnDone(void* user, const XSnipResultInfo* info)
{
    if (info->code == XSNIP_OK && info->output == XSNIP_OUTPUT_FILE)
        wprintf(L"已保存:%s\n", info->file_path);
    else
        wprintf(L"没出图,code=%d\n", info->code);
    SetEvent(g_done);
}

int main()
{
    g_done = CreateEventW(NULL, TRUE, FALSE, NULL);

    XSnipHandle h = NULL;
    if (XSnipCreate(NULL, OnDone, NULL, &h) != XSNIP_OK)
        return 1;

    XSnipCaptureOptions opt = { sizeof(opt) };
    opt.delay_ms         = 300;              // 让调用方窗口先退到后面
    opt.output           = XSNIP_MODE_FILE;
    opt.format           = XSNIP_FORMAT_PNG;
    opt.show_save_dialog = 0;                // 不弹保存框
    opt.file_path        = L"D:\\shots";      // 给目录 -> 自动拼文件名
    XSnipCapture(h, &opt);

    WaitForSingleObject(g_done, 60000);       // 用户可能慢慢框,给够时间
    XSnipDestroy(h);                           // FreeLibrary 之前必须先调
    CloseHandle(g_done);
    return 0;
}
THREAD回调在截图工作线程执行,不是宿主的 UI 线程。要在回调里更新界面,请改用 notify_wnd:消息到了再从 UI 线程调 XSnipGetLastResult 取结果。回调里的 info 只在本次回调期间有效,要留自己拷。
Reference

七个函数

全部 __cdecl。除 XSnipDestroy 返回 void,其余返回结果码,0 才算成功。

函数说明
XSnipGetAbiVersion()返回 1。宿主启动时比一下,能提前发现"dll 版本比头文件老"的情况,比后面结构体错位崩掉好查。
XSnipGetVersion()返回形如 L"1.1.0.12" 的版本串,静态生命周期,不要 free。
XSnipCreate(cfg, cb, user, &handle)建会话并拉起常驻 UI 线程。cfg / cb 都可以传 NULL;只关心结果的话给 notify_wnd 就够了。成功时配套调用 XSnipDestroy。
XSnipCapture(handle, opt)发起一次截图,立即返回,结果通过回调或窗口消息通知。opt 传 NULL 等价于全默认:不延迟、输出跟界面按钮走。
XSnipCancel(handle)请求取消进行中的截图,等价于用户按 Esc。当前没在截图时返回 XSNIP_OK,可以无条件调。
XSnipGetLastResult(&info)取最近一次结果,线程安全,给 notify_wnd 的消息处理用。从没结束过任何一次截图时返回 XSNIP_E_NOT_INIT。
XSnipDestroy(handle)请求 UI 线程退出并 join,释放资源,重复调用安全。返回后 handle 失效。FreeLibrary 之前必须先调它,否则线程还在跑,进程会崩。
Structs

两个结构体

所有入参结构体第一个字段都是 size = sizeof(...)。以后加字段只往后追加,DLL 只读 size 覆盖到的那部分,老宿主不用重编。

C · 声明xsnip_c.h
typedef struct XSnipConfig {
    unsigned int   size;              // = sizeof(XSnipConfig)
    const wchar_t* watermark;         // 平铺水印,NULL/空 = 不加
    const wchar_t* file_name_prefix;  // 文件名前缀,NULL/空 = "xsnip"
    const wchar_t* config_dir;        // xsnip.ini 目录,NULL/空 = dll 同目录
} XSnipConfig;

typedef struct XSnipCaptureOptions {
    unsigned int size;                // = sizeof(XSnipCaptureOptions)
    HWND         notify_wnd;          // 非空:完成时 PostMessage(wnd, msg, 0, 0)
    unsigned int notify_msg;          // 0 = XSNIP_WM_DONE(WM_APP + 0x5A)
    unsigned int delay_ms;            // 延迟多少毫秒再抓,0 = 立刻

    int            output;            // XSnipOutputMode,默认 UI
    int            format;            // XSnipFormat,output=FILE 时有效
    int            quality;           // 1..100,0 = 默认(JPG 50 / WebP 75)
    int            show_save_dialog;  // FILE 时:1 = 弹系统保存框,0 = 直接写
    const wchar_t* file_path;         // 完整路径 / 目录 / NULL
} XSnipCaptureOptions;
file_path 给什么行为
带扩展名的完整路径直接写到这个文件,同名覆盖,不弹框。目录不存在时会自动建。
目录(末尾带 \ 或已存在)按 file_name_prefix + 时间戳自动拼文件名,扩展名跟 format 走。
NULL / 空串用 xsnip.ini 里配置的存储目录;没配过就走默认"图片\xsnip"。
format说明
XSNIP_FORMAT_AUTO按 file_path 的扩展名判断,没扩展名按 PNG。
XSNIP_FORMAT_PNG / BMP无损,quality 被忽略。
XSNIP_FORMAT_JPG / WEBP有损,quality 1–100 生效;WebP 传默认值时走无损编码。
XSNIP_FORMAT_PDF单页 PDF,FlateDecode 无损压缩,适合直接当附件发走。
Result codes

结果码

复用一套码:函数返回值和 XSnipResultInfo.code 是同一个枚举。

码含义 / 怎么处理
XSNIP_OK = 0成功。截图的"成功"还要看 output:去了剪贴板还是文件。
XSNIP_E_FAILED = 1一般失败(抓屏失败、写文件失败)。可以直接提示用户重试。
XSNIP_E_NOT_INIT = 2未初始化 / 句柄无效,或还没产生过任何结果。
XSNIP_E_BUSY = 3上一次截图还没结束。等回调或消息再来。
XSNIP_E_INVALID_ARG = 4空指针,或结构体 size 与 DLL 期望的不匹配(通常是头文件和 dll 不是同一版)。
XSNIP_E_ALREADY = 5已有未销毁的会话。进程内单实例,先 XSnipDestroy 再建。
XSNIP_E_CANCELLED = 6用户按 Esc 或调了 XSnipCancel。属于正常路径,别当错误弹框。
C#

P/Invoke 写法

导出名不带修饰,所以声明里不用 EntryPoint;注意 CallingConvention.Cdecl 和 LPWStr。

C# · WinFormsXSnip.cs
using System;
using System.Runtime.InteropServices;

static class XSnip
{
    const string Dll = "xsnip.dll";
    public const int WM_DONE = 0x8000 + 0x5A;   // WM_APP + 0x5A

    [StructLayout(LayoutKind.Sequential)]
    public struct Options
    {
        public uint     size;
        public IntPtr   notify_wnd;
        public uint     notify_msg;
        public uint     delay_ms;
        public int      output, format, quality, show_save_dialog;
        [MarshalAs(UnmanagedType.LPWStr)] public string file_path;
    }

    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
    public struct Result
    {
        public uint size;
        public int  code, output;
        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 1024)]
        public string file_path;
    }

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern int XSnipCreate(IntPtr cfg, IntPtr cb, IntPtr user, out IntPtr handle);

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern int XSnipCapture(IntPtr handle, ref Options opt);

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern int XSnipGetLastResult(ref Result info);

    [DllImport(Dll, CallingConvention = CallingConvention.Cdecl)]
    public static extern void XSnipDestroy(IntPtr handle);
}
C# · 用法Form1.cs
protected override void OnHandleCreated(EventArgs e)
{
    base.OnHandleCreated(e);
    XSnip.XSnipCreate(IntPtr.Zero, IntPtr.Zero, IntPtr.Zero, out _h);
}

protected override void WndProc(ref Message m)
{
    if (m.Msg == XSnip.WM_DONE)          // 已经回到 UI 线程了
    {
        var r = new XSnip.Result { size = (uint)Marshal.SizeOf<XSnip.Result>() };
        if (XSnip.XSnipGetLastResult(ref r) == 0 && r.code == 0)
            label1.Text = r.output == 2 ? "已保存 " + r.file_path : "已复制到剪贴板";
    }
    base.WndProc(ref m);
}

void Shot()
{
    var opt = new XSnip.Options
    {
        size = (uint)Marshal.SizeOf<XSnip.Options>(),
        notify_wnd = Handle,
        notify_msg = XSnip.WM_DONE,
        output = 2, format = 1, show_save_dialog = 0,
        file_path = @"D:\shots"
    };
    XSnip.XSnipCapture(_h, ref opt);
}
Threads

线程与生命周期

接入时踩坑最多的不是函数怎么调,是"谁来等结果、dll 什么时候能卸载"。

场景约定
收到结果两种:给 notify_wnd 走窗口消息(UI 线程,推荐);给回调走截图线程(必须自己切线程)。两个都给时两个都会通知。
能不能并发截两张不能。同一时刻只允许一次,第二次 XSnipCapture 返回 XSNIP_E_BUSY。
能不能开多个会话不能,进程内单实例。多窗口宿主共用一个句柄。
什么时候能 FreeLibrary必须先 XSnipDestroy。它会 join 掉 UI 线程;不调就卸载,线程还在跑,进程崩。
dll 和绿色版冲突吗不冲突。单实例是进程内的,跟用户自己装/解压的 xsnip.exe 互不干扰。
配置从哪来XSnipConfig.config_dir 下的 xsnip.ini(水印、默认存储目录等)。不传就看 dll 同目录。
ABI当前 ABI = 1。不兼容的变化(改函数签名、结构体字段顺序)才会 +1;新增字段一律追加在末尾,老宿主继续可用。宿主启动时会 XSnipGetAbiVersion 比一下,比什么都稳。
FAQ

常见问题

宿主需要额外装 xsnip 吗?

不需要。dll 自带界面、皮肤和图像处理,拷一个文件过去就能用,绿色无依赖。

能直接拿到 PNG 字节流吗?

当前 ABI 只有「剪贴板」和「文件」两种输出,没有内存流接口。要字节流可以先存临时文件再读,或者走剪贴板。改成回调返回内存指针属于不兼容变更,要等 ABI 2。

dll 多大?会不会拖慢启动?

x64 约 2.7 MB、x86 约 2.4 MB,皮肤和图标都内嵌。只在 XSnipCreate 时拉起 UI 线程,不占常驻内存大户。

能改框选界面吗?

不能。界面是 xsnip 自己的皮肤,只开放结果和少量行为(延迟、输出、水印、文件名前缀)。把界面换掉等于重写产品,不在 SDK 范围内。

用户按 Esc 取消会怎样?

回调 / 消息照常到达,code = XSNIP_E_CANCELLED、output = XSNIP_OUTPUT_NONE。这是正常路径,别弹错误框。

商用要授权吗?

SDK 随 xsnip 一起免费分发,闭源商用也可以。唯一的要求是别把 dll 改名后当成自己的产品卖。

先跑通再说

包里有头文件和导入库,代码贴进工程编一次,十分钟就知道合不合用。要包就加微信,说清宿主语言和位数即可。