简介面向C语言开发者的SIP注册与eXosip2应用学习包围绕SIP用户代理向服务器注册的完整流程重点讲解eXosip2-3.6.0中REGISTER请求的构造、发送及MD5摘要身份验证帮助读者快速搭建可运行的VoIP客户端与服务端原型。包内共8个文件包含2个C源文件服务端与客户端主代码、2个DSP与2个DSW工程文件Visual C工程配置、以及2个7z压缩包eXosip2-3.6.0库和MD5相关代码压缩包整体仅222KB轻量易用。已有1567人学习下载是了解SIP注册机制和eXosip2二次开发的不错参考。通过学习可掌握SIP注册流程中的六个关键步骤理解REGISTER消息头字段、Expires有效期、401/200响应处理并能参照示例实现带MD5加密验证的SIP注册逻辑适用于VoIP通信、软电话等场景。1. SIP 注册流程是绝大多数 SIP 项目的起跑线先把 eXosip 的 register 跑通SIP 注册流程几乎是所有 SIP 对接项目的第一道坎海康平台对接、VoIP 终端入网、软交换测试服务器端等到的第一条消息永远是 REGISTER。我自己用 osip/exosip 这套开源栈把“注册到服务器”这件事拆开做过很多遍它的 register 流程本身不难但坑全藏在细节里401 重发、CSeq 递增、Contact 里填哪个 IP、刷新周期算不准就会被服务器踢下线。这篇按我实际跑通的路径把 eXosip 从初始化到注册成功、再到刷新保活的完整流程和排错方法写透。适合做 VoIP 话机、GB28181 网关、SIP 中继或者任何需要主动注册到 SIP 服务器的设备端开发的兄弟也适合注册问题卡壳时想快速定位的人。2. SIP 注册协议与 osip/exosip 的分工REGISTER 事务、401 质询与 200 OK2.1 一条 REGISTER 报文里藏着哪些字段从 Request-Line 到 Contact先把最核心的报文摆出来。下面这条是 eXosip 在没有鉴权时发出的第一轮 REGISTER我抓包后格式化过去掉了一些无关扩展头REGISTER sip:192.168.1.100:5060 SIP/2.0 Via: SIP/2.0/UDP 192.168.1.50:5060;rport;branchz9hG4bK-8f4a2c9e Max-Forwards: 70 From: sip:1001192.168.1.100;tagabc123 To: sip:1001192.168.1.100 Call-ID: 20250117120000192.168.1.50 CSeq: 1 REGISTER Contact: sip:1001192.168.1.50:5060;expires3600 Expires: 3600 Content-Length: 0这条报文定义了注册的本质告诉服务器“我是谁、我在哪、我有效期多久”。Request-Line 里的sip:192.168.1.100:5060是服务器地址对应 eXosip 里的 reg_proxyTo 和 From 头里的sip:1001192.168.1.100是 AORAddress of Record对应 reg_userContact 头里的sip:1001192.168.1.50:5060是这台设备实际可达的地址对应 reg_contact。Expires 是本次注册的有效期服务器会按这个秒数启动一个定时器到期没有刷新就自动清掉绑定。这里要特别提示一点Contact 里填的 IP必须是“服务器回包能到达的地址”。很多人在局域网里随手填了127.0.0.1或把公网 IP 写进局域网设备注册请求能发出去但服务器按 Contact 回心跳时找不着设备表现为“注册 200 了但平台一直显示离线”。eXosip 在未指定 reg_contact 时会自动用本地网卡地址生成这个默认行为在单网卡上没问题多网卡或 NAT 下必须手动指定。把 eXosip 字段和 SIP 头域的对应关系列一下后面配置账号时可以对照填避免对着头去猜参数eXosip 字段对应 SIP 位置典型值作用reg_proxyRequest-Line 请求目标sip:192.168.1.100:5060注册服务器地址reg_userTo/From 的 user 部分1001账号标识reg_displaynameFrom 的显示名1001可选可留空reg_contactContact 头sip:1001本机IP:端口实际可达地址reg_expiresExpires 头3600注册有效期单位秒2.2 osip 与 eXosip 的分层为什么不能绕过 eXosip 直接写 osiposip2 是纯粹的 SIP 协议栈负责 SIP 消息的解析、序列化、事务状态机和定时器eXosip 是跑在 osip2 之上的 UA 层封装把账号、注册、呼叫、事件这些业务概念变成一句句 API 调用。理解这层关系你才知道遇到问题时去哪找原因。我的经验是直接裸用 osip2 写注册你要自己维护 transaction 匹配、重发定时器、鉴权摘要、Call-ID 生命周期这些是协议栈最繁琐的部分做一遍至少多花一星期。eXosip 把这些封装成 event你把账号信息丢给它它内部按 RFC 3261 的状态机走完 REGISTER 的整个生命周期然后通过eXosip_event_wait把结果通知给你。这也是选型时的理由eXosip 的事件机制特别适合做设备端你的业务循环只需要等事件、分发事件不需要碰 SIP 消息细节。很多开源 VoIP 终端早期都基于它社区范例多遇到问题搜一圈就有一堆结果。代价是版本间 API 有变动网上老教程不少用的是多年前的eXosip_register老写法看的时候要留个心眼。2.3 一次注册其实是两轮交互401 质询、Digest 鉴权与 CSeq 递增多数需要鉴权的服务器一次成功注册是两轮 REGISTER 交互。第一轮不带 Authorization 头或带空凭证服务器回 401 Unauthorized同时在响应里给出WWW-Authenticate: Digest realm..., nonce...eXosip 收到 401 后用 realm、nonce、密码和用户名算出摘要在同一个 Call-ID 下重新发 REGISTER这次带上 Authorization 头服务器校验通过后回 200 OK。这两轮请求有个硬性要求Call-ID 必须保持一致CSeq 必须递增。第一轮是CSeq: 1 REGISTER第二轮必须是CSeq: 2 REGISTER。如果你自己组装报文这两点最容易翻车eXosip 在内部账号机制下会自动维护递增但如果你混用了老 API 手动发 REGISTER就要自己保证。鉴权摘要的计算是一个黑匣子eXosip 内部用 osip_md5 完成一般不需要你管。但有个工程常识要知道摘要计算依赖一个“服务器认可的非ce”而且不少商用服务器包括部分安防平台的 SIP 服务会校验客户端时间戳。本地时钟偏了哪怕密码完全正确也会表现为 401 循环或 403——这类问题排查时可以顺手对一下系统时间和 NTP 时间服务器。3. 编译与初始化把 eXosip 栈跑起来的三个前提3.1 源码准备与版本搭配eXosip 依赖 osip2所以要先编译安装 osip2再编译安装 eXosip。两者是独立源码包通常都从官方仓库或镜像直接拉取。版本上我建议都用 5.x 系列配套关系比较稳定网上多数新教程也基于这套接口。编译流程比较固定先在源码根目录生成 configure 再编译安装# libosip2 ./autogen.sh ./configure --prefix/usr/local make -j4 sudo make install # libeXosip2按同样顺序 ./autogen.sh ./configure --prefix/usr/local make -j4 sudo make install编译安装完成后用 pkg-config 验证两个库是否都被正确识别pkg-config --modversion libosip2 libeXosip2逻辑说明--prefix指定安装路径默认是 /usr/local后续头文件在 /usr/local/include库在 /usr/local/lib。如果系统本来就是 64 位且库路径没在 ldconfig 里编译时会遇到找不到 -leXosip2 的情况需要把 /usr/local/lib 加进 /etc/ld.so.conf 并执行 ldconfig。make -j4的 4 是并行编译核数按你机器 CPU 调整内存小的机器建议 -j2 避免编译 OOM。3.2 初始化与监听传参决定 UDP、端口与可复用初始化是注册流程的地基。eXosip 的句柄模型是先eXosip_malloc拿到一个上下文指针后续所有操作都围绕这个 ctx 展开。下面是基础初始化代码#include eXosip2/eXosip.h struct eXosip_t *ctx NULL; ctx eXosip_malloc(); if (ctx NULL) { fprintf(stderr, eXosip_malloc failed\n); return -1; } if (eXosip_init(ctx) ! OSIP_SUCCESS) { fprintf(stderr, eXosip_init failed\n); return -2; } if (eXosip_listen_addr(ctx, IPPROTO_UDP, 0.0.0.0, 5060, AF_INET, 0) ! OSIP_SUCCESS) { fprintf(stderr, eXosip_listen_addr failed\n); return -3; }逻辑说明eXosip_listen_addr的第二个参数是传输协议IPPROTO_UDP对应标准 5060 端口 UDP 监听大多数注册服务器和安防平台默认走 UDP想监听 TCP 换IPPROTO_TCP。第四个参数端口默认 5060如果端口被占可以临时用 5070 测试。第六个参数是 socket 选项常规场景填 0 即可如果一台机器上要频繁重启服务进程可以在此传 1 打开地址复用避免 TIME_WAIT 导致 bind 失败。注意这里监听的 IP 是0.0.0.0表示绑定所有网卡而不是只绑某个内网 IP。只绑单 IP 在双网卡比如有线 4G 网卡设备上容易出问题注册报文发出去了但回包走了另一块网卡本地收不到。像我这种经常拿笔记本到处跑的一律 0.0.0.0然后在 reg_contact 里手动指定要通告给服务器的地址。3.3 最小工程骨架一个循环跑起来初始化和事件循环是配套的。即使只是测试注册也要先把事件循环跑起来因为 401 响应、200 OK 都是事件eXosip 靠eXosip_event_wait把这些从内部队列取出来。最小骨架如下int main(void) { struct eXosip_t *ctx eXosip_malloc(); if (!ctx) return -1; if (eXosip_init(ctx) ! OSIP_SUCCESS) return -2; if (eXosip_listen_addr(ctx, IPPROTO_UDP, 0.0.0.0, 5060, AF_INET, 0) ! OSIP_SUCCESS) return -3; for (;;) { eXosip_event_t *ev eXosip_event_wait(ctx, 0, 100); if (ev) { printf(event type%d\n, ev-type); eXosip_event_free(ev); } } return 0; }逻辑说明eXosip_event_wait(ctx, 0, 100)的 0 是超时秒数100 是超时毫秒数表示最多等 100 毫秒没事件就返回 NULL这样主循环可以顺便处理自己的定时任务。事件拿到后必须调用eXosip_event_free(ev)释放否则内存持续增长跑一个晚上就吃满内存。这个循环是后续所有注册、保活、呼叫处理的主战场后面几章的代码都挂在这个循环上。4. 注册实现与回调处理从账号配置到注册刷新4.1 eXosip_account_t 与 eXosip_add_account把 AOR、代理、密码一次喂给栈初始化成功后注册的中心动作是配置账号并添加。eXosip 5.x 里账号信息集中在struct eXosip_account_t清空后填关键字段再调用eXosip_add_accountstruct eXosip_account_t acct; int account_id -1; memset(acct, 0, sizeof(acct)); acct.reg_proxy sip:192.168.1.100:5060; // 注册服务器 acct.reg_user 1001; // 账号名 acct.reg_password 123456; // 密码 acct.reg_displayname 1001; // 显示名 acct.reg_contact sip:1001192.168.1.50:5060; // 本机可达地址 acct.reg_expires 3600; // 注册有效期 account_id eXosip_add_account(ctx, acct); if (account_id 0) { fprintf(stderr, eXosip_add_account failed\n); return -1; }逻辑说明reg_proxy决定 REGISTER 发给谁reg_user决定 To/From 里的身份。这两个字段组合起来有个常见误用reg_proxy 写sip:server.example.comreg_user 却写sip:1001192.168.1.100导致 From 头里的 domain 和服务器配置的 AOR 域名对不上服务器校验直接不通过。正确做法是 reg_user 不写域名只写账号部分域名从 reg_proxy 继承或由 reg_contact 补全。reg_contact是坑最多的字段。它不通告的话eXosip 默认用监听网卡的 IP 拼一个 Contact这在家里宽带和办公室网络里通常没问题但一旦设备在 NAT 后面或者有多块网卡默认生成的 Contact 就可能是错的。我在现场处理过一台设备有线网卡 192.168.1.504G 网卡 10.x.x.xeXosip 取了 10.x 网段生成 Contact服务器按这个地址回心跳全部石沉大海表现在监控平台上一会儿在线一会儿离线的边缘把责任工程师折磨了三天。从那次以后我接项目头一天就把 reg_contact 写死成业务侧能通的那个地址。4.2 事件循环里处理注册结果不再让注册黑匣子化账号添加之后eXosip 会自动发起第一轮 REGISTER注册结果会以事件形式出现在事件循环里。5.x 版本里注册结果对应EXOSIP_REGISTRATION_SUCCESS和EXOSIP_REGISTRATION_FAILURE两个事件类型处理代码如下for (;;) { eXosip_event_t *ev eXosip_event_wait(ctx, 0, 200); if (ev NULL) continue; switch (ev-type) { case EXOSIP_REGISTRATION_SUCCESS: printf(注册成功 account%d\n, ev-rid); break; case EXOSIP_REGISTRATION_FAILURE: if (ev-response) { printf(注册失败 code%d reason%s\n, ev-response-status_code, ev-response-reason_phrase); } break; default: break; } eXosip_event_free(ev); }逻辑说明ev-rid是注册标识多账号场景下用它区分是哪个账号注册成功了后面刷新时也要带着它调 API。ev-response在注册失败事件里指向 SIP 响应取状态码和原因短语即可但要注意不是所有事件都有 response 字段访问前先判空。事件用完必须eXosip_event_free这个习惯要刻进肌肉记忆。我见过有的工程把注册结果打印到日志就不管了这是个隐患。注册失败后要立刻进重试逻辑而不是干等下一次人为触发。后面第 5 章会展开典型的失败原因但先把事件落位后面排查才有抓手。4.3 注册刷新与注销把 expires 的边界算清楚注册成功只代表拿到了一个有效期为 reg_expires 秒的绑定。到期前必须重新发 REGISTER 刷新否则服务器到期清 binding设备就“掉线”了。刷新时机不要卡在 expires 的 99%网络抖动一次就翻车我一般取 expires 的 50%60% 提前量。用 osip 提供的时间接口拿绝对时间维护一个下次刷新时间点#include osip2/osip_time.h osip_timeval_t tv; long now_ms, next_refresh_ms; int account_id; /* 来自 eXosip_add_account 的返回值假设已有值 */ /* 注册成功后初始化60% 时间点刷新 */ osip_gettimeofday(tv, NULL); now_ms tv.tv_sec * 1000 tv.tv_usec / 1000; next_refresh_ms now_ms (long)(3600 * 600); /* 3600s * 0.6 */ /* 在事件循环的每次空转或定时检查里做以下判断 */ osip_gettimeofday(tv, NULL); now_ms tv.tv_sec * 1000 tv.tv_usec / 1000; if (now_ms next_refresh_ms) { eXosip_register_account(ctx, account_id, 3600); next_refresh_ms now_ms (long)(3600 * 600); }逻辑说明刷新时重新调用eXosip_register_account(ctx, account_id, expires)expires 传你要的新有效期通常和初次注册一致。这里不能用相对时间累加必须每次重新取绝对时间否则事件循环偶发卡顿会让刷新时间点漂移。osip_gettimeofday是 osip2 提供的跨平台时间接口返回 struct timeval 一样的结构秒和微秒分开存放。注销是刷新语义的延伸把 expires 传 0服务器就会立刻清掉 bindingeXosip_register_account(ctx, account_id, 0);实际产品里不建议用注销因为设备断电往往来不及发注销就没了服务器那边等 expires 自然超时就行。注销更多用在调试和主动切服务器的场景。5. 常见注册失败排查五个我看过的翻车现场5.1 401 无限循环密码、realm 和本地时钟的三个并发嫌疑现象抓包看到 REGISTER 一轮接一轮往外发服务器每次回 401客户端日志里全是 Unauthorized协议栈内部在自动重发停不下来。原因多数是三个之一。第一密码错误或密码字符串里带了意外字符——例如从配置文件读的密码带着引号或换行符肉眼看着没差别摘要算出来全错。第二realm 不匹配——服务器在 WWW-Authenticate 里下发的 realm 和客户端配置的账号域名不一致摘要计算基于 realm错一个字符都不行。第三部分服务器校验客户端时间戳本地时间偏了nonce 校验不过表现为密码重置后仍然 401 循环。解决先看抓包里第二轮 REGISTER 的 Authorization 头的 realm和服务器第一轮下发的 WWW-Authenticate 的 realm 比对不一致就调整 reg_proxy 或 reg_user 的域名部分。密码临时写死明文排除配置读取引入的隐形字符。时间不对就先对时把设备加入 NTP 时间服务器同步再测注册。5.2 注册 200 OK 后几十秒被踢下线刷新定时器没装现象注册成功200 OK 都打印出来了但过几十秒或正好在注册后第 60 秒、第 180 秒服务器端把设备标记为离线甚至主动发来一条消息让客户端重注册。原因这是最普遍的一个——代码只做了初次注册没有注册刷新逻辑。eXosip 内部不会自动替你做周期刷新你得自己维护那个 next_refresh 定时器。很多平台侧配置的注册有效期是 3600 秒但也有不少设备默认 60 秒或 120 秒如果你 reg_expires 配的是 3600 而平台只认 60服务器到期清绑定设备就掉线。解决把 reg_expires 和平台的注册周期配置对齐然后按 4.3 节那样加绝对时间刷新。还有一个血泪经验调这种问题不要靠肉眼看日志等 3600 秒测试阶段把 expires 临时改成 60然后设个 35 秒的刷新点一分钟后看服务器侧状态就知道了。5.3 海康/安防平台回 403 Forbidden来源和 Contact 不一致现象REGISTER 鉴权都过了服务器不回 200 而是直接 403 Forbidden。很多做 GB28181 网关对接海康平台的兄弟都卡过这一步。原因这种平台侧的 SIP 服务多数校验 Contact 头里的 IP 和报文来源 IP 的一致性。设备在 NAT 后面发出的 REGISTER 源 IP 是内网地址Contact 里也写了内网地址但请求经过路由后平台看到来源是网关的公网 IP两边对不上就 403。还有个常见原因平台侧配置设备编码时带了空格或大小写问题和 REGISTER 里 From 的 user 部分不一致鉴权逻辑直接拒绝。解决在 reg_contact 里显式填平台能回通的地址。局域网内对接就让 Contact 和物理网卡地址一致跨网段对接要知道平台侧看到的来源 IP必要时和平台调试人员确认而不是自己猜。对照平台侧的设备编码确保和 reg_user 完全一致一个字符都不能差。5.4 第二个 UA 进程起不来端口被占用现象同一台机器上跑第二个测试程序或者服务进程重启时时报 bind 失败错误是 Address already in use然后整个进程退出。原因5060 端口被第一个进程占用。eXosip 默认监听 5060 且未开 SO_REUSEADDR第二个进程拿不到端口。另外重启时旧进程没完全退出进入了 TIME_WAIT也会这样。解决测试工程固定用 5070 或 5090 之类的端口避开和正式服务冲突生产环境确认旧进程完全退出再拉起新进程。每次重启时顺手lsof -i :5060看一眼端口占用比看半天日志快得多。5.5 公网注册发出去却等不到回包Contact 和防火墙双重背锅现象本地抓包能看到 REGISTER 发出服务器也确实回了 401 或 200但客户端就是收不到事件循环里没有事件。用内网服务器测就正常。原因两种典型。第一种Contact 通告的地址在公网不可达服务器回包的时候找不到对应会话消息被路由吞了。第二种运营商或云服务器安全组把 UDP 的入方向过滤了常见于云主机默认只放行 TCP。解决Contact 必须是公网可达的地址这一步不是玄学是路由事实。云主机要把 UDP 端口的入方向安全组规则放行本地自建服务器要确认路由器把对应端口映射到了设备。整体上公网注册比局域网严苛排查链路是抓包确认客户端发出 → 抓服务器侧确认收到并回 → 再确认回包能回来缺哪一段补哪一段。6. 注册保活与多账号的进阶技巧把注册做成定时任务6.1 保活手段不要混REGISTER 刷新和 OPTIONS 心跳各干各的注册刷新解决的是 binding 过期问题OPTIONS 心跳解决的是中间网络路径 (NAT 映射和防火墙会话) 老化问题。很多设备商把两者混成一个只做 OPTIONS 心跳不做 REGISTER 刷新结果服务器的 binding 到了还是掉线。我的习惯是注册周期内必须做 REGISTER 刷新NAT 环境再叠加 OPTIONS 心跳间隔取注册周期的三分之一各干各的互不替代。6.2 多账号注册用一个 ctx靠 rid 分流一台设备注册到多个 SIP 服务器、或多个平台比如同时对接两个安防平台不需要创建多个 eXosip 实例那会引发端口冲突和线程爆炸。一个 ctx 上多次eXosip_add_account返回不同的 account_id事件分发时按 rid 或账号索引分流即可。6.3 失败重试必须退避别在一个失败账号上死磕注册失败后不能 1 秒一次狂发会把服务器打到限流。我一般做五档退避5 秒、15 秒、30 秒、60 秒、300 秒成功后归位。这个逻辑放在事件循环里用EXOSIP_REGISTRATION_FAILURE分支驱动成功后重置计数器重新计算下一轮刷新点。做某个网关项目时半夜设备集体掉线日志里全是注册超时查到最后是刷新时间用了相对累加一次线程调度卡顿让整批设备错过了刷新窗口。从那以后我每次做注册流程都强制走一遍抓包看 REGISTER 两轮交互、确认 401 和 200 闭环、把 expires 改成 60 秒压测到刷新边界、再回到正式周期。这套习惯救了我很多次希望帮到你。本文还有配套的精品资源点击获取