一个 dll,7 个 C 函数。框选、自动选窗、控件检测、标注、长截图这些界面部分都白送——你只负责决定图往哪去:剪贴板,还是磁盘上的文件。
dll 和绿色版是同一份代码、同一套皮肤,用户看到的框选界面和主程序一模一样,不会出现"嵌进来的是另一个软件"的割裂感。
指定 XSNIP_MODE_FILE 加一个目录,框完直接落盘,不弹保存框、不碰剪贴板。批量化截图工具不需要为每一张都问一次用户。
纯 C 导出、__cdecl、UTF-16 路径。C / C++ / C# / Delphi / Go(cgo) 都能直接调,xsnip.def 里就 10 行符号,没有 C++ 修饰名。
SDK 不在站上公开下载,也没有自动回复的下载链接。加微信说一句你要做什么,我直接把当前最新的包发给你——省得拿到过期版本,ABI 有变动也好通知到你。
这三条决定我发哪个包,一次说清能省一个来回:
| 包内文件 | 用途 |
|---|---|
| xsnip.dll | 运行时。跟宿主 exe 放同一目录,或放进系统 PATH;皮肤、图标全部内嵌,不需要附带别的资源。 |
| xsnip_c.h | 唯一对三方承诺稳定的头文件。接入时只需要它,别 include 工程内部的 xsnip.h。 |
| xsnip.lib | MSVC 导入库。MinGW / 非 MSVC 编译器直接 LoadLibrary + GetProcAddress,或按 xsnip.def 自己生成 .a。 |
| xsnip.def | 导出表,7 个函数、无修饰名。C# / Delphi 写声明时对着它核对名字与调用约定。 |
建会话 → 发起截图 → 销毁。项目属性里加一句 xsnip.lib;user32.lib,把 xsnip.dll 和 xsnip_c.h 放好就能编。
// 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; }
notify_wnd:消息到了再从 UI 线程调 XSnipGetLastResult 取结果。回调里的 info 只在本次回调期间有效,要留自己拷。全部 __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 之前必须先调它,否则线程还在跑,进程会崩。 |
所有入参结构体第一个字段都是 size = sizeof(...)。以后加字段只往后追加,DLL 只读 size 覆盖到的那部分,老宿主不用重编。
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 无损压缩,适合直接当附件发走。 |
复用一套码:函数返回值和 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。属于正常路径,别当错误弹框。 |
导出名不带修饰,所以声明里不用 EntryPoint;注意 CallingConvention.Cdecl 和 LPWStr。
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); }
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); }
接入时踩坑最多的不是函数怎么调,是"谁来等结果、dll 什么时候能卸载"。
| 场景 | 约定 |
|---|---|
| 收到结果 | 两种:给 notify_wnd 走窗口消息(UI 线程,推荐);给回调走截图线程(必须自己切线程)。两个都给时两个都会通知。 |
| 能不能并发截两张 | 不能。同一时刻只允许一次,第二次 XSnipCapture 返回 XSNIP_E_BUSY。 |
| 能不能开多个会话 | 不能,进程内单实例。多窗口宿主共用一个句柄。 |
| 什么时候能 FreeLibrary | 必须先 XSnipDestroy。它会 join 掉 UI 线程;不调就卸载,线程还在跑,进程崩。 |
| dll 和绿色版冲突吗 | 不冲突。单实例是进程内的,跟用户自己装/解压的 xsnip.exe 互不干扰。 |
| 配置从哪来 | XSnipConfig.config_dir 下的 xsnip.ini(水印、默认存储目录等)。不传就看 dll 同目录。 |
XSnipGetAbiVersion 比一下,比什么都稳。不需要。dll 自带界面、皮肤和图像处理,拷一个文件过去就能用,绿色无依赖。
当前 ABI 只有「剪贴板」和「文件」两种输出,没有内存流接口。要字节流可以先存临时文件再读,或者走剪贴板。改成回调返回内存指针属于不兼容变更,要等 ABI 2。
x64 约 2.7 MB、x86 约 2.4 MB,皮肤和图标都内嵌。只在 XSnipCreate 时拉起 UI 线程,不占常驻内存大户。
不能。界面是 xsnip 自己的皮肤,只开放结果和少量行为(延迟、输出、水印、文件名前缀)。把界面换掉等于重写产品,不在 SDK 范围内。
回调 / 消息照常到达,code = XSNIP_E_CANCELLED、output = XSNIP_OUTPUT_NONE。这是正常路径,别弹错误框。
SDK 随 xsnip 一起免费分发,闭源商用也可以。唯一的要求是别把 dll 改名后当成自己的产品卖。
微信扫一扫,备注 xsnip SDK