'\" t
.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LIBIRCCLIENT" "1" "Jul 12, 2024" "1.9" "Libircclient"
.SH "نام (NAME)"
libircclient \- کتابخانه کارخواه IRC برای زبان C
.SH "مقدمه (INTRODUCTION)"
.SS "معرفی (Introduction)"
.SS "نمای کلی (Overview)"
.sp
کتابخانه Libircclient یک کتابخانه کوچک اما بسیار قدرتمند است که پروتکل کارخواه (کلاینت) IRC را پیاده‌سازی می‌کند. این کتابخانه به گونه‌ای طراحی شده است که سبک، سریع، قابل‌حمل و سازگار با استانداردهای RFC و همچنین ویژگی‌های غیر استاندارد اما پرکاربرد باشد. این کتابخانه انتخابی عالی برای ساخت کلاینت‌ها و ربات‌های IRC است.
.SS "ویژگی‌ها (Features)"
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
رابط برنامه‌نویسی جامع به زبان C؛
.IP \(bu 2
پوشش کامل پروتکل IRC با استفاده از توابع ارائه‌شده؛
.IP \(bu 2
پشتیبانی از چندین اتصال همزمان به سرورهای مختلف IRC یا حتی به همان سرور؛
.IP \(bu 2
پشتیبانی از هر دو اتصال عادی و امن SSL به سرورهای IRC همراه با بررسی اختیاری گواهینامه؛
.IP \(bu 2
پشتیبانی کامل از چندنخی (Multi-threading)، کتابخانه امن برای نخ‌ها (thread-safe) است؛
.IP \(bu 2
امکان پردازش تمام اتصالات توسط یک نخ منفرد حتی در صورت استفاده از چندین اتصال؛
.IP \(bu 2
رابط ناهمگام و غیرمسدودکننده مبتنی بر رویداد پیاده‌سازی‌شده با فراخوانی‌های بازگشتی (callbacks)؛
.IP \(bu 2
پشتیبانی ویژه از برنامه‌های مبتنی بر سوکت که از select() استفاده می‌کنند؛
.IP \(bu 2
پشتیبانی از CTCP همراه با کد پاسخ داخلی اختیاری؛
.IP \(bu 2
پشتیبانی از CTCP PING که برای گذر از «بررسی جعل هویت» (spoof check) پیاده‌شده در اکثر سرورهای IRC ضروری است؛
.IP \(bu 2
پشتیبانی انعطاف‌پذیر از DCC، شامل هر دو گفتگوی DCC و انتقال فایل DCC؛
.IP \(bu 2
توانایی شروع و همچنین واکنش به نشست‌های DCC شروع‌شده؛
.IP \(bu 2
امکان پذیرش یا رد ناهمگام نشست‌های DCC؛
.IP \(bu 2
نوشته‌شده به زبان خالص C با حجم بسیار کم باینری (حدود ۳۰ کیلوبایت بسته به پلتفرم)؛
.IP \(bu 2
سازگار با تمام کلاینت‌های آزمایش‌شده IRC؛
.IP \(bu 2
نرم‌افزار آزاد تحت مجوز LGPLv3؛
.IP \(bu 2
پشتیبانی از لینوکس و همچنین هر یونیکس سازگار با POSIX، سیستم‌عامل Mac OS X و مایکروسافت ویندوز؛
.IP \(bu 2
پشتیبانی از معماری‌های ۳۲ و ۶۴ بیتی و همچنین معماری‌های غیر x86؛
.IP \(bu 2
پشتیبانی از IPv6 (اختیاری، باید در زمان کامپایل فعال شود)؛
.IP \(bu 2
پشتیبانی از OpenSSL (اختیاری، باید در زمان کامپایل فعال شود)؛
.IP \(bu 2
رابط Cocoa توسط Nathan Ollerenshaw؛
.IP \(bu 2
مستندات جامع، مثال‌ها و پرسش‌های متداول (FAQ)؛
.UNINDENT
.UNINDENT
.UNINDENT
.SS "مشکلات شناخته‌شده (Known issues)"
.sp
هرچند با استفاده از چندین نشست امکان‌پذیر است، اما این کتابخانه برای اتصال همزمان به تعداد بسیار زیادی از سرورهای IRC مناسب نیست. اگر همچنان می‌خواهید از آن بدین منظور استفاده کنید، باید بر موارد زیر فائق آیید:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
نمی‌توانید از حلقه اصلی در \X'tty: link #c.irc_run'\fI\%irc_run()\fP\X'tty: link' استفاده کنید زیرا فقط از یک نشست پشتیبانی می‌کند. باید از \X'tty: link #c.irc_add_select_descriptors'\fI\%irc_add_select_descriptors()\fP\X'tty: link' استفاده نمایید
.IP \(bu 2
باید اتصال‌های مجدد را با پردازش مقادیر بازگشتی مرتبط از \X'tty: link #c.irc_process_select_descriptors'\fI\%irc_process_select_descriptors()\fP\X'tty: link' به طور جداگانه مدیریت کنید
.IP \(bu 2
اگر مایل به استفاده از poll/epoll() به جای select() هستید، باید منطق بیشتری بنویسید زیرا این مورد مستقیماً پشتیبانی نمی‌شود. به \X'tty: link #faq-epoll'\fI\%FAQ\fP\X'tty: link'\& مراجعه کنید.
.IP \(bu 2
کتابخانه برای داشتن ردپای حافظه پایین به ازای هر اتصال بهینه‌سازی نشده است؛ هر اتصال غیر SSL حداقل ۴ کیلوبایت و هر اتصال SSL حدود ۳۲ کیلوبایت حافظه مصرف می‌کند.
.UNINDENT
.UNINDENT
.UNINDENT
.SS "نویسنده (Author)"
.sp
این کتابخانه توسط George Yunaev ساخته شده است، حق نشر ۲۰۰۴-۲۰۱۶. لطفاً ببینید: \X'tty: link http://www.ulduzsoft.com/linux/libircclient'\fI\%http://www.ulduzsoft.com/linux/libircclient\fP\X'tty: link'
.SS "مجوز (License)"
.sp
کتابخانه Libircclient تحت مجوز Lesser General Public License نسخه ۳ یا بالاتر منتشر شده است. متن کامل مجوز در بخش پیوست ارائه شده است.
.SH "یکپارچه‌سازی (INTEGRATION)"
.SS "یکپارچه‌سازی (Integration)"
.SS "نیازمندی‌ها (Requirements)"
.SS "سیستم‌عامل‌ها و کامپایلرهای پشتیبانی‌شده (Supported operating systems and compilers)"
.sp
این کتابخانه به طور گسترده روی پلتفرم‌های لینوکس x86 و x86_64 آزمایش شده است. همچنین روی پلتفرم‌های سولاریس x86، لینوکس روی معماری‌های ARM و MIPS، مک او اس (Mac OS X) روی x86 و نسخه‌های مختلف مایکروسافت ویندوز آزمایش شده است.
.SS "کامپایل (Compilation)"
.sp
در لینوکس، FreeBSD و Mac OS X این کتابخانه پیش از استفاده باید کامپایل و نصب شود، مگر اینکه از بسته پیش‌کامپایل‌شده توزیع سیستم‌عامل خود استفاده کنید. در صورت ارائه بسته توزیع، استفاده از آن توصیه می‌شود زیرا هنگام رفع اشکالات از مخزن مرکزی به‌روزرسانی خواهد شد.
.sp
در مایکروسافت ویندوز فایل‌های باینری رسمی کتابخانه ارائه می‌شوند، بنابراین نیازی به بیلد آن ندارید. مگر اینکه تجربه بیلد با Cygwin را داشته باشید، توصیه می‌شود از سورس بیلد نکنید و از باینری رسمی استفاده کنید.
.SS "کتابخانه‌های مورد نیاز (Required libraries)"
.sp
این کتابخانه فقط به libc (بسته glibc\-devel در لینوکس) و gcc وابسته است، هرچند برنامه‌های نمونه به libstdc++ (بسته libstdc++\-devel) و g++ نیز نیاز دارند. حداقل نسخه پشتیبانی‌شده glibc نسخه ۲.۲ است، اگرچه در صورت درخواست IPv6 حداقل نسخه ۲.۴ از glibc الزامی است.
.sp
اگر کتابخانه با پشتیبانی از SSL بیلد شود، بسته توسعه openssl (بسته openssl\-devel) باید نصب باشد.
.sp
در مایکروسافت ویندوز باید محیط Cygwin به همراه بسته‌های توسعه لازم (و همچنین openssl\-devel) نصب شده باشد.
.SS "کامپایل کردن (Compiling)"
.sp
کتابخانه به روش استاندارد یونیکس پیکربندی و بیلد می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
\&./configure [\-\-enable\-openssl] [\-\-enable\-ipv6]
make
.EE
.UNINDENT
.UNINDENT
.SS "نصب (Installing)"
.sp
اگرچه برای استفاده از کتابخانه‌ها نیازی به نصب نیست، اما هدف نصب برای راحتی ارائه شده و با اجرای دستور \fBsudo make install\fP قابل فراخوانی است.
.SS "پیوند دادن (Linking)"
.sp
برنامه خود را بسته به نیاز به libircclient.a یا libircclient.so پیوند دهید. اگر از کتابخانه ارائه‌شده توسط سیستم استفاده می‌کنید، لطفاً با libircclient.so پیوند دهید.
.sp
اگر کتابخانه را با پشتیبانی از SSL بیلد کرده‌اید، لازم است با کتابخانه‌های OpenSSL پیوند برقرار کنید؛ فلگ‌های \fB\-lcrypto \-lssl\fP را به LDFLAGS خود بیفزایید.
.sp
در مایکروسافت ویندوز لطفاً با libircclient.lib پیوند دهید که به طور ضمنی با libircclient.dll پیوند می‌خورد.
.SS "کدنویسی (Coding)"
.SS "مقداردهی اولیه (Initialization)"
.SS "درج فایل‌های سرآیند (Include the headers)"
.sp
پیش از استفاده از کتابخانه باید سرآیند کتابخانه \fIlibircclient.h\fP را درج کنید. همچنین ممکن است بخواهید \fIlibirc_rfcnumeric.h\fP را که کدهای RFC را فراهم می‌کند، اضافه نمایید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include \(dqlibircclient.h\(dq
#include \(dqlibirc_rfcnumeric.h\(dq
.EE
.UNINDENT
.UNINDENT
.SS "ایجاد گرداننده‌های رویداد (Create event handlers)"
.sp
برخلاف بیشتر پروتکل‌های شبکه مانند HTTP یا SMTP، پروتکل IRC مبتنی بر رویداد است. رویدادها به صورت ناهمگام از سرور می‌آیند. برخی رویدادها با عمل شما ایجاد می‌شوند (مانند پیوستن به کانال یا تغییر نام مستعار)، برخی توسط سایر کاربران IRC ایجاد می‌شوند (مانند ارسال پیام برای شما)، و برخی توسط خود سرور IRC تولید می‌شوند (مانند ارسال یادداشت‌های عملیاتی یا فراخوانی سرویس‌های NickServ).
.sp
کتابخانه Libircclient با ارائه \fBساختار مدیریت رویداد\fP به مدیریت این رویدادها کمک می‌کند. این ساختار رویدادهایی را اعلام می‌کند که می‌توانید در برنامه خود تعریف کنید، و هنگامی که چنین رویدادی از سرور دریافت شد، فراخوانی بازگشتی (callback) مناسب صدا زده خواهد شد. تعداد رویدادهایی که باید مدیریت کنید به پیچیدگی کلاینت شما و عملکردهایی که پشتیبانی می‌کند بستگی دارد.
.sp
به طور کلی فقط دو رویداد وجود دارند که برای ارائه حداقل عملکرد باید آن‌ها را مدیریت کنید: \fBevent_connect\fP و \fBevent_numeric\fP\&. با این حال توصیه می‌شود یک تابع تخلیه رویداد (dump) ایجاد کنید و از آن برای تمام رویدادهای استفاده‌نشده استفاده کنید تا مطمئن شوید به دلیل انتظار برای یک رویداد اشتباه، رویداد مهمی را از دست نمی‌دهید. تابع \fBdump_event\fP را در فایل examples/irctest.c ببینید.
.SS "مقداردهی اولیه ویژه ویندوز (Windows-specific initialization)"
.sp
اگر در مایکروسافت ویندوز با کتابخانه \fBایستا (static)\fP پیوند می‌دهید، باید قبل از فراخوانی توابع کتابخانه، کتابخانه Winsock2 را مقداردهی اولیه کنید. این کار به صورت زیر انجام می‌شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
WSADATA wsaData;

if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
    // گزارش خطا
.EE
.UNINDENT
.UNINDENT
.sp
با این حال اگر با کتابخانه \fBپویا (dynamic)\fP (یعنی libircclient.dll) پیوند می‌دهید که در بیلد رسمی پیش‌فرض است، نیازی به این کار نیست زیرا DLL در زمان بارگذاری این کار را به صورت خودکار انجام می‌دهد.
.SS "ایجاد یک نشست IRC (Create an IRC session)"
.sp
برای استفاده از کتابخانه باید حداقل یک \fBنشست IRC (IRC session)\fP ایجاد شود. یک نشست می‌تواند برای برقراری یک اتصال واحد به یک سرور IRC برای یک نام مستعار استفاده شود. با این حال در صورت نیاز می‌توان بیش از یک نشست ایجاد کرد.
.sp
برای ایجاد یک نشست، تابع \X'tty: link #c.irc_create_session'\fI\%irc_create_session()\fP\X'tty: link' را فراخوانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// ساختار کال‌بک‌های IRC
irc_callbacks_t callbacks;

// مقداردهی اولیه آن
memset ( &callbacks, 0, sizeof(callbacks) );

// تنظیم رویدادهای اجباری
callbacks.event_connect = event_connect;
callbacks.event_numeric = event_numeric;

// تنظیم سایر رویدادها

// اکنون نشست را ایجاد کنید
irc_session_t * session = irc_create_session( &callbacks );

if ( !session )
    // مدیریت خطا
.EE
.UNINDENT
.UNINDENT
.sp
این کد می‌تواند به تعداد دفعات مورد نیاز برای ایجاد چندین نشست تکرار شود. همان ساختار فراخوانی بازگشتی می‌تواند برای چندین نشست مجدداً استفاده شود.
.SS "تنظیم گزینه‌ها (Set options)"
.sp
علاوه بر اشکال‌زدایی، دو گزینه وجود دارد که ممکن است به آن‌ها نیاز داشته باشید. گزینه \X'tty: link #c.LIBIRC_OPTION_STRIPNICKS'\fI\%LIBIRC_OPTION_STRIPNICKS\fP\X'tty: link' تجزیه خودکار نام‌های مستعار را فعال می‌کند، و از آنجا که به سختی می‌توان موردی را تصور کرد که این گزینه نباید فعال باشد، ما آن را فعال می‌کنیم:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
irc_option_set( session, LIBIRC_OPTION_STRIPNICKS );
.EE
.UNINDENT
.UNINDENT
.sp
گزینه دومی که ممکن است در صورت استفاده از اتصالات SSL و اتصال به سرورهایی با گواهینامه‌های خودامضا (self-signed) نیاز داشته باشید، در مستندات \X'tty: link #c.LIBIRC_OPTION_SSL_NO_VERIFY'\fI\%LIBIRC_OPTION_SSL_NO_VERIFY\fP\X'tty: link' شرح داده شده است.
.SS "اتصال به سرور (Connect to the server)"
.sp
برای شروع اتصال به سرور IRC، تابع \X'tty: link #c.irc_connect'\fI\%irc_connect()\fP\X'tty: link' را فراخوانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// اتصال به یک سرور معمولی IRC
if ( irc_connect (session, \(dqirc.example.com\(dq, 6667, 0, \(dqmynick\(dq, \(dqmyusername\(dq, \(dqmyrealname\(dq ) )
  // مدیریت خطا: ()irc_strerror و ()irc_errno
.EE
.UNINDENT
.UNINDENT
.sp
برای شروع اتصال به سرور IRC از طریق SSL، تابع \X'tty: link #c.irc_connect'\fI\%irc_connect()\fP\X'tty: link' را فراخوانی کنید و پیشوند نام میزبان یا نشانی IP را با یک علامت هش (#) قرار دهید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// اتصال به سرور SSL؛ درج 192.168.1.1# نیز ممکن است
if ( irc_connect (session, \(dq#irc.example.com\(dq, 6669, 0, \(dqmynick\(dq, \(dqmyusername\(dq, \(dqmyrealname\(dq ) )
  // مدیریت خطا: ()irc_strerror و ()irc_errno
.EE
.UNINDENT
.UNINDENT
.sp
این تابع فقط اتصال را آغاز می‌کند، بنابراین هنگامی که با موفقیت بازمی‌گردد، اتصال تنها آغاز شده است اما هنوز برقرار نشده است. سپس پس از فراخوانی گرداننده شبکه یکی از موارد زیر رخ می‌دهد:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
اگر اتصال برقرار شود، رویداد \fBevent_connect\fP را دریافت خواهید کرد - به همین دلیل مدیریت آن اهمیت دارد
.IP \(bu 2
اگر اتصال ناموفق باشد، تابع گرداننده شبکه وضعیت شکست را برمی‌گرداند
.UNINDENT
.UNINDENT
.UNINDENT
.SS "اتصال به سرور IPv6 (Connect to the IPv6 server)"
.sp
برای آغاز اتصال به سرور IPv6، تابع \X'tty: link #c.irc_connect6'\fI\%irc_connect6()\fP\X'tty: link' را فراخوانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if ( irc_connect6 (session, \(dq2001:0db8:85a3:0042:1000:8a2e:0370:7334\(dq, 6669, 0, \(dqmynick\(dq, \(dqmyusername\(dq, \(dqmyrealname\(dq ) )
  // مدیریت خطا: ()irc_strerror و ()irc_errno
.EE
.UNINDENT
.UNINDENT
.sp
بقیه جزئیات، از جمله مقدار بازگشتی و SSL همانند اتصال معمولی است.
.SS "شروع حلقه شبکه (Start the networking loop)"
.sp
برای اینکه به کتابخانه اجازه دهید رویدادها را مدیریت کند، دو سناریو وجود دارد. می‌توانید حلقه شبکه داخلی را فراخوانی کنید که عملیات شبکه را مدیریت کرده و رویدادهای شما را فراخوانی می‌کند، یا می‌توانید حلقه خود را بنویسید.
.sp
فراخوانی حلقه شبکه داخلی ساده‌تر اما محدود است. از آنجا که این حلقه تا زمان پایان اتصال اجرا می‌شود، برای یک برنامه دارای رابط کاربری گرافیکی (GUI) مناسب نیست (مگر اینکه حلقه را در یک نخ جداگانه اجرا کنید که این کار امکان‌پذیر است). و از آنجا که این حلقه فقط می‌تواند یک نشست را مدیریت کند، در صورتی که بخواهید چندین نشست IRC را مدیریت کنید استفاده از آن غیرممکن است. در این موارد باید از حلقه شبکه سفارشی که در زیر توضیح داده شده استفاده شود.
.sp
برای شروع حلقه رویداد، تابع \X'tty: link #c.irc_run'\fI\%irc_run()\fP\X'tty: link' را فراخوانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
if ( irc_run (s) )
  // یا اتصال به سرور برقرار نشد یا قطع شد. به ()irc_errno مراجعه کنید
.EE
.UNINDENT
.UNINDENT
.sp
به یاد داشته باشید که فراخوانی ()irc_run \fBتا زمانی که اتصال سرور دیگر فعال نباشد بازنخواهد گشت\fP\&.
.SS "استفاده از حلقه شبکه سفارشی (Use the custom networking loop)"
.sp
اگر از چندین نشست استفاده می‌کنید یا گرداننده سوکت خودتان را دارید، می‌توانید از حلقه شبکه سفارشی استفاده کنید. در این حالت برنامه شما باید مبتنی بر select() باشد (اگر می‌خواهید از روش‌های دیگر نظرسنجی استفاده کنید، \X'tty: link #faq-epoll'\fI\%پرسش‌های متداول (FAQ)\fP\X'tty: link' را ببینید). و باید حلقه زیر را اجرا کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// مطمئن شوید که تمام نشست‌های IRC متصل هستند
if ( !irc_is_connected(session) )
  // اتصال مجدد آن یا توقف

// ساخت ساختارهای لازم برای ()select
struct timeval tv;
fd_set in_set, out_set;
int maxfd = 0;

// انتظار ۰.۲۵ ثانیه برای رویدادها - در صورت تمایل می‌توانید بیشتر منتظر بمانید،
// اما کتابخانه مهلت‌های زمانی داخلی دارد، بنابراین حتی در صورت عدم وجود رویدادهای شبکه
// باید به صورت دوره‌ای فراخوانی شود
tv.tv_usec = 250000;
tv.tv_sec = 0;

// مقداردهی اولیه مجموعه‌ها
FD_ZERO (&in_set);
FD_ZERO (&out_set);

// توصیف‌کننده‌های خودتان را که باید منتظرشان بمانید اضافه کنید، در صورت وجود
\&...

// افزودن توصیف‌کننده‌های نشست IRC - برای هر نشست فعال تابع ()irc_add_select_descriptors را فراخوانی کنید
irc_add_select_descriptors( session, &in_set, &out_set, &maxfd );

// فراخوانی ()select
if ( select (maxfd + 1, &in_set, &out_set, 0, &tv) < 0 )
   // خطا

// همچنین می‌توانید بررسی کنید که آیا توصیف‌کننده‌ای فعال است یا خیر، اما باز هم کتابخانه
// باید مهلت‌های زمانی داخلی را مدیریت کند، بنابراین باید حداقل هر چند ثانیه یک بار
// تابع ()irc_process_select_descriptors را برای هر نشست فراخوانی کنید
\&...

// فراخوانی ()irc_process_select_descriptors برای هر نشست با مجموعه توصیف‌کننده‌ها
if ( irc_process_select_descriptors (session, &in_set, &out_set) )
    // اتصال با شکست روبرو شد یا سرور ارتباط را قطع کرد. آن را مدیریت کنید.

// تکرار مجدد
.EE
.UNINDENT
.UNINDENT
.SS "کانال‌ها و کاربران (Channels and users)"
.sp
پیش از فراخوانی هر یک از این توابع مطمئن شوید که به سرور متصل شده‌اید.
.SS "ورود به کانال و خروج از آن (Join and leave a channel)"
.sp
برای ورود به کانال، تابع \X'tty: link #c.irc_cmd_join'\fI\%irc_cmd_join()\fP\X'tty: link' را همراه با نام کانال فراخوانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// ورود به کانال #linux
if ( irc_cmd_join( session, \(dq#linux\(dq, 0 ) )
  // احتمالاً خطای اتصال

// ورود به کانال science$ محافظت‌شده با کلید سری *superpassword*
if ( irc_cmd_join( session, \(dq$science\(dq, \(dqsuperpassword\(dq ) )
  // احتمالاً خطای اتصال
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانید به هر تعداد کانال که می‌خواهید ملحق شوید، اگرچه ممکن است سرور تعداد کانال‌هایی را که می‌توانید همزمان در آن‌ها عضو باشید محدود کند.
.sp
اگر پیوستن موفقیت‌آمیز باشد، رویداد \fBevent_join\fP را دریافت خواهید کرد. قبل از اینکه بتوانید هرگونه عملیات کانال (مانند ارسال پیام) را انجام دهید، باید منتظر این رویداد بمانید. با این حال نیازی نیست برای صدور دستور دوم JOIN همان‌طور که در مثال بالا نشان داده شد، منتظر این رویداد بمانید.
.sp
اگر پیوستن موفقیت‌آمیز نبود، خطا را از طریق \fBevent_numeric\fP دریافت خواهید کرد.
.sp
برای خروج از کانال، تابع \X'tty: link #c.irc_cmd_part'\fI\%irc_cmd_part()\fP\X'tty: link' را همراه با نام کانال فراخوانی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// خروج از کانال #linux
if ( irc_cmd_part( session, \(dq#linux\(dq ) )
  // احتمالاً خطای اتصال

// خروج از کانال science$
if ( irc_cmd_part( session, \(dq$science\(dq ) )
  // احتمالاً خطای اتصال
.EE
.UNINDENT
.UNINDENT
.SS "ارسال پیام به یک کانال یا کاربر (Send a message to a channel or to a user)"
.sp
پس از ورود به کانال، می‌توانید با استفاده از تابع \X'tty: link #c.irc_cmd_msg'\fI\%irc_cmd_msg()\fP\X'tty: link' همراه با نام کانال، پیامی به آن بفرستید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// ارسال پیام "!Hi" به همه در کانال #linux
if ( irc_cmd_msg( session, \(dq#linux\(dq, \(dqHi!\(dq ) )
  // احتمالاً خطای اتصال
.EE
.UNINDENT
.UNINDENT
.sp
از نظر فنی، پروتکل کاربر را ملزم نمی‌کند که برای ارسال پیام به یک کانال، حتماً عضو آن باشد. اما اکثر سرورها به طور پیش‌فرض حالت کانالی را تنظیم می‌کنند که مانع از ارسال پیام توسط کاربرانی می‌شود که به کانال نپیوسته‌اند.
.sp
از همین تابع برای ارسال یک پیام «خصوصی» به کاربر دیگر استفاده می‌شود. پیام‌های «خصوصی» از کانال‌ها عبور نمی‌کنند، اما همچنان از سرور IRC (گاهی چندین سرور) عبور می‌کنند و توسط مدیران شبکه IRC قابل مشاهده یا حتی ثبت هستند.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// ارسال پیام "!Hi" به کاربر john در IRC
if ( irc_cmd_msg( session, \(dqjohn\(dq, \(dqHi!\(dq ) )
  // احتمالاً خطای اتصال
.EE
.UNINDENT
.UNINDENT
.sp
اگر پیام با موفقیت ارسال شود، هیچ تأییدیه یا رویدادی دریافت نخواهید کرد. فقط در صورتی که پیام ارسال نشود، خطا را از طریق \fBevent_numeric\fP دریافت خواهید کرد.
.SS "دریافت پیام‌ها از یک کانال یا کاربر (Receive messages from a channel or from a user)"
.sp
شما پیام‌های کانال را با مدیریت رویداد \fBevent_channel\fP دریافت می‌کنید. هر بار که کسی در کانال سخنی می‌گوید این رویداد فراخوانی می‌شود.
.sp
پیام‌های «خصوصی» از دیگر کاربران را با مدیریت رویداد \fBevent_privmsg\fP دریافت می‌کنید.
.sp
این گرداننده‌های رویداد باید در برنامه شما ایجاد شوند و هنگام ایجاد نشست IRC به کتابخانه فرستاده شوند.
.SS "ارسال پیام کنش (Send an action message)"
.sp
پیام‌های «کنش» (Action) که پیام‌های me/ نیز نامیده می‌شوند، پیام‌های CTCP با قالب‌بندی ویژه هستند. با این حال کتابخانه شامل یک تابع ویژه به نام \X'tty: link #c.irc_cmd_me'\fI\%irc_cmd_me()\fP\X'tty: link' برای ارسال آن‌ها است. کنش‌های ارسال‌شده توسط افراد دیگر توسط رویداد \fBevent_ctcp_action\fP مدیریت می‌شوند.
.sp
همانند ارسال پیام، در صورت موفقیت هیچ تاییدیه‌ای دریافت نمی‌شود.
.SS "ارسال درخواست CTCP (Send a CTCP request)"
.sp
سایر درخواست‌های CTCP مانند PING، VERSION و غیره باید با فراخوانی \X'tty: link #c.irc_cmd_ctcp_request'\fI\%irc_cmd_ctcp_request()\fP\X'tty: link' ارسال شوند. در صورت دریافت پاسخ CTCP، رویداد \fBevent_ctcp_rep\fP آن را مدیریت می‌کند.
.SS "مدیریت گفتگوی DCC (Handling DCC chat)"
.SS "پیاده‌سازی فراخوانی بازگشتی DCC (Implementing the DCC callback)"
.sp
صرف‌نظر از اینکه قصد شروع گفتگوهای DCC را دارید یا پاسخ دادن به آن‌ها، باید \fBکال‌بک DCC\fP را پیاده‌سازی کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
void dcc_callback (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
{
   if ( status )
   {
       // اگر وضعیت LIBIRC_ERR_CLOSED باشد، گفتگو توسط طرف مقابل بسته شده است.
       // در غیر این صورت یک خطا است؛ گفتگو پایان یافته یا برقرار نشده است. وضعیت کد خطا است؛ ()irc_strerror را ببینید
   }
   else if ( length == 0 )
   {
       // طرف مقابل درخواست گفتگو را پذیرفته است، پیامی برای آن‌ها بفرستید
       irc_dcc_text( session, id, \(dqHello!\(dq );
   }
   else
   {
       // پیام گفتگو از طرف مقابل دریافت شد
       printf (\(dqRemote party said: %s\en\(dq, data );
   }
}
.EE
.UNINDENT
.UNINDENT
.sp
این کال‌بک باید یا به تابع \X'tty: link #c.irc_dcc_chat'\fI\%irc_dcc_chat()\fP\X'tty: link' که درخواست را آغاز می‌کند، یا به تابع \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' که درخواست DCC CHAT آغاز شده توسط کاربر دیگر را می‌پذیرد، فرستاده شود.
.SS "شروع گفتگوی DCC (Initiating the DCC CHAT)"
.sp
می‌توانید گفتگوی DCC را با کاربر دیگری با فراخوانی \X'tty: link #c.irc_dcc_chat'\fI\%irc_dcc_chat()\fP\X'tty: link' آغاز کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// شناسه نشست گفتگوی DCC در این متغیر بازگردانده می‌شود
irc_dcc_t dccid;

// آغاز گفتگوی DCC با کاربر john در IRC
if ( irc_dcc_chat( session, 0, \(dqjohn\(dq, dcc_callback, &dccid ) )
  // گزارش خطا
.EE
.UNINDENT
.UNINDENT
.sp
اکنون می‌توانید به کارهای دیگر ادامه دهید. هنگامی که جان گفتگو را پذیرفت یا رد کرد، dcc_callback() فراخوانی خواهد شد و امکان استفاده از تابع \fBirc_dcc_text()\fP برای ارسال پیام‌های گفتگو فراهم خواهد بود. این فراخوانی بازگشتی همچنین هر بار که پیام گفتگوی جدیدی دریافت شود، یا زمانی که گفتگو به پایان برسد یا به دلیل خطای شبکه قطع شود، فراخوانی خواهد شد.
.SS "پاسخ به درخواست‌های گفتگوی DCC (Responding to DCC CHAT requests)"
.sp
برای پاسخ دادن به درخواست‌های DCC CHAT، برنامه شما باید رویداد \fBevent_dcc_chat_req\fP را پیاده‌سازی کند. این فراخوانی بازگشتی می‌تواند به صورت زیر پیاده‌سازی شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
void callback_event_dcc_chat( irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid )
{
    // کاربر 'nick' از نشانی IP با مقدار 'addr' تلاش می‌کند گفتگوی DCC را با ما آغاز کند.
    // این اطلاعات را به همراه dccid در صف داخلی برنامه ذخیره کنید تا کال‌بک بتواند بازگردد
    dcc_queue.store( dccid, \(dqCHAT from \(dq + nick + \(dq IP address: \(dq + addr  );
}
.EE
.UNINDENT
.UNINDENT
.sp
و در زمان ایجاد نشست IRC ثبت شود. اگر برنامه شما اصلاً DCC را مدیریت نمی‌کند، می‌توانید تابع \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' را داخل این کال‌بک صدا بزنید.
.sp
اگر مدیریت می‌کند، ما فقط این اطلاعات را در کال‌بک ذخیره کرده و بازمی‌گردیم. زیرا پردازش رویدادها تا زمان بازگشت کال‌بک متوقف خواهد شد، بنابراین نمایش پنجره گفتگو برای درخواست تایید از کاربر، پردازش رویدادهای بعدی مانند پیام‌های کانال را متوقف می‌کند. حتی اگر برنامه شما خودکار است و پنجره‌ای نمایش نمی‌دهد، باز هم بهتر است منطق گفتگو را از منطق فراخوانی بازگشتی جدا کنید.
.sp
کمی بعدتر برنامه در نخ GUI صف را بررسی می‌کند، این اطلاعات را دریافت کرده و پنجره درخواست نظر کاربر را نمایش می‌دهد. سپس اگر درخواست گفتگو پذیرفته شد، برنامه تابع \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' را فراخوانی می‌کند، و اگر رد شد، تابع \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' را صدا می‌زند. هر دو تابع شناسه \fIdccid\fP را می‌پذیرند که این درخواست خاص را مشخص می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// جایی در نخ GUI
if ( !dcc_queue.empty() )
{
    // دریافت اطلاعات DCC و نمایش کادر محاوره‌ای به کاربر
    irc_dcc_t dccid = dcc_chat_queue.top().dccid;

    ...

    // واکنش به ورودی کاربر
    if ( dialog.isAccepted() )
        irc_dcc_accept( session, dccid, 0, dcc_callback );
    else
        irc_dcc_decline( session, dccid );
}
.EE
.UNINDENT
.UNINDENT
.SS "ارسال پیام‌های گفتگوی DCC (Send CHAT messages)"
.sp
پس از برقراری نشست گفتگو، می‌توانید پیام‌های گفتگو را با استفاده از تابع \fBirc_dcc_text()\fP ارسال کنید. توجه داشته باشید که به جای نام مستعار، باید شناسه نشست dcc را ارسال کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
irc_dcc_text( session, dccid, \(dqHello there!\(dq );
.EE
.UNINDENT
.UNINDENT
.SS "مدیریت انتقال فایل DCC (Handling DCC file transfer)"
.sp
این بخش مدیریت ارسال و دریافت فایل‌ها از طریق DCC را پوشش می‌دهد.
.SS "پیاده‌سازی فراخوانی بازگشتی (Implementing the callback)"
.sp
صرف‌نظر از اینکه قصد ارسال یا دریافت فایل‌ها از طریق dcc را دارید، باید \fBکال‌بک DCC\fP را پیاده‌سازی کنید. در حالی که ممکن است از همان کال‌بک برای هر دو مورد ارسال و دریافت استفاده شود، اما به دلیل تفاوت منطق، این کار توصیه نمی‌شود. بنابراین پیاده‌سازی پیشنهادی استفاده از کال‌بک‌های متفاوت به صورت زیر است:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// این کال‌بک هنگام ارسال فایل به طرف مقابل استفاده می‌شود
void callback_dcc_send_file (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
{
   if ( status )
   {
       // این یک خطا است؛ عملیات ارسال متوقف شده یا اتصال برقرار نشده است. status کد خطا است؛ ()irc_strerror را ببینید
   }
   else
   {
       // داده‌هایی را به طرف مقابل ارسال کردیم، 'length' مقدار داده ارسال‌شده را نشان می‌دهد
       printf (\(dqSent bytes: %d\en\(dq, length );
   }
}

// این کال‌بک زمانی استفاده می‌شود که فایلی از طرف مقابل دریافت می‌کنیم
void callback_dcc_recv_file (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
{
   if ( status )
   {
       // این یک خطا است؛ عملیات ارسال متوقف شده یا اتصال برقرار نشده است. status کد خطا است؛ ()irc_strerror را ببینید
   }
   else if ( data == 0 )
   {
       // انتقال فایل به پایان رسید
       printf (\(dqFile has been received successfully\en\(dq );
   }
   else
   {
       // بخش دیگری از محتوای فایل دریافت شد. آن را در حافظه ذخیره کنید، روی دیسک بنویسید یا موارد مشابه
       printf (\(dqReceived %d bytes of data\en\(dq, length );
   }
}
.EE
.UNINDENT
.UNINDENT
.sp
این کال‌بک باید یا به تابع \X'tty: link #c.irc_dcc_sendfile'\fI\%irc_dcc_sendfile()\fP\X'tty: link' که درخواست را آغاز می‌کند، یا به تابع \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' که درخواست DCC RECVFILE آغاز شده توسط کاربر دیگر را می‌پذیرد، فرستاده شود.
.SS "ارسال فایل از طریق DCC (Sending the file via DCC)"
.sp
می‌توانید ارسال فایل از طریق DCC به کاربر دیگر را با فراخوانی \X'tty: link #c.irc_dcc_sendfile'\fI\%irc_dcc_sendfile()\fP\X'tty: link' آغاز کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// شناسه نشست DCC در این متغیر بازگردانده می‌شود
irc_dcc_t dccid;

// آغاز ارسال فایل "/etc/passwd" از طریق گفتگوی DCC به کاربر "john" در IRC
if ( irc_dcc_sendfile( session, 0, \(dqjohn\(dq, \(dq/etc/passwd\(dq, callback_dcc_send_file, &dccid ) )
  // گزارش خطا
.EE
.UNINDENT
.UNINDENT
.sp
اکنون می‌توانید به کارهای دیگر ادامه دهید. وقتی جان درخواست را بپذیرد، فایل ارسال می‌شود و callback_dcc_send_file() هر بار که تکه‌ای از فایل ارسال می‌شود فراخوانی خواهد شد. همچنین پس از ارسال کامل فایل یا هنگامی که ارسال به دلیل خطای شبکه متوقف شود، این کال‌بک فراخوانی خواهد شد.
.SS "دریافت فایل از طریق DCC (Receive a file via DCC)"
.sp
برای دریافت فایل از طریق DCC، یک کاربر دوردست باید درخواست DCC برای ارسال فایلی به شما را آغاز کند. برای دریافت این درخواست، برنامه شما باید رویداد \fBevent_dcc_send_req\fP را پیاده‌سازی کند. این کال‌بک می‌تواند به صورت زیر پیاده‌سازی شود:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
void callback_event_dcc_file( irc_session_t * session, const char * nick, const char * addr, const char * filename, unsigned long size, irc_dcc_t dccid )
{
    // کاربر 'nick' از نشانی IP با مقدار 'addr' تلاش می‌کند گفتگوی DCC با ما آغاز کند.
    // این اطلاعات را همراه با dccid در صف برنامه ذخیره کنید تا کال‌بک بتواند بازگردد
    dcc_queue.store( dccid, \(dqCHAT from \(dq + nick + \(dq IP address: \(dq + addr + \(dq, filename \(dq + filename  );
}
.EE
.UNINDENT
.UNINDENT
.sp
اگر برنامه شما اصلاً DCC را مدیریت نمی‌کند، می‌توانید تابع \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' را داخل کال‌بک صدا بزنید.
.sp
اگر مدیریت می‌کند، ما فقط این اطلاعات را در کال‌بک ذخیره کرده و بازمی‌گردیم. زیرا پردازش رویدادها تا زمان بازگشت کال‌بک متوقف می‌شود، بنابراین نمایش کادر محاوره‌ای برای درخواست تایید از کاربر، پردازش رویدادهای بعدی مانند پیام‌های کانال را متوقف می‌کند. حتی اگر برنامه شما خودکار باشد و پنجره‌ای نمایش ندهد، باز هم بهتر است منطق گفتگو را از منطق فراخوانی بازگشتی جدا کنید.
.sp
کمی بعدتر برنامه در نخ GUI صف را بررسی می‌کند، این اطلاعات را دریافت کرده و کادر محاوره‌ای درخواست تایید کاربر را نمایش می‌دهد. سپس اگر درخواست پذیرفته شد، برنامه تابع \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' را صدا می‌زند، و اگر رد شد، تابع \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' را فراخوانی می‌کند. هر دو تابع شناسه \fIdccid\fP را می‌پذیرند که این درخواست خاص را مشخص می‌کند:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
// جایی در نخ GUI
if ( !dcc_queue.empty() )
{
    // دریافت اطلاعات DCC و نمایش کادر محاوره‌ای به کاربر
    irc_dcc_t dccid = dcc_chat_queue.top().dccid;

    ...

    // واکنش به ورودی کاربر
    if ( dialog.isAccepted() )
        irc_dcc_accept( session, dccid, 0, dcc_callback );
    else
        irc_dcc_decline( session, dccid );
}
.EE
.UNINDENT
.UNINDENT
.sp
توجه داشته باشید که امکان ارسال درخواست به یک کاربر دوردست برای فرستادن یک فایل به شما وجود ندارد.
.SS "مدیریت رنگ‌ها (Handling colors)"
.SS "حذف رنگ‌ها از پیام (Stripping colors from the message)"
.sp
اگر ربات شما به پیام‌های متنی واکنش نشان می‌دهد، باید پیش از پردازش پیام‌ها رنگ‌ها را از آن‌ها پاک کنید. در غیر این صورت کاربری که پیام رنگی ارسال می‌کند پاسخی مشابه کاربری که از رنگ استفاده نکرده دریافت نخواهد کرد، و برخی کاربران به طور پیش‌فرض از رنگ‌ها استفاده می‌کنند.
.sp
از تابع \X'tty: link #c.irc_color_strip_from_mirc'\fI\%irc_color_strip_from_mirc()\fP\X'tty: link' برای پاک کردن رنگ‌های ANSI از پیام متنی استفاده کنید. این تابع پیامی را که از رنگ استفاده نکرده تغییر نمی‌دهد.
.SS "تبدیل رنگ (Color conversion)"
.sp
این کتابخانه از تبدیل رنگ پشتیبانی می‌کند و می‌تواند رنگ‌ها را بین رنگ‌های ANSI مورد استفاده کلاینت‌های IRC و نمایش متنی آن‌ها تبدیل کند. استفاده از رنگ‌ها معمولاً به پیام‌ها و دلایل مشخص‌شده توسط کاربر محدود می‌شود. نمی‌توانید از رنگ‌ها به عنوان بخشی از نام مستعار یا نام کانال خود استفاده کنید.
.sp
از تابع \X'tty: link #c.irc_color_convert_from_mirc'\fI\%irc_color_convert_from_mirc()\fP\X'tty: link' برای تبدیل رنگ‌ها از ANSI به نمایش متنی کتابخانه، و از تابع \X'tty: link #c.irc_color_convert_to_mirc'\fI\%irc_color_convert_to_mirc()\fP\X'tty: link' برای تبدیل نمایش متنی رنگ‌ها در کتابخانه به ANSI استفاده کنید.
.sp
فراموش نکنید که پس از پایان استفاده، اشاره‌گر بازگردانده‌شده را با free() آزاد کنید.
.SS "متفرقه (Miscellaneous)"
.SS "ردیابی نام‌های مستعار کاربران (Tracking user nicks)"
.sp
اگر برنامه شما سهمیه‌های خاصی را برای هر کاربر نگهداری می‌کند، ردیابی تغییرات نام مستعار اهمیت دارد. از آنجا که نام مستعار تنها شناسه در دسترس شماست، هر بار که کاربر نام مستعار خود را تغییر می‌دهد باید پایگاه داده سهمیه خود را به‌روزرسانی کنید. برای انجام این کار باید رویداد \fBevent_nick\fP را شنود کنید. برای جزئیات به examples/censor.c مراجعه کنید.
.SH "مرجع رابط برنامه‌نویسی (API REFERENCE)"
.SS "فراخوانی‌های بازگشتی (Callbacks)"
.sp
این بخش فراخوانی‌های بازگشتی (کال‌بک‌ها) پشتیبانی‌شده توسط کتابخانه را شرح می‌دهد.
.SS irc_event_callback_t
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B typedef void (*irc_event_callback_t) (irc_session_t * session, const char * event, const char * origin, const char ** params, unsigned int count)
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
نشست IRC که رویداد را ایجاد کرده است
T}
_
T{
\fIevent\fP
T}	T{
نام متنی رویداد. در صورتی که از یک گرداننده رویداد واحد برای مدیریت چندین رویداد استفاده شود مفید است
T}
_
T{
\fIorigin\fP
T}	T{
مبدأ و ایجادکننده رویداد. بسته به نوع رویداد متفاوت است.
T}
_
T{
\fIparams\fP
T}	T{
پارامترهای اضافی در صورت وجود برای این رویداد. تعداد پارامترهای اضافی به نوع رویداد بستگی دارد و ممکن است صفر باشد. هر پارامتر یک رشته متنی خاتمه‌یافته با NULL است. هیچ‌یک از پارامترها نمی‌تواند NULL باشد، اما خود اشاره‌گر \fIparams\fP برای برخی رویدادها ممکن است NULL باشد.
T}
_
T{
\fIcount\fP
T}	T{
تعداد ورودی‌های ارائه‌شده در آرگومان \fIparams\fP.
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
هر رویداد IRC یک فراخوانی بازگشتی ایجاد می‌کند. این نوع کال‌بک سراسری است و تقریباً توسط تمام رویدادهای IRC استفاده می‌شود. بسته به ماهیت رویداد، می‌تواند صفر یا چند پارامتر داشته باشد. برای هر نوع رویداد، تعداد پارامترهای ارائه‌شده ثابت است و معنای آن‌ها در ساختار \fBirc_callbacks_t\fP توصیف شده است.
.sp
هر رویداد دارای یک مبدأ است (یعنی چه کسی رویداد را آغاز کرده است). در برخی موارد متغیر \fIorigin\fP ممکن است NULL باشد که نشان می‌دهد مبدأ رویداد ناشناخته است. مبدأ معمولاً شبیه به \fInick!host@ircserver\fP است، مانند \fItim!home@irc.server.net\fP\&. چنین مبدأهایی نمی‌توانند در دستورات IRC استفاده شوند و قبل از استفاده باید پیراسته شوند (یعنی بخش میزبان و سرور باید حذف شود). این کار می‌تواند یا به صورت دستی با فراخوانی \X'tty: link #c.irc_target_get_nick'\fI\%irc_target_get_nick()\fP\X'tty: link' یا به صورت خودکار برای همه رویدادها با تنظیم گزینه \X'tty: link #c.LIBIRC_OPTION_STRIPNICKS'\fI\%LIBIRC_OPTION_STRIPNICKS\fP\X'tty: link' از طریق \X'tty: link #c.irc_option_set'\fI\%irc_option_set()\fP\X'tty: link' انجام گیرد.
.SS irc_event_dcc_chat_t
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B typedef void (*irc_event_dcc_chat_t) (irc_session_t * session, const char * nick, const char * addr, irc_dcc_t dccid)
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
نشست IRC که رویداد را ایجاد می‌کند (نشستی که توسط irc_create_session بازگردانده شده است)
T}
_
T{
\fInick\fP
T}	T{
کاربری که درخواست گفتگو داده است
T}
_
T{
\fIaddr\fP
T}	T{
نشانی IP شخص مانند 189.12.34.56
T}
_
T{
\fIdccid\fP
T}	T{
شناسه مرتبط با این درخواست که باید به توابع \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' یا \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' فرستاده شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این کال‌بک زمانی فراخوانی می‌شود که شخصی از شما درخواست DCC CHAT کند. گفتگوی DCC نوعی گفتگو است که به جای عبور از سرور IRC، مستقیماً میان کلاینت‌ها صورت می‌گیرد. از آنجا که برای برقراری آن باید اتصال TCP تشکیل شود، معمولاً آغازکننده باید IP عمومی داشته باشد یا از نرم‌افزار ویژه‌ای روی فایروال برای هدایت پورت (port forwarding) استفاده کند.
.sp
شما باید به درخواست گفتگو یا با فراخوانی \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' برای پذیرش آن، یا با فراخوانی \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' برای رد آن پاسخ دهید.
.SS irc_event_dcc_send_t
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B typedef void (*irc_event_dcc_send_t) (irc_session_t * session, const char * nick, const char * addr, const char * filename, unsigned long size, irc_dcc_t dccid)
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
نشست IRC که رویداد را ایجاد می‌کند (نشستی که توسط irc_create_session بازگردانده شده است)
T}
_
T{
\fInick\fP
T}	T{
کاربری که درخواست ارسال فایل داده است
T}
_
T{
\fIaddr\fP
T}	T{
نشانی IP شخص مانند 189.12.34.56
T}
_
T{
\fIfilename\fP
T}	T{
نام فایلی که کاربر سعی در ارسال آن برای شما دارد
T}
_
T{
\fIsize\fP
T}	T{
اندازه فایل
T}
_
T{
\fIdccid\fP
T}	T{
شناسه مرتبط با این درخواست که باید به توابع \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' یا \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' فرستاده شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این کال‌بک زمانی فراخوانی می‌شود که کسی بخواهد با استفاده از DCC SEND فایلی برای شما ارسال کند. ارسال با DCC SEND مستقیماً میان کلاینت‌ها انجام می‌شود و نیازمند برقراری اتصال TCP است. بنابراین آغازکننده باید IP عمومی یا تنظیمات هدایت پورت در فایروال داشته باشد.
.sp
شما باید به درخواست گفتگو یا با فراخوانی \X'tty: link #c.irc_dcc_accept'\fI\%irc_dcc_accept()\fP\X'tty: link' برای پذیرش آن، یا با فراخوانی \X'tty: link #c.irc_dcc_decline'\fI\%irc_dcc_decline()\fP\X'tty: link' برای رد آن پاسخ دهید.
.SS irc_dcc_callback_t
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B typedef void (*irc_dcc_callback_t) (irc_session_t * session, irc_dcc_t id, int status, void * ctx, const char * data, unsigned int length)
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
نشست IRC که رویداد را ایجاد می‌کند (نشستی که توسط irc_create_session بازگردانده شده است)
T}
_
T{
\fIid\fP
T}	T{
شناسه نشست DCC
T}
_
T{
\fIstatus\fP
T}	T{
وضعیت اتصال DCC. مقدار ۰ یعنی خطایی وجود ندارد، در غیر این صورت شامل کد خطا است
T}
_
T{
\fIctx\fP
T}	T{
بافت ارائه‌شده توسط کاربر
T}
_
T{
\fIdata\fP
T}	T{
داده‌های دریافت‌شده (در صورت وجود)، در غیر این صورت NULL
T}
_
T{
\fIlength\fP
T}	T{
اندازه داده‌های دریافتی در صورت وجود داده
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این کال‌بک برای تمام توابع DCC هنگامی که تغییر وضعیت رخ دهد فراخوانی می‌شود.
.INDENT 0.0
.TP
.B برای DCC CHAT، کال‌بک به شرح زیر فراخوانی می‌شود:
.INDENT 7.0
.IP \(bu 2
مقدار \fIstatus\fP برابر \X'tty: link #c.LIBIRC_ERR_CLOSED'\fI\%LIBIRC_ERR_CLOSED\fP\X'tty: link' است: اتصال توسط طرف مقابل بسته شده است. پس از بازگشت از کال‌بک، نشست DCC به طور خودکار نابود می‌شود.
.IP \(bu 2
مقدار \fIstatus\fP غیرصفر است اما \X'tty: link #c.LIBIRC_ERR_CLOSED'\fI\%LIBIRC_ERR_CLOSED\fP\X'tty: link' نیست: خطای I/O سوکت (خطای اتصال، خطای پذیرش، خطای دریافت، خطای ارسال). پس از بازگشت از کال‌بک، نشست DCC به طور خودکار نابود می‌شود.
.IP \(bu 2
مقدار \fIstatus\fP صفر و \fIlength\fP صفر است: طرف مقابل درخواست گفتگو را پذیرفته است.
.IP \(bu 2
مقدار \fIstatus\fP صفر و \fIlength\fP غیرصفر است: پیام گفتگوی جدیدی دریافت شد، \fIdata\fP حاوی پیام (یک رشته خاتمه‌یافته با null) است و \fIlength\fP طول رشته بدون محاسبه null را در بر دارد.
.UNINDENT
.TP
.B برای DCC SEND، در حین ارسال فایل، کال‌بک به شرح زیر فراخوانی می‌شود:
.INDENT 7.0
.IP \(bu 2
مقدار \fIstatus\fP غیرصفر است: خطای I/O سوکت (خطای اتصال، خطای پذیرش، خطای دریافت، خطای ارسال). پس از بازگشت از کال‌بک، نشست DCC به طور خودکار نابود می‌شود.
.IP \(bu 2
مقدار \fIstatus\fP صفر است: بسته داده دیگری ارسال شده است، \fIlength\fP شامل کل مقدار داده ارسال‌شده تا این لحظه است، و \fIdata\fP مقدار NULL دارد.
.UNINDENT
.TP
.B برای DCC RECV، در حین دریافت فایل، کال‌بک به شرح زیر فراخوانی می‌شود:
.INDENT 7.0
.IP \(bu 2
مقدار \fIstatus\fP غیرصفر است: خطای I/O سوکت (خطای اتصال، خطای پذیرش، خطای دریافت، خطای ارسال). پس از بازگشت از کال‌بک، نشست DCC به طور خودکار نابود می‌شود.
.IP \(bu 2
مقدار \fIstatus\fP صفر است و \fIdata\fP مقدار NULL دارد: فایل با موفقیت دریافت شد. پس از بازگشت از کال‌بک، نشست DCC به طور خودکار نابود می‌شود.
.IP \(bu 2
مقدار \fIstatus\fP صفر است و \fIdata\fP مقدار NULL ندارد: داده‌های جدید دریافت شد، \fIdata\fP حاوی داده‌های دریافتی است و \fIlength\fP مقدار داده‌های دریافت شده را نشان می‌دهد.
.UNINDENT
.UNINDENT
.SS irc_eventcode_callback_t
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B typedef void (*irc_eventcode_callback_t) (irc_session_t * session, unsigned int event, const char * origin, const char ** params, unsigned int count)
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
نشست IRC که رویداد را ایجاد می‌کند (نشستی که توسط irc_create_session بازگردانده شده است)
T}
_
T{
\fIevent\fP
T}	T{
کد عددی رویداد. در صورتی که از یک گرداننده رویداد واحد برای مدیریت چندین رویداد استفاده شود مفید است
T}
_
T{
\fIorigin\fP
T}	T{
مبدأ و ایجادکننده رویداد. بسته به نوع رویداد متفاوت است.
T}
_
T{
\fIparams\fP
T}	T{
پارامترهای اضافی در صورت وجود برای این رویداد. تعداد پارامترهای اضافی به نوع رویداد بستگی دارد و ممکن است صفر باشد. هر پارامتر یک رشته متنی خاتمه‌یافته با NULL است. هیچ‌یک از پارامترها نمی‌تواند NULL باشد، اما خود اشاره‌گر \fIparams\fP برای برخی رویدادها ممکن است NULL باشد.
T}
_
T{
\fIcount\fP
T}	T{
تعداد ورودی‌های ارائه‌شده در آرگومان \fIparams\fP.
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این یک کال‌بک پیشرفته برای کسانی است که می‌خواهند رویدادها را در سطحی عمیق‌تر مدیریت کنند. در بیشتر مواقع سرور IRC به اقدامات شما با رویدادهای عددی پاسخ می‌دهد. بیشتر این رویدادها کدهای خطا هستند، و برخی نشانگرهای شروع و پایان فهرست هستند. هر کد مجموعه پارامترهای خود را دارد؛ برای جزئیات می‌توانید آزمایش کنید یا RFC 1459 را بخوانید (البته انتظار نداشته باشید سرورها دقیقاً از آن پیروی کنند).
.sp
هر رویداد دارای یک مبدأ است (یعنی چه کسی رویداد را آغاز کرده است). در برخی موارد متغیر \fIorigin\fP ممکن است NULL باشد که نشان می‌دهد مبدأ رویداد ناشناخته است. مبدأ معمولاً شبیه به \fInick!host@ircserver\fP است، مانند \fItim!home@irc.server.net\fP\&. چنین مبدأهایی نمی‌توانند در دستورات IRC استفاده شوند و قبل از استفاده باید پیراسته شوند (یعنی بخش میزبان و سرور باید حذف شود). این کار می‌تواند یا به صورت دستی با فراخوانی \X'tty: link #c.irc_target_get_nick'\fI\%irc_target_get_nick()\fP\X'tty: link' یا به صورت خودکار برای همه رویدادها با تنظیم گزینه \X'tty: link #c.LIBIRC_OPTION_STRIPNICKS'\fI\%LIBIRC_OPTION_STRIPNICKS\fP\X'tty: link' از طریق \X'tty: link #c.irc_option_set'\fI\%irc_option_set()\fP\X'tty: link' انجام گیرد.
.SS "توابع (Functions)"
.sp
این بخش توابع تعریف‌شده در کتابخانه را شرح می‌دهد که بر اساس هدف گروه‌بندی شده‌اند.
.SS "راه‌اندازی و خاتمه کتابخانه (Library initialization and shutdown)"
.SS irc_create_session
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B irc_session_t *irc_create_session(irc_callbacks_t *callbacks) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l.
T{
\fIcallbacks\fP | ساختار فراخوانی‌های بازگشتی رویداد، که چندین کال‌بک را برای فراخوانی در زمان رویدادهای مناسب تعریف می‌کند. نمی‌تواند NULL باشد.
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
یک نشست جدید IRC ایجاد و آغاز می‌کند. هر نشست نشان‌دهنده یک اتصال واحد کاربر به یک سرور IRC منفرد است، و احتمالاً به یک یا چند کاربر دیگر از طریق DCC. تقریباً تمام توابع کتابخانه نیازمند ارسال این شیء هستند، و بنابراین این تابع باید در ابتدا فراخوانی شود. چندین نشست را می‌توان برای پشتیبانی از اتصالات متعدد تخصیص داد.
.sp
هنگامی که دیگر نیازی به نشست نباشد، باید با فراخوانی تابع \fI\%irc_destroy_session()\fP از بین برود.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
یک شیء \fBirc_session_t\fP، یا 0 در صورت شکست عملیات ایجاد. معمولاً شکست به دلیل خطای کمبود حافظه رخ می‌دهد.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود. ساختار کال‌بک یکسان می‌تواند توسط چندین نخ مجدداً استفاده شود.
.SS irc_destroy_session
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_destroy_session(irc_session_t *session) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l.
T{
\fIsession\fP | دستگیره نشست IRC
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع یک نشست IRC را نابود می‌کند، اتصال به سرور IRC را می‌بندد و تمام منابع استفاده‌شده را آزاد می‌نماید. پس از فراخوانی این تابع دیگر نباید از این شیء نشست استفاده کنید.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "اتصال، قطع اتصال و اجرای حلقه رویداد اصلی (Connecting, disconnecting and running the main event loop)"
.SS irc_connect6
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_connect6(irc_session_t *session, const char *server, unsigned short port, const char *password, const char *nick, const char *username, const char *realname) 
.UNINDENT
.SS irc_connect
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_connect(irc_session_t *session, const char *server, unsigned short port, const char *password, const char *nick, const char *username, const char *realname) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIserver\fP
T}	T{
نشانی IP یا نام میزبان سرور. اگر با # شروع شود، کتابخانه تلاش می‌کند اتصال SSL برقرار کند. نشانی IPv4 باید به شکل عددی مانند 154.23.112.33 باشد؛ نشانی IPv6 باید در قالب استانداردهای IPv6 باشد
T}
_
T{
\fIport\fP
T}	T{
شماره پورت برای اتصال، معمولاً 6667
T}
_
T{
\fIpassword\fP
T}	T{
گذرواژه سرور IRC، در صورتی که سرور به آن نیاز داشته باشد. می‌تواند NULL باشد که در این صورت گذرواژه‌ای به سرور IRC ارسال نخواهد شد. اکثریت قریب به اتفاق سرورهای IRC نیازی به گذرواژه ندارند. این گذرواژه مربوط به NickServ/ChanServ نیست
T}
_
T{
\fInick\fP
T}	T{
نام مستعاری که برای ورود به سرور IRC استفاده می‌شود. نمی‌تواند NULL باشد
T}
_
T{
\fIusername\fP
T}	T{
نام کاربری حساب کاربری یونیکس که برای اتصال به سرور IRC استفاده می‌شود. این مورد صرفاً جنبه اطلاع‌رسانی دارد و در کادرهای محاوره‌ای «ویژگی‌های کاربر» نمایش داده می‌شود و با درخواست whois/ بازگردانده می‌شود. می‌تواند NULL باشد که در این صورت مقدار "nobody" استفاده خواهد شد
T}
_
T{
\fIrealname\fP
T}	T{
نام واقعی شخصی که به IRC متصل می‌شود. در عمل معمولاً برای توصیف خود، تبلیغات یا اهداف دیگر به کار می‌رود. این اطلاعات نیز در کادرهای محاوره‌ای «ویژگی‌های کاربر» نمایش داده می‌شود و با درخواست whois/ بازگردانده می‌شود. می‌تواند NULL باشد که در این صورت "noname" استفاده خواهد شد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع اتصال به سرور IRC در پروتکل IPv4 (تابع irc_connect) یا IPv6 (تابع irc_connect6) را آغاز می‌کند. سرور می‌تواند با نشانی IP یا نام دامنه DNS مشخص شود. تابع irc_connect6 تنها در صورتی کار می‌کند که کتابخانه با پشتیبانی از IPv6 بیلد شده باشد.
.sp
اگر کتابخانه با پشتیبانی از OpenSSL بیلد شده باشد و نشانی IP یا نام میزبان با یک علامت هش پیشوند شود (مانند \fB\(dq#irc.example.com\(dq\fP)، کتابخانه تلاش می‌کند اتصال SSL برقرار کند.
.sp
اتصال به صورت ناهمگام برقرار می‌شود و پس از برقراری موفق، رویداد \fBevent_connect\fP فراخوانی می‌گردد.
.sp
یک شیء نشست IRC تنها می‌تواند به یک سرور IRC متصل باشد و فقط با یک نام مستعار، به این معنی که امکان استفاده چند نام مستعار به صورت مشترک از یک اتصال واحد وجود ندارد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
در صورت آغاز موفقیت‌آمیز اتصال، مقدار 0 برمی‌گرداند. این به معنای برقراری کامل اتصال نیست؛ هنگامی که اتصال برقرار شود رویداد \fBevent_connect\fP فراخوانی می‌شود. اگر اتصال برقرار نشود، یا تابع \fI\%irc_run()\fP یا تابع \fI\%irc_process_select_descriptors()\fP یک خطا بازمی‌گردانند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود، اما نه با استفاده از شیء نشست یکسان.
.SS irc_disconnect
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_disconnect(irc_session_t *session) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l.
T{
\fIsession\fP   | دستگیره نشست IRC
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع اتصال IRC را می‌بندد. پس از بسته شدن اتصال، اگر libirc در حلقه \fI\%irc_run()\fP قفل شده باشد، به طور خودکار از حلقه خارج شده و تابع \fI\%irc_run()\fP بازمی‌گردد.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود، اما نه با استفاده از یک شیء نشست یکسان.
.SS irc_is_connected
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_is_connected(irc_session_t *session) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
.TE
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
این تابع در صورتی که اتصال به سرور IRC برقرار باشد مقدار 1 و در غیر این صورت مقدار 0 برمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_run
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_run(irc_session_t *session) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع وارد یک حلقه بی‌پایان می‌شود، رویدادهای IRC را پردازش می‌کند و فراخوانی‌های بازگشتی مربوطه را صدا می‌زند. این تابع تا زمانی که اتصال سرور قطع نشود (یا توسط سرور یا با فراخوانی \fI\%irc_cmd_quit\fP) بازنخواهد گشت. این تابع فقط در صورتی باید استفاده شود که از یک نشست منفرد IRC استفاده می‌کنید و نیازی به پردازش درخواست‌های ناهمگام ندارید (یعنی ربات شما فقط به رویدادها واکنش نشان می‌دهد و آن‌ها را به صورت ناهمگام تولید نمی‌کند). حتی در حالت آخر، همچنان می‌توانید این تابع را فراخوانی کرده و نخ ناهمگام را در گرداننده رویداد \fBevent_connect\fP آغاز کنید. مثال‌ها را ببینید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
این تابع در صورتی که اتصال به سرور IRC برقرار نشود یا قطع شود، یک مقدار غیرصفر بازمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع نمی‌تواند از چندین نخ فراخوانی شود. به جای آن از \fI\%irc_add_select_descriptors()\fP و \fI\%irc_process_select_descriptors()\fP استفاده کنید.
.SS irc_add_select_descriptors
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_add_select_descriptors(irc_session_t *session, fd_set *in_set, fd_set *out_set, int *maxfd) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIin_set\fP
T}	T{
مجموعه توصیف‌کننده‌های ورودی fd_set برای ()select
T}
_
T{
\fIout_set\fP
T}	T{
مجموعه توصیف‌کننده‌های خروجی fd_set برای ()select
T}
_
T{
\fImaxfd\fP
T}	T{
بزرگ‌ترین توصیف‌کننده موجود در تمام مجموعه‌ها. در صورتی که libirc عدد بزرگ‌تری به آرایه FD_SET اضافه کند، به‌روزرسانی خواهد شد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع باید پس از فراخوانی \fI\%irc_connect()\fP استفاده شود. زمانی مفید است که حلقه پردازش رویداد مبتنی بر select اختصاصی خود را داشته باشید. برای استفاده از آن باید توصیف‌کننده‌های خود را در مجموعه‌ها قرار دهید، این تابع را برای افزودن توصیف‌کننده(های) کتابخانه به مجموعه فراخوانی کنید و سپس ()select را صدا بزنید. پس از بازگشت آن، باید \fI\%irc_process_select_descriptors()\fP را فراخوانی کنید که رویدادها را مدیریت کرده و کال‌بک‌های شما را صدا می‌زند(!). سپس می‌توانید رویدادهای سوکت خود را از مجموعه پردازش کنید. مثال را ببینید.
.sp
اگر از epoll استفاده می‌کنید چه؟ \X'tty: link #faq-epoll'\fI\%پرسش‌های متداول (FAQ)\fP\X'tty: link' را ببینید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
این تابع در صورتی که \fI\%irc_connect()\fP پیش از فراخوانی این تابع صدا زده نشده باشد، مقدار غیرصفر برمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود، اما به ندرت منطقی است.
.SS irc_process_select_descriptors
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_process_select_descriptors(irc_session_t *session, fd_set *in_set, fd_set *out_set) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIin_set\fP
T}	T{
مجموعه توصیف‌کننده‌های ورودی fd_set برای ()select
T}
_
T{
\fIout_set\fP
T}	T{
مجموعه توصیف‌کننده‌های خروجی fd_set برای ()select
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع باید به همراه تابع \fI\%irc_add_select_descriptors()\fP استفاده شود، که مستندات آن نحوه عملکرد مشترک آن‌ها را شرح می‌دهد.
.sp
توجه داشته باشید که هنگام پردازش رویدادها، این تابع کال‌بک‌های شما را فراخوانی می‌کند و تا زمانی که همه کال‌بک‌های شما بازنگردند، بازنخواهد گشت. در صورتی که در برنامه خود یک کادر محاوره‌ای (مانند تایید DCC CHAT یا DCC SEND) باز می‌کنید، این نکته را به خاطر داشته باشید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 به معنی موفقیت است. مقادیر دیگر به معنی خطا هستند و کد خطا را می‌توان از طریق ()irc_errno دریافت کرد.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ تنها برای اشیاء نشست متفاوت IRC فراخوانی شود.
.SS "مدیریت کانال‌های IRC: ورود، خروج، دعوت (Managing the IRC channels: joining, leaving, inviting)"
.SS irc_cmd_join
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_join(irc_session_t *session, const char *channel, const char *key) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال برای ورود. نمی‌تواند NULL باشد.
T}
_
T{
\fIkey\fP
T}	T{
کلید مخفی (گذرواژه) کانال. در صورت عدم نیاز می‌تواند NULL باشد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
از این تابع برای پیوستن به یک کانال جدید IRC استفاده کنید. اگر کانال وجود نداشته باشد، به طور خودکار توسط سرور IRC ایجاد خواهد شد. توجه داشته باشید که برای ورود به کانال دارای گذرواژه، باید گذرواژه را بدانید و آن را در آرگومان key مشخص کنید.
در صورت موفقیت‌آمیز بودن پیوستن، رویداد \fBevent_join\fP فراخوانی خواهد شد (با نام مستعار شما به عنوان مبدأ)، سپس معمولاً \fBevent_topic\fP فراخوانی می‌شود و پس از آن فهرست کاربران حاضر در کانال را (با استفاده از LIBIRC_RFC_RPL_NAMREPLY) دریافت خواهید کرد که شامل کاربری که به تازگی پیوسته است نیز می‌شود.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 به این معنی است که دستور با موفقیت به سرور IRC ارسال شده است. این به معنی موفقیت‌آمیز بودن قطعی عملیات نیست، و شما باید منتظر رویداد مناسب یا کد خطا از طریق رویداد \fBevent_numeric\fP بمانید.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_BANNEDFROMCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_INVITEONLYCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_BADCHANNELKEY
.IP \(bu 2
LIBIRC_RFC_ERR_CHANNELISFULL
.IP \(bu 2
LIBIRC_RFC_ERR_BADCHANMASK
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYCHANNELS
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_part
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_part(irc_session_t *session, const char *channel) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال برای خروج. نمی‌تواند NULL باشد.
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
از این تابع برای خروج از کانال IRC که قبلاً به آن پیوسته‌اید استفاده کنید. تلاش برای ترک کانالی که در آن حضور ندارید منجر به خطای سرور LIBIRC_RFC_ERR_NOTONCHANNEL می‌شود.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC ارسال شد. این به معنای موفقیت کامل عملیات نیست و باید منتظر رویداد مربوطه یا کد خطا از طریق \fBevent_numeric\fP بمانید.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_invite
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_invite(irc_session_t *session, const char *nick, const char *channel) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInick\fP
T}	T{
نام مستعار کاربری که دعوت می‌شود
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال برای ورود. نمی‌تواند NULL باشد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای دعوت شخصی به یک کانال «فقط‌دعوتی» استفاده می‌شود. «فقط‌دعوتی» (Invite-only) یک حالت کانال است که پیوستن به کانال را برای همه، به جز دعوت‌شدگان، محدود می‌کند. پس از دعوت، کاربر می‌تواند به این کانال بپیوندد. کاربری که دعوت شده رویداد \fBevent_invite\fP را دریافت خواهد کرد. توجه داشته باشید که برای دعوت کاربران باید اپراتور کانال باشید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است. شما باید منتظر رویداد مربوطه یا کد خطا از طریق \fBevent_numeric\fP باشید.
.INDENT 0.0
.TP
.B در صورت موفقیت، یکی از پاسخ‌های زیر بازگردانده می‌شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_RPL_INVITING
.IP \(bu 2
LIBIRC_RFC_RPL_AWAY
.UNINDENT
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NEEDMOREPARAMS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_ERR_USERONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_ERR_CHANOPRIVSNEEDED
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_names
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_names(irc_session_t *session, const char *channel); 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال(ها) برای دریافت فهرست کاربران. نام‌های متعدد باید با کاما جدا شوند
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای درخواست فهرست کاربرانی که به کانال مشخص‌شده پیوسته‌اند از سرور IRC استفاده می‌شود. می‌توانید تمام نام‌های مستعاری را که برای شما در هر کانال قابل مشاهده است فهرست کنید. فهرست کاربران با استفاده از کدهای عددی LIBIRC_RFC_RPL_NAMREPLY و LIBIRC_RFC_RPL_ENDOFNAMES بازگردانده می‌شود.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور فرستاده شد. برای تایید نهایی باید منتظر رویداد مربوطه باشید.
.INDENT 0.0
.TP
.B نام‌های کانال از طریق رویداد \fBevent_numeric\fP با کدهای پاسخ زیر بازگردانده می‌شوند:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_RPL_NAMREPLY
.IP \(bu 2
LIBIRC_RFC_RPL_ENDOFNAMES
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_list
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_list(irc_session_t *session, const char *channel) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال(ها) برای فهرست کردن. نام‌های چندگانه باید با کاما جدا شوند. اگر NULL باشد، تمام کانال‌ها فهرست می‌شوند
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای درخواست فهرست کانال‌های فعال (موجود) از سرور IRC استفاده می‌شود. این فهرست با توالی رویدادهای LIBIRC_RFC_RPL_LISTSTART، چندین LIBIRC_RFC_RPL_LIST و LIBIRC_RFC_RPL_LISTEND بازگردانده خواهد شد. توجه داشته باشید که کانال‌های «خصوصی» (بدون موضوع آن‌ها) به صورت کانال "Prv" فهرست می‌شوند، مگر اینکه کلاینت ارسال‌کننده پرس‌وجو واقعاً در آن کانال حضور داشته باشد. به همین ترتیب کانال‌های مخفی اصلاً فهرست نمی‌شوند مگر اینکه کلاینت در کانال مورد نظر فعال باشد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.
.INDENT 0.0
.TP
.B فهرست کانال‌ها از طریق رویداد \fBevent_numeric\fP با استفاده از کدهای پاسخ زیر بازگردانده می‌شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_RPL_LISTSTART
.IP \(bu 2
LIBIRC_RFC_RPL_LISTEND
.IP \(bu 2
LIBIRC_RFC_RPL_LIST
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_topic
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_topic(irc_session_t *session, const char *channel, const char *topic) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال
T}
_
T{
\fItopic\fP
T}	T{
موضوع جدید کانال. اگر NULL باشد، موضوع قبلی بازگردانده می‌شود و تغییری ایجاد نخواهد شد. برای خالی کردن موضوع از "" استفاده کنید
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای تغییر یا مشاهده موضوع (عنوان) یک کانال استفاده می‌شود. توجه داشته باشید که بسته به حالت t+ کانال، ممکن است برای تغییر موضوع کانال ملزم به داشتن دسترسی اپراتور کانال باشید.
.sp
اگر دستور موفقیت‌آمیز باشد، سرور IRC یک پیام LIBIRC_RFC_RPL_NOTOPIC یا LIBIRC_RFC_RPL_TOPIC تولید می‌کند که حاوی موضوع قدیمی یا تغییر یافته است. همچنین سرور IRC می‌تواند (اما الزامی نیست) پیام غیر RFC با عنوان LIBIRC_RFC_RPL_TOPIC_EXTRA تولید کند که حاوی نام مستعار فرد تغییردهنده موضوع و تاریخ و زمان آخرین تغییر است.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 نشان می‌دهد که دستور با موفقیت به سرور ارسال شده است.
.INDENT 0.0
.TP
.B اطلاعات موضوع با استفاده از یکی از کدهای پاسخ زیر بازگردانده می‌شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_RPL_NOTOPIC
.IP \(bu 2
LIBIRC_RFC_RPL_TOPIC
.UNINDENT
.UNINDENT
.sp
اگر تغییر موضوع درخواست شده و با موفقیت انجام شده باشد، رویداد \fBevent_topic\fP نیز تولید می‌شود.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NEEDMOREPARAMS
.IP \(bu 2
LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_channel_mode
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_channel_mode(irc_session_t *session, const char *channel, const char *mode) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIchannel\fP
T}	T{
نام کانال
T}
_
T{
\fImode\fP
T}	T{
حالتی که باید تغییر کند. اگر NULL باشد، حالت کانال تغییر نمی‌کند اما حالت قبلی بازگردانده می‌شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای تغییر یا مشاهده حالت‌های کانال به کار می‌رود. توجه داشته باشید که تنها اپراتورهای کانال می‌توانند حالت آن را تغییر دهند.
.sp
حالت کانال با ترکیبی از چندین حرف نشان داده می‌شود. هر حرف در حالت‌های کانال معنای خاص خود را دارد. بیشتر حروف حالت‌های کانال بولی هستند (یعنی فقط می‌توانند تنظیم یا بازنشانی شوند)، اما تعداد کمی از آن‌ها پارامتر می‌پذیرند. تمام گزینه‌های کانال با افزودن علامت مثبت قبل از حرف فعال، و با افزودن علامت منفی غیرفعال می‌شوند.
.sp
در اینجا فهرستی از حالت‌های «استاندارد» کانال آورده شده است:
.TS
box center;
l|l.
T{
o nickname
T}	T{
اعطای امتیازات اپراتور کانال به یک نام مستعار (+o nickname) یا سلب آن (\-o nickname). این حالت روی کاربران داخل کانال اثر می‌گذارد، نه خود کانال. مثال‌ها: "tim o+"، "watson o\-"
T}
_
T{
p
T}	T{
تنظیم (+p) یا بازنشانی (\-p) فلگ کانال خصوصی. کانال‌های خصوصی در فهرست کانال‌ها با عنوان 'Prv' و بدون موضوع نمایش داده می‌شوند
T}
_
T{
s
T}	T{
تنظیم (+s) یا بازنشانی (\-s) فلگ کانال مخفی. کانال‌های مخفی اصلاً در فهرست کانال‌ها نمایش داده نمی‌شوند
T}
_
T{
i
T}	T{
تنظیم (+i) یا بازنشانی (\-i) فلگ کانال فقط‌دعوتی. هنگامی که این فلگ تنظیم شود، تنها افرادی که توسط \fI\%irc_cmd_invite()\fP دعوت شده‌اند می‌توانند به این کانال بپیوندند
T}
_
T{
t
T}	T{
مجاز ساختن (+t) یا منع کردن (\-t) تغییر موضوع توسط کاربران غیر اپراتور. هنگامی که این فلگ تنظیم شود، فقط اپراتورهای کانال می‌توانند موضوع را تغییر دهند
T}
_
T{
n
T}	T{
تنظیم (+n) یا بازنشانی (\-n) محافظت در برابر کاربرانی که به کانال نپیوسته‌اند. هنگام فعال بودن حالت n+، تنها کاربرانی که وارد کانال شده‌اند می‌توانند به آن پیام بفرستند
T}
_
T{
m
T}	T{
تنظیم (+m) یا بازنشانی (\-m) مدیریت‌شده بودن (moderation) کانال. در این حالت فقط اپراتورهای کانال و کاربرانی که دارای حالت v+ هستند می‌توانند در کانال صحبت کنند
T}
_
T{
v nickname
T}	T{
اعطا (+v nick) یا سلب (\-v nick) توانایی صحبت در کانال مدیریت‌شده به کاربر. مثال‌ها: "bob v+"، "joy v\-"
T}
_
T{
l number
T}	T{
تنظیم (+l 20) یا حذف (\-l) محدودیت حداکثر تعداد کاربران مجاز در کانال. وقتی محدودیت تنظیم شود و تعداد کاربران به آن برسد، هیچ‌کس دیگری نمی‌تواند به کانال بپیوندد
T}
_
T{
k key
T}	T{
تنظیم (+k password) یا حذف (\-k) گذرواژه از کانال. وقتی این محدودیت فعال باشد، هر کاربری که وارد کانال می‌شود باید کلید کانال را ارائه دهد
T}
_
T{
b mask
T}	T{
تنظیم (+b \fI!*@\fP\&.mil) یا حذف (\-b \fI!*@\fP\&.mil) ماسک مسدودسازی (ban) روی کاربر برای دور نگه داشتن او از کانال. برای رفع مسدودیت باید ماسک دقیق را مشخص کنید، نه فقط "b\-"
T}
.TE
.sp
توجه داشته باشید که فهرست واقعی حالت‌های کانال به سرور IRC بستگی دارد و می‌تواند بزرگ‌تر باشد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.
.INDENT 0.0
.TP
.B اطلاعات حالت قبلی با استفاده از کدهای عددی زیر بازگردانده می‌شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_RPL_CHANNELMODEIS
.IP \(bu 2
LIBIRC_RFC_RPL_BANLIST
.IP \(bu 2
LIBIRC_RFC_RPL_ENDOFBANLIST
.UNINDENT
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NEEDMOREPARAMS
.IP \(bu 2
LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_KEYSET
.IP \(bu 2
LIBIRC_RFC_ERR_UNKNOWNMODE
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHCHANNEL
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_user_mode
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_user_mode(irc_session_t *session, const char *mode) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fImode\fP
T}	T{
حالتی که باید تغییر کند. اگر NULL باشد، حالت کاربر تغییر نمی‌کند اما حالت قبلی بازگردانده می‌شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای تغییر یا مشاهده حالت‌های کاربر استفاده می‌شود. توجه داشته باشید که بر خلاف حالت‌های کانال، برخی حالت‌های کاربر اصلاً قابل تغییر نیستند.
.sp
حالت کاربر با ترکیبی از حروف نشان داده می‌شود. تمام حروف حالت کاربر بولی هستند (یعنی فقط می‌توانند فعال یا غیرفعال شوند)، آن‌ها با اضافه کردن علامت مثبت فعال و با علامت منفی غیرفعال می‌شوند.
.sp
فهرست حالت‌های «استاندارد» کاربر:
.TS
box center;
l|l.
T{
o
T}	T{
نشان‌دهنده وضعیت اپراتور IRC است. نمی‌توان آن را مستقیماً تنظیم کرد (اما می‌توان آن را بازنشانی کرد)؛ برای تنظیم آن باید از دستور OPER در IRC استفاده کنید
T}
_
T{
i
T}	T{
در صورت تنظیم، کاربر را به عنوان «نامرئی» (invisible) علامت‌گذاری می‌کند - یعنی در جستجوها دیده نمی‌شود مگر اینکه کاربر در یک کانال حضور داشته باشد
T}
_
T{
w
T}	T{
در صورت تنظیم، کاربر را به عنوان دریافت‌کننده wallops علامت‌گذاری می‌کند - پیام‌های ویژه‌ای که توسط اپراتورهای IRC با استفاده از دستور WALLOPS ارسال می‌شوند
T}
_
T{
s
T}	T{
در صورت تنظیم، کاربر را برای دریافت اعلان‌های سرور علامت‌گذاری می‌کند
T}
_
T{
r
T}	T{
حالت غیر استاندارد. در صورت تنظیم، کاربر با سرویس NickServ در IRC احراز هویت شده است
T}
_
T{
x
T}	T{
حالت غیر استاندارد. در صورت تنظیم، نشانی IP واقعی کاربر توسط سرور IRC پنهان (ماسک) می‌شود
T}
.TE
.sp
توجه داشته باشید که فهرست واقعی حالت‌های کاربر به سرور IRC بستگی دارد و می‌تواند گسترده‌تر باشد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.
.sp
اطلاعات حالت قبلی با استفاده از کد عددی LIBIRC_RFC_RPL_UMODEIS بازگردانده می‌شود:
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NEEDMOREPARAMS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.IP \(bu 2
LIBIRC_RFC_ERR_UNKNOWNMODE
.IP \(bu 2
LIBIRC_RFC_ERR_USERSDONTMATCH
.IP \(bu 2
LIBIRC_RFC_ERR_UMODEUNKNOWNFLAG
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_kick
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_kick(irc_session_t *session, const char *nick, const char *channel, const char *reason); 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInick\fP
T}	T{
نام مستعاری که باید اخراج شود
T}
_
T{
\fIchannel\fP
T}	T{
کانالی که کاربر باید از آن اخراج شود
T}
_
T{
\fIreason\fP
T}	T{
اگر NULL نباشد، دلیل اخراج کاربر است
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای اخراج یک شخص از کانال استفاده می‌شود. توجه داشته باشید که برای اخراج دیگران از یک کانال باید اپراتور کانال باشید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است.
.sp
اگر دستور موفق شود، رویداد \fBevent_kick\fP تولید خواهد شد.
.INDENT 0.0
.TP
.B در صورت شکست دستور، یکی از پاسخ‌های \fBevent_numeric\fP زیر تولید می‌شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NEEDMOREPARAMS
.IP \(bu 2
LIBIRC_RFC_ERR_BADCHANMASK
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_CHANOPRIVSNEEDED
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "ارسال پیام‌ها، اعلان‌ها، پیام‌های /me و کار با CTCP (Sending the messages, notices, /me messages and working with CTCP)"
.SS irc_cmd_msg
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_msg(irc_session_t *session, const char *nch, const char *text) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInch\fP
T}	T{
نام مستعار مقصد یا کانال مقصد
T}
_
T{
\fItext\fP
T}	T{
متن پیام
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای ارسال پیام به یک کانال یا به طور خصوصی به یک نام مستعار دیگر استفاده می‌شود. در اینجا منظور از «خصوصی» این است که پیام به صورت عمومی منتشر نمی‌شود، اما همچنان از سرور IRC عبور می‌کند و توسط مدیران شبکه IRC قابل مشاهده است. مقصد پیام با آرگومان \fInch\fP مشخص می‌شود: اگر یک نام مستعار باشد، یک پیام خصوصی خواهد بود، اما اگر نام کانال باشد در آن کانال ارسال می‌شود.
.sp
پروتکل شما را ملزم نمی‌کند که برای ارسال پیام حتماً عضو کانال باشید، اما بیشتر کانال‌ها حالتی را تنظیم می‌کنند که از ارسال پیام توسط افرادی که عضو نیستند جلوگیری می‌کند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد. این به معنای موفقیت کامل عملیات نیست. باید منتظر رویداد مربوطه یا کد خطا از طریق رویداد \fBevent_numeric\fP بمانید.
.sp
اگر دستور موفق شود، به طور معمول رویدادی جز احتمال LIBIRC_RFC_RPL_AWAY تولید نمی‌شود.
.INDENT 0.0
.TP
.B اما اگر دستور ناموفق باشد، ممکن است یکی از رویدادهای عددی زیر تولید شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_me
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_me(irc_session_t *session, const char *nch, const char *text) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInch\fP
T}	T{
نام مستعار مقصد یا کانال مقصد
T}
_
T{
\fItext\fP
T}	T{
متن پیام
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای ارسال پیام me/ (کنش CTCP یا CTCP ACTION) به یک کانال یا به طور خصوصی به نام مستعار دیگر استفاده می‌شود. در اینجا منظور از «خصوصی» این است که پیام به طور عمومی منتشر نمی‌شود، اما همچنان از سرور IRC می‌گذرد و توسط مدیران شبکه IRC قابل مشاهده است. مقصد پیام با آرگومان \fInch\fP مشخص می‌شود: اگر نام مستعار باشد پیامی خصوصی خواهد بود، و اگر نام کانال باشد در کانال ارسال خواهد شد.
.sp
پروتکل نیازی به عضویت در کانال برای ارسال پیام به آن ندارد، اما بیشتر کانال‌ها حالتی دارند که ارسال پیام توسط افراد غیرعضو را مسدود می‌کند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور فرستاده شد.
.sp
در صورت موفقیت دستور، معمولاً هیچ رویدادی به جز احتمال LIBIRC_RFC_RPL_AWAY تولید نمی‌شود.
.INDENT 0.0
.TP
.B اما اگر دستور ناموفق باشد، ممکن است یکی از رویدادهای عددی زیر تولید شود:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_notice
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_notice(irc_session_t *session, const char *nch, const char *text) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInch\fP
T}	T{
نام مستعار مقصد یا کانال مقصد
T}
_
T{
\fItext\fP
T}	T{
متن پیام
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای ارسال اعلان (notice) به کانال یا به صورت خصوصی به یک نام مستعار استفاده می‌شود. مقصد با آرگومان \fInch\fP تعیین می‌گردد.
.sp
تنها تفاوت میان یک پیام معمولی و یک اعلان در این است که RFC صریحاً تأکید می‌کند که ربات‌های خودکار هرگز نباید به طور خودکار به NOTICE پاسخ دهند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 به این معنی است که دستور با موفقیت ارسال شده است.
.sp
در صورت موفقیت دستور، معمولاً رویدادی تولید نمی‌شود مگر احتمال LIBIRC_RFC_RPL_AWAY.
.INDENT 0.0
.TP
.B با این حال در صورت شکست دستور، ممکن است یکی از رویدادهای عددی زیر رخ دهد:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_ctcp_request
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_ctcp_request(irc_session_t *session, const char *nick, const char *request) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInick\fP
T}	T{
نام مستعار مقصد
T}
_
T{
\fIrequest\fP
T}	T{
متن درخواست CTCP
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای ارسال یک درخواست CTCP استفاده می‌شود. چهار درخواست CTCP توسط بیشتر کلاینت‌های IRC پشتیبانی می‌شوند:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
VERSION \- دریافت نام و نسخه نرم‌افزار کلاینت
.IP \(bu 2
FINGER  \- دریافت نام کاربری، میزبان و نام واقعی کلاینت
.IP \(bu 2
PING    \- سنجش میزان تأخیر ارتباط کلاینت
.IP \(bu 2
TIME    \- دریافت زمان محلی کلاینت
.UNINDENT
.UNINDENT
.UNINDENT
.sp
برخی کلاینت‌ها ممکن است از درخواست‌های دیگر نیز پشتیبانی کنند. سند RFC این درخواست‌ها را فهرست نکرده و هیچ‌گونه پشتیبانی از CTCP را اجباری ندانسته است.
.sp
اگر یک درخواست CTCP ارسال می‌کنید، مطمئن شوید که گرداننده‌ای برای \fBevent_ctcp_rep\fP جهت پردازش پاسخ تعریف کرده‌اید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور فرستاده شد.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_ctcp_reply
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_ctcp_reply(irc_session_t *session, const char *nick, const char *reply) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInick\fP
T}	T{
نام مستعار مقصد
T}
_
T{
\fIreply\fP
T}	T{
متن پاسخ CTCP
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای ارسال پاسخ به یک درخواست CTCP دریافت شده از رویداد \fBevent_ctcp_req\fP استفاده می‌شود. توجه داشته باشید که این رویداد را دریافت نخواهید کرد مگر اینکه در زمان مقداردهی اولیه نشست IRC گرداننده اختصاصی خود را مشخص کرده باشید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "متفرقه: نسخه کتابخانه، داده‌های خام، تغییر نام مستعار، خروج (Miscellaneous: library version, raw data, changing nick, quitting)"
.SS irc_cmd_nick
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_nick(irc_session_t *session, const char *newnick) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInick\fP
T}	T{
نام مستعار جدید
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای تغییر نام مستعار فعلی شما به یک نام مستعار دیگر استفاده می‌شود. توجه داشته باشید که چنین تغییری همیشه ممکن نیست؛ به عنوان مثال نمی‌توانید نام مستعار خود را به یک نام مستعار موجود یا (در برخی سرورها) به یک نام مستعار ثبت‌شده تغییر دهید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.
.INDENT 0.0
.TP
.B اگر عملیات موفق شود، سرور رویداد \fBevent_nick\fP را ارسال می‌کند. در غیر این صورت یک خطای عددی می‌فرستد. پاسخ‌های خطای احتمالی از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NONICKNAMEGIVEN
.IP \(bu 2
LIBIRC_RFC_ERR_ERRONEUSNICKNAME
.IP \(bu 2
LIBIRC_RFC_ERR_NICKNAMEINUSE
.IP \(bu 2
LIBIRC_RFC_ERR_NICKCOLLISION
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_whois
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_whois(irc_session_t *session, const char *nick) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fInick\fP
T}	T{
نام مستعار یا فهرست جداشده با کاما از نام‌های مستعار برای پرس‌وجوی اطلاعات
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع اطلاعات مختلفی را درباره یک نام مستعار استعلام می‌کند. میزان اطلاعات به سرور IRC بستگی دارد اما معمولاً شامل نام کاربری، نام واقعی (تعریف‌شده توسط کلاینت در زمان ورود)، سرور IRC مورد استفاده، کانال‌هایی که کاربر در آن‌ها حضور دارد، زمان بی‌کاری، حالت غیبت (away) و غیره است.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 نشان‌دهنده ارسال موفقیت‌آمیز دستور به سرور IRC است.
.INDENT 0.0
.TP
.B در صورت موفقیت درخواست، اطلاعات از طریق کدهای عددی زیر بازگردانده می‌شوند:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_RPL_WHOISUSER
.IP \(bu 2
LIBIRC_RFC_RPL_WHOISCHANNELS
.IP \(bu 2
LIBIRC_RFC_RPL_WHOISSERVER
.IP \(bu 2
LIBIRC_RFC_RPL_AWAY
.IP \(bu 2
LIBIRC_RFC_RPL_WHOISOPERATOR
.IP \(bu 2
LIBIRC_RFC_RPL_WHOISIDLE
.IP \(bu 2
LIBIRC_RFC_RPL_ENDOFWHOIS \- این رویداد اطلاعات WHOIS را خاتمه می‌دهد
.UNINDENT
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHSERVER
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.IP \(bu 2
LIBIRC_RFC_ERR_NONICKNAMEGIVEN
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_cmd_quit
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_cmd_quit(irc_session_t *session, const char *reason) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIreason\fP
T}	T{
در صورت غیر NULL بودن، دلیل خروج
T}
.TE
.sp
\fBتوضیحات (Description):\fP
این تابع دستور QUIT را به سرور IRC می‌فرستد. این دستور سرور IRC را وادار می‌کند تا اتصال IRC را ببندد و نشست را خاتمه دهد.
.sp
تفاوت میان این دستور و فراخوانی irc_disconnect در این است که این دستور امکان تعیین دلیل خروج را می‌دهد که به تمام کاربران حاضر در کانال‌های شما نمایش داده خواهد شد. همچنین مشخص می‌کند که شما عمداً کانال‌های IRC را ترک کرده‌اید، نه اینکه اتصال شما صرفاً قطع شده باشد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_send_raw
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_send_raw(irc_session_t *session, const char *format, \&...); 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIformat\fP
T}	T{
رشته قالب‌بندی از نوع printf به همراه آرگومان‌های قالب
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع داده‌های خام را به همان شکل به سرور IRC ارسال می‌کند. از آن برای تولید یک دستور سرور استفاده کنید که هنوز مستقیماً توسط libircclient ارائه نشده است.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_target_get_nick
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_target_get_nick(const char *origin, char *nick, size_t size) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
نام مستعار در قالب رایج سرور IRC مانند tim!root@mycomain.com
T}
_
T{
\fInick\fP
T}	T{
بافر برای بازیابی نام مستعار تجزیه‌شده
T}
_
T{
\fIsize\fP
T}	T{
اندازه بافر \fInick\fP. اگر نام مستعار تجزیه‌شده بزرگ‌تر از اندازه بافر باشد، کوتاه (truncate) خواهد شد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
برای بیشتر رویدادها سرور IRC مبدأ 'origin' (یعنی شخصی که این رویداد را ایجاد کرده) را در فرمت اصطلاحاً «رایج» بازمی‌گرداند، مانند \X'tty: link mailto:nick!host@domain'\fI\%nick!host@domain\fP\X'tty: link'\&. با این حال تمام توابع _irc_cmd فقط به یک نام مستعار ساده نیاز دارند. این تابع این مبدأ را تجزیه کرده و نام مستعار را استخراج می‌کند و آن را در بافر ارائه‌شده توسط کاربر ذخیره می‌نماید.
.sp
یک بافر به اندازه 128 بایت باید برای بیشتر نام‌های مستعار کافی باشد.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_target_get_host
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_target_get_host(const char *target, char *host, size_t size) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
نام مستعار در قالب رایج سرور IRC مانند tim!root@mycomain.com
T}
_
T{
\fIhost\fP
T}	T{
بافر برای بازیابی نام میزبان تجزیه‌شده
T}
_
T{
\fIsize\fP
T}	T{
اندازه بافر \fIhost\fP. اگر نام میزبان تجزیه‌شده بزرگ‌تر از اندازه بافر باشد، کوتاه خواهد شد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
برای بیشتر رویدادها سرور IRC مبدأ 'origin' را به صورت رایج nick!host@domain بازمی‌گرداند. این تابع این مبدأ را تجزیه کرده و میزبان (host) را استخراج می‌کند و در بافر ارائه‌شده توسط کاربر ذخیره می‌نماید.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "شروع و پذیرش نشست‌های گفتگوی DCC، ارسال و دریافت فایل‌ها (DCC initiating and accepting chat sessions, sending and receiving files)"
.SS irc_dcc_chat
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_dcc_chat(irc_session_t *session, void *ctx, const char *nick, irc_dcc_callback_t callback, irc_dcc_t *dccid) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIctx\fP
T}	T{
بافت تعریف‌شده توسط کاربر که به کال‌بک ارسال می‌شود. می‌تواند NULL باشد
T}
_
T{
\fInick\fP
T}	T{
نام مستعار مقصد
T}
_
T{
\fIcallback\fP
T}	T{
کال‌بک DCC که برای رویدادهای DCC و گفتگو استفاده خواهد شد
T}
_
T{
\fIdccid\fP
T}	T{
اگر این تابع موفق شود، شناسه نشست DCC در این فیلد ذخیره می‌شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع درخواست یک DCC CHAT میان شما و کاربر دیگر IRC می‌دهد. گفتگوی DCC شبیه به گفتگوی خصوصی است اما مستقیماً بین دو کاربر برقرار می‌شود و از سرور IRC عبور نمی‌کند. درخواست DCC CHAT پیش از اینکه بتوانید چیزی ارسال کنید باید توسط طرف مقابل پذیرفته شود.
.sp
هنگامی که گفتگو پذیرفته، رد یا متوقف شود، یا داده‌ای دریافت گردد، تابع \fIcallback\fP فراخوانی می‌شود. به طور مشخص، این فراخوانی بازگشتی زمانی صدا زده خواهد شد که:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
درخواست گفتگو پذیرفته شود؛
.IP \(bu 2
درخواست گفتگو رد شود؛
.IP \(bu 2
پیام گفتگوی جدیدی دریافت شود؛
.IP \(bu 2
گفتگو توسط طرف مقابل قطع شود؛
.UNINDENT
.UNINDENT
.UNINDENT
.sp
جزئیات را در اعلان \fBirc_dcc_callback_t\fP ببینید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد. این به معنای موفقیت قطعی عملیات نیست و باید منتظر رویداد مربوطه یا کد خطا از طریق \fBevent_numeric\fP بمانید.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_dcc_msg
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_dcc_msg(irc_session_t *session, irc_dcc_t dccid, const char *text) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIdccid\fP
T}	T{
شناسه نشست DCC برای نشست گفتگوی DCC که فعال است
T}
_
T{
\fItext\fP
T}	T{
پیام خاتمه‌یافته با NULL برای ارسال
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع برای ارسال پیام DCC CHAT به یک گفتگوی فعال DCC استفاده می‌شود. برای فعال بودن، درخواست DCC CHAT باید توسط یک طرف آغاز شده و توسط طرف دیگر پذیرفته شده باشد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی موفقیت. مقدار دیگر نشان‌دهنده خطا است و کد خطا از طریق ()irc_errno قابل دریافت است.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_dcc_accept
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_dcc_accept(irc_session_t *session, irc_dcc_t dccid, void *ctx, irc_dcc_callback_t callback) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIdccid\fP
T}	T{
شناسه نشست DCC بازگردانده‌شده توسط کال‌بک
T}
_
T{
\fIctx\fP
T}	T{
بافت تعریف‌شده توسط کاربر که به کال‌بک فرستاده می‌شود. می‌تواند NULL باشد
T}
_
T{
\fIcallback\fP
T}	T{
کال‌بک DCC که برای رویدادهای DCC و گفتگو استفاده خواهد شد
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع یک درخواست گفتگوی DCC یا انتقال فایل از راه دور را می‌پذیرد. پس از پذیرش درخواست، تابع \fIcallback\fP برای رویدادهای بعدی DCC، از جمله خاتمه نشست DCC، فراخوانی خواهد شد. اطلاعات کال‌بک DCC را ببینید.
.sp
این تابع باید تنها پس از دریافت رویدادهای \fBevent_dcc_chat_req\fP یا \fBevent_dcc_send_req\fP فراخوانی شود. شما مجبور نیستید بلافاصله در تابع پردازش رویداد ()irc_dcc_accept یا ()irc_dcc_decline را صدا بزنید - می‌توانید فقط \fIdccid\fP را ذخیره کرده و بازگردید، و این توابع را بعداً فراخوانی کنید. اما برای جلوگیری از نشت حافظه باید ظرف ۶۰ ثانیه پس از دریافت هر درخواست ورودی DCC، یکی از این دو تابع را صدا بزنید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی موفقیت. مقادیر دیگر یعنی خطا، کد خطا را می‌توان از طریق \fI\%irc_errno()\fP دریافت کرد.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_dcc_decline
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_dcc_decline(irc_session_t *session, irc_dcc_t dccid) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIdccid\fP
T}	T{
شناسه نشست DCC بازگردانده‌شده توسط کال‌بک
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع یک درخواست گفتگوی دوردست DCC یا انتقال فایل را رد می‌کند.
.sp
این تابع باید تنها پس از دریافت رویدادهای \fBevent_dcc_chat_req\fP یا \fBevent_dcc_send_req\fP فراخوانی شود. برای جلوگیری از نشت حافظه باید ظرف ۶۰ ثانیه یکی از توابع رد یا پذیرش را فراخوانی کنید.
.sp
از این تابع برای بستن اجباری نشست DCC که قبلاً پذیرفته شده یا آغاز شده است استفاده نکنید. به جای آن از \fI\%irc_dcc_destroy()\fP استفاده نمایید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی موفقیت. مقدار دیگر نشان‌دهنده خطا است و کد خطا از طریق \fI\%irc_errno()\fP قابل دریافت است.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_dcc_sendfile
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_dcc_sendfile(irc_session_t *session, void *ctx, const char *nick, const char *filename, irc_dcc_callback_t callback, irc_dcc_t *dccid) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIctx\fP
T}	T{
بافت تعریف‌شده توسط کاربر که به کال‌بک ارسال می‌شود. می‌تواند NULL باشد
T}
_
T{
\fInick\fP
T}	T{
نام مستعار مقصد
T}
_
T{
\fIfilename\fP
T}	T{
مسیر کامل فایلی که ارسال خواهد شد. باید یک فایل موجود باشد
T}
_
T{
\fIcallback\fP
T}	T{
کال‌بک DCC که برای رویدادهای DCC و گفتگو استفاده خواهد شد
T}
_
T{
\fIdccid\fP
T}	T{
در صورت موفقیت این تابع، شناسه نشست DCC در این فیلد ذخیره می‌شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع یک درخواست DCC SEND برای ارسال فایل ایجاد می‌کند. هنگامی که پذیرفته شد، فایل به طرف مقابل ارسال می‌شود و نشست DCC بسته خواهد شد. پیشرفت و نتیجه عملیات ارسال را می‌توان در کال‌بک بررسی کرد. اطلاعات کال‌بک DCC را ببینید.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 به این معنی است که دستور با موفقیت به سرور ارسال شده است.
.INDENT 0.0
.TP
.B پاسخ‌های خطای احتمالی برای این دستور از RFC 1459:
.INDENT 7.0
.IP \(bu 2
LIBIRC_RFC_ERR_NORECIPIENT
.IP \(bu 2
LIBIRC_RFC_ERR_NOTEXTTOSEND
.IP \(bu 2
LIBIRC_RFC_ERR_CANNOTSENDTOCHAN
.IP \(bu 2
LIBIRC_RFC_ERR_NOTONCHANNEL
.IP \(bu 2
LIBIRC_RFC_ERR_NOTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_WILDTOPLEVEL
.IP \(bu 2
LIBIRC_RFC_ERR_TOOMANYTARGETS
.IP \(bu 2
LIBIRC_RFC_ERR_NOSUCHNICK
.UNINDENT
.UNINDENT
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_dcc_destroy
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_dcc_destroy(irc_session_t *session, irc_dcc_t dccid) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIdccid\fP
T}	T{
شناسه نشست DCC برای نشستی که باید نابود شود
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع اتصال DCC را می‌بندد (در صورت وجود)، و نشست DCC را نابود کرده و منابع استفاده‌شده را آزاد می‌نماید. می‌توان آن را در هر زمانی فراخوانی کرد، حتی از داخل کال‌بک‌ها یا از نخ‌های مختلف.
.sp
توجه داشته باشید که وقتی نشست DCC به پایان برسد (چه با موفقیت و چه با شکست)، نباید آن را دستی نابود کنید؛ این کار به طور خودکار انجام خواهد شد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد بازگشتی 0 یعنی موفقیت. مقدار دیگر نشان‌دهنده خطا است و کد خطا از طریق \fI\%irc_errno()\fP به دست می‌آید.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "مدیریت پیام‌های رنگی (Handling the colored messages)"
.SS irc_color_strip_from_mirc
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B char *irc_color_strip_from_mirc(const char *message) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fImessage\fP
T}	T{
پیام اصلی دارای رنگ
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع تمام کدهای رنگ ANSI را از پیام حذف کرده و یک پیام جدید بدون اطلاعات رنگ بازمی‌گرداند. برای ربات‌هایی که به رشته‌ها واکنش نشان می‌دهند مفید است تا در صورت استفاده رشته از رنگ‌ها دچار سردرگمی نشوند.
.sp
این تابع پیامی را که از رنگ استفاده نکرده تغییر نمی‌دهد.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
پیام جدیدی را با کدهای رنگ حذف‌شده بازمی‌گرداند. توجه داشته باشید که حافظه پیام جدید با ()malloc تخصیص داده می‌شود، بنابراین وقتی دیگر استفاده نمی‌شود باید آن را با ()free آزاد کنید. اگر تخصیص حافظه ناموفق باشد، 0 برمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_color_convert_from_mirc
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B char *irc_color_convert_from_mirc(const char *message) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fImessage\fP
T}	T{
پیام اصلی دارای رنگ
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع تمام کدهای رنگ و گزینه‌های قالب‌بندی را به رنگ‌های داخلی libircclient تبدیل می‌کند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
اشاره‌گری به پیام جدید با کدهای رنگ ANSI و گزینه‌های قالب‌بندی تبدیل‌شده بازمی‌گرداند. برای جزئیات به راهنمای \fI\%irc_color_convert_to_mirc\fP مراجعه کنید.
.sp
توجه داشته باشید که حافظه پیام جدید با ()malloc تخصیص یافته است، بنابراین هنگام پایان استفاده باید آن را با ()free آزاد کنید. در صورت شکست تخصیص حافظه، 0 بازمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_color_convert_to_mirc
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B char *irc_color_convert_to_mirc(const char *message) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fImessage\fP
T}	T{
پیام اصلی دارای رنگ
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع تمام کدهای رنگ و گزینه‌های قالب‌بندی را از رنگ‌های داخلی libircclient به کدهای ANSI مورد استفاده mIRC و سایر کلاینت‌های IRC تبدیل می‌کند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
پیام جدیدی با کدهای رنگ و گزینه‌های قالب‌بندی تبدیل‌شده، یا 0 در صورت عدم امکان تخصیص حافظه برمی‌گرداند. حافظه تخصیص‌یافته با ()malloc باید با ()free آزاد شود.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.sp
سیستم رنگ در libircclient به گونه‌ای طراحی شده که استفاده از آن آسان و بین کلاینت‌های مختلف IRC قابل‌حمل باشد. هر رنگ یا گزینه قالب‌بندی با دستورات متنی ساده داخل براکت توصیف می‌شود.
.INDENT 0.0
.TP
.B کدهای ممکن عبارتند از:
.INDENT 7.0
.IP \(bu 2
[B] ... [/B] \- حالت قالب برجسته (bold). هر متنی بین [B] و [/B] به صورت \fBبرجسته\fP نوشته می‌شود.
.IP \(bu 2
[I] ... [/I] \- حالت قالب مورب/وارونه (italic/reverse). هر متنی بین [I] و [/I] به صورت \fIمورب\fP یا رنگ وارونه نمایش می‌یابد (با توجه به اینکه برخی کلاینت‌ها قادر به رندر متن مورب نیستند، اکثر آن‌ها این را به صورت متن عادی با جابجایی رنگ پس‌زمینه و پیش‌زمینه نشان می‌دهند).
.IP \(bu 2
[U] ... [/U] \- حالت قالب زیرخط‌دار (underline). متن بین [U] و [/U] با زیرخط نوشته می‌شود.
.IP \(bu 2
[COLOR=RED] ... [/COLOR] \- نوشتن متن با استفاده از رنگ پیش‌زمینه مشخص‌شده. رنگ با کلیدواژه COLOR و علامت مساوی همراه با کد رنگ مشخص می‌شود (به زیر نگاه کنید).
.IP \(bu 2
[COLOR=RED/BLUE] ... [/COLOR] \- نوشتن متن با استفاده از رنگ پیش‌زمینه و پس‌زمینه مشخص‌شده. رنگ با کلیدواژه COLOR، علامت مساوی همراه با کد رنگ پیش‌زمینه، یک اسلش و کد رنگ پس‌زمینه تعیین می‌شود.
.UNINDENT
.TP
.B رنگ‌های زیر پشتیبانی می‌شوند:
.INDENT 7.0
.IP \(bu 2
WHITE
.IP \(bu 2
BLACK
.IP \(bu 2
DARKBLUE
.IP \(bu 2
DARKGREEN
.IP \(bu 2
RED
.IP \(bu 2
BROWN
.IP \(bu 2
PURPLE
.IP \(bu 2
OLIVE
.IP \(bu 2
YELLOW
.IP \(bu 2
GREEN
.IP \(bu 2
TEAL
.IP \(bu 2
CYAN
.IP \(bu 2
BLUE
.IP \(bu 2
MAGENTA
.IP \(bu 2
DARKGRAY
.IP \(bu 2
LIGHTGRAY
.UNINDENT
.UNINDENT
.sp
نمونه‌هایی از توالی رنگ‌ها:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Hello, [B]Tim[/B].
[U]Arsenal[/U] got a [COLOR=RED]red card[/COLOR]
The tree[U]s[/U] are [COLOR=GREEN/BLACK]green[/COLOR]
.EE
.UNINDENT
.UNINDENT
.SS "تغییر گزینه‌های کتابخانه (Changing the library options)"
.SS irc_get_version
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_get_version(unsigned int *high, unsigned int *low) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIhigh\fP
T}	T{
شماره نسخه اصلی (high) را ذخیره می‌کند
T}
_
T{
\fIlow\fP
T}	T{
شماره نسخه فرعی (low) را ذخیره می‌کند
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع نسخه libircclient را برمی‌گرداند. می‌توانید از نسخه برای بررسی در دسترس بودن گزینه‌های لازم یا نمایش نسخه استفاده کنید. رشته فرمت توصیه‌شده شبیه printf برای چاپ نسخه به این صورت است:
.sp
\fBprintf (\(dqVersion: %d.%02d\(dq, high, low);\fP
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_set_ctx
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_set_ctx(irc_session_t *session, void *ctx) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIctx\fP
T}	T{
بافت تعریف‌شده توسط کاربر
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع بافت تعریف‌شده توسط کاربر را برای این نشست IRC تنظیم می‌کند. این بافت توسط libircclient استفاده نمی‌شود. هدف آن ذخیره داده‌های کاربری ویژه نشست است که ممکن است بعداً با فراخوانی \fI\%irc_get_ctx\fP به دست آید. توجه داشته باشید که libircclient فقط این اشاره‌گر را حمل می‌کند. اگر حافظه‌ای تخصیص دهید و نشانی آن را در ctx ذخیره کنید، مسئولیت آزادسازی آن قبل از فراخوانی \fI\%irc_destroy_session()\fP با خود شما است.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_get_ctx
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void *irc_get_ctx(irc_session_t *session) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع بافت نشست IRC را که توسط \fI\%irc_set_ctx\fP تنظیم شده بود برمی‌گرداند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
اگر بافتی تنظیم نشده باشد، این تابع NULL برمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_option_set
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_option_set(irc_session_t *session, unsigned int option) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIoption\fP
T}	T{
یکی از \X'tty: link #api-options'\fI\%گزینه‌های Libirc\fP\X'tty: link' برای تنظیم
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع گزینه libircclient را تنظیم می‌کند و رفتار کتابخانه را تغییر می‌دهد. برای معنای هر گزینه به فهرست گزینه‌ها مراجعه کنید.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS irc_option_reset
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B void irc_option_reset(irc_session_t *session, unsigned int option) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
_
T{
\fIoption\fP
T}	T{
یکی از \X'tty: link #api-options'\fI\%گزینه‌های Libirc\fP\X'tty: link' برای تنظیم
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع گزینه libircclient را بازنشانی می‌کند و رفتار libircclient را تغییر می‌دهد. برای معنای هر گزینه به فهرست گزینه‌ها مراجعه کنید.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "مدیریت خطاها (Handling the errors)"
.SS irc_errno
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B int irc_errno(irc_session_t *session) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIsession\fP
T}	T{
دستگیره نشست IRC
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع آخرین کد خطای مرتبط با آخرین عملیات این نشست IRC را بازمی‌گرداند. کدهای خطای ممکن در libirc_errors.h تعریف شده‌اند.
.sp
همانند همیشه، قواعد رایج errno اعمال می‌شوند:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
تابع ()irc_errno تنها و تنها باید زمانی فراخوانی شود که تابع فراخوانی‌شده با شکست مواجه شده باشد؛
.IP \(bu 2
تابع ()irc_errno در صورت موفقیت تابع مقدار 0 برنمی‌گرداند؛ در واقع مقدار بازگشتی تعریف‌نشده خواهد بود.
.IP \(bu 2
باید ()irc_errno را بلافاصله پس از شکست تابع و پیش از فراخوانی هر تابع دیگر libircclient صدا بزنید.
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
کد خطا.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود. کد خطای محلی به ازای هر بافت IRC است، نه به ازای هر نخ.
.SS irc_strerror
.sp
\fBپیش‌نمونه (Prototype):\fP
.INDENT 0.0
.TP
.B const char *irc_strerror(int ircerrno) 
.UNINDENT
.sp
\fBپارامترها (Parameters):\fP
.TS
box center;
l|l.
T{
\fIircerrno\fP
T}	T{
کد خطای IRC بازگردانده‌شده توسط \fI\%irc_errno()\fP
T}
.TE
.sp
\fBتوضیحات (Description):\fP
.sp
این تابع نمایش متنی کد خطای داده‌شده را بازمی‌گرداند.
.sp
\fBمقدار بازگشتی (Return value):\fP
.sp
یک رشته داخلی انگلیسی همراه با شرح مختصری از کد خطا بازمی‌گرداند.
.sp
\fBامنیت نخ (Thread safety):\fP
.sp
این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.
.SS "انواع داده (Types)"
.sp
این بخش انواع داده‌های مختلف تعریف‌شده توسط کتابخانه را شرح می‌دهد.
.SS irc_session_t
.INDENT 0.0
.TP
.B typedef struct irc_session_s irc_session_t
.UNINDENT
.sp
دستگیره نشست IRC که با فراخوانی \X'tty: link #c.irc_create_session'\fI\%irc_create_session()\fP\X'tty: link' ایجاد می‌شود. اکثر فراخوانی‌های توابع کتابخانه این دستگیره را به عنوان پارامتر دریافت می‌کنند. می‌توانید به هر تعداد که مایلید دستگیره بسازید. هر دستگیره می‌تواند برای برقراری یک اتصال IRC به سرور IRC به عنوان یک کاربر منفرد استفاده شود.
.sp
هنگامی که دیگر از این دستگیره استفاده نمی‌شود، باید با فراخوانی \X'tty: link #c.irc_destroy_session'\fI\%irc_destroy_session()\fP\X'tty: link' نابود شود.
.SS irc_dcc_session_t
.INDENT 0.0
.TP
.B typedef struct irc_dcc_session_s irc_dcc_session_t
.UNINDENT
.sp
این ساختار یک نشست DCC مورد استفاده در libircclient را شرح می‌دهد. اعضای آن مربوط به بخش‌های داخلی libircclient هستند و نباید مستقیماً استفاده شوند.
.SS irc_dcc_t
.INDENT 0.0
.TP
.B typedef unsigned int irc_dcc_t
.UNINDENT
.sp
این نوع یک شناسه نشست DCC است، که برای شناسایی نشست‌های DCC در فراخوانی‌های بازگشتی و توابع مختلف استفاده می‌شود.
.SS irc_callbacks_t
.INDENT 0.0
.TP
.B typedef struct irc_callbacks_t
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.EX
typedef struct
{
  irc_event_callback_t         event_connect;
  irc_event_callback_t         event_nick;
  irc_event_callback_t         event_quit;
  irc_event_callback_t         event_join;
  irc_event_callback_t         event_part;
  irc_event_callback_t         event_mode;
  irc_event_callback_t         event_umode;
  irc_event_callback_t         event_topic;
  irc_event_callback_t         event_kick;
  irc_event_callback_t         event_channel;
  irc_event_callback_t         event_privmsg;
  irc_event_callback_t         event_notice;
  irc_event_callback_t         event_channel_notice;
  irc_event_callback_t         event_invite;
  irc_event_callback_t         event_ctcp_req;
  irc_event_callback_t         event_ctcp_rep;
  irc_event_callback_t         event_ctcp_action;
  irc_event_callback_t         event_unknown;
  irc_eventcode_callback_t     event_numeric;
  irc_event_dcc_chat_t         event_dcc_chat_req;
  irc_event_dcc_send_t         event_dcc_send_req;
}
.EE
.UNINDENT
.UNINDENT
.sp
ساختار فراخوانی‌های بازگشتی رویداد را توصیف می‌کند که در ثبت کال‌بک‌ها استفاده می‌شود.
.sp
تمام ارتباطات با شبکه IRC مبتنی بر رویدادها است. به طور کلی رویداد هر چیزی است که توسط فرد دیگری در شبکه یا توسط خود سرور IRC تولید می‌شود. «شخصی پیامی برای شما می‌فرستد»، «شخصی به کانال پیوست»، «شخصی از IRC خارج شد» - همه این پیام‌ها رویداد هستند.
.sp
هر رویداد دارای گرداننده اختصاصی خود است که هنگام دریافت رویداد مناسب فراخوانی می‌شود. شما مجبور نیستید تمام گرداننده‌های رویداد را تعریف کنید؛ فقط گرداننده‌هایی را تعریف کنید که باید آن‌ها را شنود کنید و اشاره‌گر گرداننده‌های باقی‌مانده را روی NULL قرار دهید.
.INDENT 0.0
.TP
.B event_connect
.UNINDENT
.sp
این رویداد زمانی فعال می‌شود که اتصال به سرور IRC با موفقیت برقرار شده و پیام روز (MOTD) دریافت شود. بسته به سرور، ممکن است ارسال دستورات قبل از این رویداد نیز امکان‌پذیر باشد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
استفاده‌نشده، تنظیم روی NULL
T}
_
T{
\fIparams\fP
T}	T{
استفاده‌نشده، تنظیم روی NULL
T}
.TE
.INDENT 0.0
.TP
.B event_nick
.UNINDENT
.sp
این رویداد پس از دریافت پیام NICK رخ می‌دهد. زمانی اتفاق می‌افتد که یکی از کاربران (از جمله خود شما) در یکی از کانال‌هایی که نظارت می‌کنید (پیوسته‌اید) نام مستعار خود را تغییر دهد.
.sp
تغییر نام مستعار خودتان نیز این رویداد را تولید می‌کند. توجه داشته باشید که ممکن است سرور نام مستعار شما را به طور مستقل تغییر دهد، بنابراین باید این رویداد را دنبال کنید.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
نام مستعار اصلی (ممکن است مال شما باشد!)
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام مستعار جدید است.
T}
.TE
.INDENT 0.0
.TP
.B event_quit
.UNINDENT
.sp
این رویداد پس از دریافت پیام QUIT فعال می‌شود. زمانی رخ می‌دهد که یکی از کاربران در یکی از کانال‌هایی که در آن حضور دارید از سرور IRC قطع اتصال کند.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که ارتباطش قطع شد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] اختیاری است و شامل دلیل خروج تعیین‌شده توسط کاربر است
T}
.TE
.INDENT 0.0
.TP
.B event_join
.UNINDENT
.sp
این رویداد با دریافت پیام JOIN فعال می‌شود. زمانی رخ می‌دهد که کاربر جدیدی به کانالی که نظارت می‌کنید (پیوسته‌اید) ملحق شود. همچنین زمانی که خودتان به کانال جدیدی بپیوندید نیز رخ می‌دهد.
.sp
توجه داشته باشید که ممکن است شما بدون ارسال دستور JOIN مجبور به پیوستن به کانال شوید (و در نتیجه این رویداد را دریافت کنید). یک حالت متداول زمانی است که ربات NickServ روی سرور طوری پیکربندی شده که شما را به صورت خودکار به کانال‌های خاصی ملحق کند.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که به کانال پیوست (ممکن است خود شما باشید!)
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
T}
.TE
.INDENT 0.0
.TP
.B event_part
.UNINDENT
.sp
این رویداد پس از دریافت پیام PART فعال می‌شود. زمانی رخ می‌دهد که کاربری کانالی را که در آن حضور دارید ترک کند. همچنین وقتی خودتان کانالی را ترک کنید رخ می‌دهد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که کانال را ترک کرد (ممکن است خود شما باشید!)
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] اختیاری است و دلیل تعیین‌شده توسط کاربر را در بر دارد
T}
.TE
.INDENT 0.0
.TP
.B event_mode
.UNINDENT
.sp
این رویداد پس از دریافت پیام MODE کانال فعال می‌شود. زمانی رخ می‌دهد که شخصی حالت(های) کانالی را که در آن حضور دارید تغییر دهد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که تغییر را انجام داد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] شامل تغییرات حالت کانال است، مانند "t+" یا "i\-"
مقدار params[2] اختیاری است و آرگومان حالت کانال را در بر دارد (مثلاً یک نام مستعار برای حالت o+)
T}
.TE
.INDENT 0.0
.TP
.B event_umode
.UNINDENT
.sp
این رویداد با دریافت پیام MODE کاربر فعال می‌شود. زمانی رخ می‌دهد که حالت کاربری شما تغییر کند.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که تغییر را انجام داد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] شامل تغییرات حالت کاربر است، مانند "t+" یا "i\-"
T}
.TE
.INDENT 0.0
.TP
.B event_topic
.UNINDENT
.sp
این رویداد با دریافت پیام TOPIC فعال می‌شود. زمانی رخ می‌دهد که شخصی موضوع کانالی را که در آن حضور دارید تغییر دهد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که تغییر را انجام داد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] اختیاری است و موضوع جدید را در بر دارد
T}
.TE
.INDENT 0.0
.TP
.B event_kick
.UNINDENT
.sp
این رویداد پس از دریافت پیام KICK فعال می‌شود. زمانی رخ می‌دهد که شخصی (از جمله شما) فردی را (از جمله خود شما) از کانالی که در آن عضو هستید اخراج کند. اخراج کردن خودتان از کانال نیز امکان‌پذیر است.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که اقدام را انجام داد (ممکن است خود شما باشید)
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] اختیاری است و نام مستعار فرد اخراج‌شده را در بر دارد
مقدار params[2] اختیاری است و دلیل اخراج را شامل می‌شود
T}
.TE
.INDENT 0.0
.TP
.B event_channel
.UNINDENT
.sp
این رویداد با دریافت پیام PRIVMSG ارسال‌شده به کانال رخ می‌دهد. زمانی فعال می‌شود که شخصی (به جز شما) پیامی به کانال مورد نظارت ارسال کند.
.sp
پیام‌های خودتان این رویداد را فعال نمی‌کنند. با این حال سرور می‌تواند با تولید این رویداد شما را مجبور به ارسال پیام به کانال کند.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را ارسال کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] اختیاری است و متن پیام را شامل می‌شود
T}
.TE
.INDENT 0.0
.TP
.B event_privmsg
.UNINDENT
.sp
این رویداد با دریافت یک پیام PRIVMSG ارسال‌شده به صورت خصوصی برای شما رخ می‌دهد. زمانی فعال می‌شود که کسی برای شما پیام فرستاده باشد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را ارسال کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام مستعار شما است
مقدار params[1] اختیاری است و متن پیام را شامل می‌شود
T}
.TE
.INDENT 0.0
.TP
.B event_notice
.UNINDENT
.sp
این رویداد پس از دریافت پیام NOTICE فعال می‌شود. این پیام مشابه PRIVMSG است. طبق RFC 1459، تنها تفاوت میان NOTICE و PRIVMSG این است که شما هرگز نباید به طور خودکار به پیام‌های NOTICE پاسخ دهید. متأسفانه این قاعده اغلب توسط خود سرورهای IRC نقض می‌شود - برای مثال، پیام‌های NICKSERV نیازمند پاسخ هستند و به عنوان NOTICE ارسال می‌شوند.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را ارسال کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام مستعار مقصد است
مقدار params[1] اختیاری است و متن پیام را در بر دارد
T}
.TE
.INDENT 0.0
.TP
.B event_channel_notice
.UNINDENT
.sp
این رویداد با دریافت پیام NOTICE ارسال‌شده به کانال رخ می‌دهد. این پیام مشابه PRIVMSG کانال است. طبق RFC 1459 نباید به طور خودکار به پیام‌های NOTICE پاسخ داد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را ارسال کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام کانال است
مقدار params[1] اختیاری است و متن پیام را شامل می‌شود
T}
.TE
.INDENT 0.0
.TP
.B event_invite
.UNINDENT
.sp
این رویداد با دریافت پیام INVITE فعال می‌شود. زمانی رخ می‌دهد که شخصی شما را به کانالی با حالت i+ (فقط‌دعوتی) دعوت کند.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که شما را دعوت کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل نام مستعار شما است
مقدار params[1] اختیاری است و نام کانال را در بر دارد
T}
.TE
.sp
همچنین ببینید: \X'tty: link #c.irc_cmd_invite'\fI\%irc_cmd_invite()\fP\X'tty: link'
.INDENT 0.0
.TP
.B event_ctcp_req
.UNINDENT
.sp
این رویداد پس از دریافت یک درخواست CTCP فعال می‌شود. به طور پیش‌فرض از گرداننده داخلی درخواست CTCP استفاده می‌گردد. کلاینت mIRC پیام‌های \fIPING\fP، \fIFINGER\fP، \fIVERSION\fP، \fITIME\fP و \fIACTION\fP را تولید می‌کند که در صورت عدم مدیریت این رویداد توسط برنامه شما، به طور خودکار توسط کتابخانه مدیریت و پاسخ داده می‌شوند؛ به جز پیام ACTION که رویداد event_ctcp_action را فعال می‌کند.
اگر نیاز به مدیریت انواع بیشتری از پیام‌ها دارید، این گرداننده رویداد را تعریف کنید و کد مبدأ تابع \fBlibirc_event_ctcp_internal\fP را برای نحوه نوشتن گرداننده اختصاصی بررسی نمایید. حداقل باید از CTCP PING پشتیبانی کنید تا بررسی جعل هویت برخی سرورهای IRC را پشت سر بگذارید.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را تولید کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل پیام کامل CTCP است
T}
.TE
.INDENT 0.0
.TP
.B event_ctcp_rep
.UNINDENT
.sp
این رویداد پس از دریافت پاسخ CTCP فعال می‌شود. بنابراین اگر پیام CTCP ارسال کنید و کاربر دوردست پاسخ دهد، این گرداننده رویداد فراخوانی خواهد شد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را تولید کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل پیام کامل CTCP است
T}
.TE
.INDENT 0.0
.TP
.B event_ctcp_action
.UNINDENT
.sp
این رویداد پس از دریافت پیام کنش CTCP ACTION فعال می‌شود. تنها زمانی فراخوانی می‌شود که گرداننده رویداد event_ctcp_req را تعریف نکرده باشید.
.sp
چنین پیام‌هایی معمولاً در کلاینت IRC به این شکل دیده می‌شوند:
.INDENT 0.0
.TP
.B ::
[08:32:55] * Michael is having fun
[08:32:55] * Bobby\(aqs getting jealous
.UNINDENT
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که پیام را تولید کرد
T}
_
T{
\fIparams\fP
T}	T{
مقدار params[0] شامل محتوای پیام ACTION است
T}
.TE
.INDENT 0.0
.TP
.B event_unknown
.UNINDENT
.sp
این رویداد با دریافت یک پیام ناشناخته که توسط کتابخانه مدیریت نمی‌شود فعال می‌گردد.
.sp
این رویداد از کال‌بک \fBirc_event_callback_t\fP با مقادیر زیر استفاده می‌کند:
.TS
box center;
l|l.
T{
\fIorigin\fP
T}	T{
کاربری که رویداد را تولید کرد
T}
_
T{
\fIparams\fP
T}	T{
صفر یا چند پارامتر ارائه‌شده با این رویداد
T}
.TE
.INDENT 0.0
.TP
.B event_numeric
.UNINDENT
.sp
این رویداد پس از دریافت هر پیام عددی از سرور فعال می‌شود. فهرست ناقصی از این پاسخ‌ها در RFC 1459 یافت می‌شود. مدیریت این رویداد برای هر کلاینت معناداری ضروری است.
.sp
این رویداد از کال‌بک اختصاصی irc_eventcode_callback_t استفاده می‌کند. مستندات کال‌بک را ببینید.
.INDENT 0.0
.TP
.B event_dcc_chat_req
.UNINDENT
.sp
این رویداد زمانی که شخصی تلاش کند گفتگوی DCC CHAT با شما برقرار کند فعال می‌شود.
.sp
این رویداد از کال‌بک اختصاصی \fBirc_event_dcc_chat_t\fP استفاده می‌کند. مستندات کال‌بک را ببینید.
.INDENT 0.0
.TP
.B event_dcc_send_req
.UNINDENT
.sp
این رویداد زمانی فعال می‌شود که شخصی تلاش کند فایلی را از طریق DCC SEND برای شما بفرستد.
.sp
این رویداد از کال‌بک اختصاصی \fBirc_event_dcc_send_t\fP استفاده می‌کند. مستندات کال‌بک را ببینید.
.SS "ثوابت (Constants)"
.sp
این بخش ثوابت کتابخانه مانند گزینه‌ها و کدهای خطا را شرح می‌دهد.
.SS "خطاها (Errors)"
.INDENT 0.0
.TP
.B LIBIRC_ERR_OK 
.UNINDENT
.sp
(0): بدون خطا
.INDENT 0.0
.TP
.B LIBIRC_ERR_INVAL 
.UNINDENT
.sp
(1): مقدار نامعتبر برای یکی از آرگومان‌های یک تابع داده شده است. به عنوان مثال، ارسال مقدار NULL به عنوان آرگومان کانال در \X'tty: link #c.irc_cmd_join'\fI\%irc_cmd_join()\fP\X'tty: link' این خطا را تولید می‌کند.
.INDENT 0.0
.TP
.B LIBIRC_ERR_RESOLV 
.UNINDENT
.sp
(2): نام میزبان ارائه‌شده برای تابع \X'tty: link #c.irc_connect'\fI\%irc_connect()\fP\X'tty: link' نتوانست به یک نشانی IP معتبر تفکیک شود.
.INDENT 0.0
.TP
.B LIBIRC_ERR_SOCKET 
.UNINDENT
.sp
(3): سوکت جدید نمی‌تواند ایجاد شود یا به حالت غیرمسدودکننده درآید. معمولاً به این معنی است که سرور با کمبود منابع مواجه شده یا اشکالی در libircclient وجود دارد. همچنین ببینید: \X'tty: link #faq-err-socket'\fI\%چرا در Win32 هنگام استفاده از کتابخانه ایستا خطای LIBIRC_ERR_SOCKET دریافت می‌کنم؟\fP\X'tty: link'
.INDENT 0.0
.TP
.B LIBIRC_ERR_CONNECT 
.UNINDENT
.sp
(4): سوکت نتوانست به سرور IRC یا بخش مقصد DCC متصل شود. معمولاً یعنی سرور IRC از کار افتاده یا نشانی آن نامعتبر است. برای DCC دلیل معمولاً فایروال رایانه شما یا رایانه مقصد است که انتقال DCC را رد می‌کند.
.INDENT 0.0
.TP
.B LIBIRC_ERR_CLOSED 
.UNINDENT
.sp
(5): اتصال IRC توسط سرور IRC بسته شد (که می‌تواند به این معنی باشد که یک اپراتور IRC شما را از سرور اخراج کرده است)، یا اتصال DCC توسط طرف مقابل بسته شد. معمولاً این مورد یک خطای فنی نیست.
.INDENT 0.0
.TP
.B LIBIRC_ERR_NOMEM 
.UNINDENT
.sp
(6): دو دلیل ممکن برای این خطا وجود دارد: اول اینکه حافظه برای استفاده داخلی libircclient تخصیص نیافت، و این خطا معمولاً مهلک است. دلیل دوم این است که بافر دستورات (که دستورات آماده ارسال به سرور IRC را صف‌بندی می‌کند) پر است و هنوز نمی‌تواند دستورات بیشتری را بپذیرد. در مورد اخیر باید کمی صبر کنید و دستور را بعداً تکرار نمایید.
.INDENT 0.0
.TP
.B LIBIRC_ERR_ACCEPT 
.UNINDENT
.sp
(7): اتصال گفتگوی/ارسال DCC از طرف مقابل نتوانست پذیرفته شود. یا اتصال قبل از پذیرش قطع شده یا اشکالی در libircclient وجود دارد.
.INDENT 0.0
.TP
.B LIBIRC_ERR_NODCCSEND 
.UNINDENT
.sp
(9): نام فایل ارائه‌شده به \X'tty: link #c.irc_dcc_sendfile'\fI\%irc_dcc_sendfile()\fP\X'tty: link' نتوانست ارسال شود. یا یک فایل معمولی نیست (مثلاً یک دایرکتوری یا یک سوکت است) یا قابل خواندن نبوده است. همچنین ببینید: \fI\%LIBIRC_ERR_OPENFILE\fP
.INDENT 0.0
.TP
.B LIBIRC_ERR_READ 
.UNINDENT
.sp
(10): یا فایل DCC قابل خواندن نبود (مثلاً در حین ارسال کوتاه شد)، یا سوکت DCC خطای خواندن برگرداند که معمولاً به این معنی است که اتصال شبکه قطع شده است.
.INDENT 0.0
.TP
.B LIBIRC_ERR_WRITE 
.UNINDENT
.sp
(11): یا فایل DCC نتوانست نوشته شود (مثلاً فضای خالی روی دیسک وجود ندارد)، یا سوکت DCC خطای نوشتن برگرداند که نشان‌دهنده قطع اتصال شبکه است.
.INDENT 0.0
.TP
.B LIBIRC_ERR_STATE 
.UNINDENT
.sp
(12): تابع در زمانی فراخوانی شده که مجاز به فراخوانی نبوده است. به عنوان مثال، \X'tty: link #c.irc_cmd_join'\fI\%irc_cmd_join()\fP\X'tty: link' پیش از برقراری اتصال به سرور IRC و قبل از فراخوانی \fBevent_connect\fP صدا زده شده است.
.INDENT 0.0
.TP
.B LIBIRC_ERR_TIMEOUT 
.UNINDENT
.sp
(13): مهلت زمانی درخواست DCC به پایان رسید. تایمری برای هر درخواست DCC وجود دارد که اتصال، پذیرش و درخواست‌های پذیرفته‌نشده/رد‌شده DCC را ردیابی می‌کند. این تایمر روی ۶۰ ثانیه تنظیم شده است. اگر درخواست در این مدت متصل، پذیرفته یا رد نشود، با این خطا متوقف خواهد شد.
.INDENT 0.0
.TP
.B LIBIRC_ERR_OPENFILE 
.UNINDENT
.sp
(14): فایل مشخص‌شده در \X'tty: link #c.irc_dcc_sendfile'\fI\%irc_dcc_sendfile()\fP\X'tty: link' باز نشد.
.INDENT 0.0
.TP
.B LIBIRC_ERR_TERMINATED 
.UNINDENT
.sp
(15): اتصال به سرور IRC قطع شد.
.INDENT 0.0
.TP
.B LIBIRC_ERR_NOIPV6 
.UNINDENT
.sp
(16): تابعی که نیازمند پشتیبانی IPv6 است فراخوانی شد، اما پشتیبانی IPv6 در برنامه کامپایل نشده است.
.INDENT 0.0
.TP
.B LIBIRC_ERR_SSL_NOT_SUPPORTED 
.UNINDENT
.sp
(17): اتصال SSL نیاز بود اما کتابخانه با پشتیبانی از SSL کامپایل نشده است.
.INDENT 0.0
.TP
.B LIBIRC_ERR_SSL_INIT_FAILED 
.UNINDENT
.sp
(18): کتابخانه SSL نتوانست مقداردهی اولیه شود.
.INDENT 0.0
.TP
.B LIBIRC_ERR_CONNECT_SSL_FAILED 
.UNINDENT
.sp
(19): دست‌تکانی SSL هنگام تلاش برای اتصال به سرور با شکست مواجه شد. معمولاً به این معنی است که شما سعی در استفاده از SSL روی یک پورت غیر SSL دارید.
.INDENT 0.0
.TP
.B LIBIRC_ERR_SSL_CERT_VERIFY_FAILED 
.UNINDENT
.sp
(20): سرور از یک گواهینامه نامعتبر یا خودامضا استفاده می‌کند. از گزینه \fI\%LIBIRC_OPTION_SSL_NO_VERIFY\fP برای اتصال به آن استفاده کنید.
.SS "گزینه‌ها (Options)"
.INDENT 0.0
.TP
.B LIBIRC_OPTION_DEBUG 
.UNINDENT
.sp
در صورت تنظیم، خروجی‌های اضافی اشکال‌زدایی را فعال می‌کند که به STDOUT فرستاده می‌شوند.
.INDENT 0.0
.TP
.B LIBIRC_OPTION_STRIPNICKS 
.UNINDENT
.sp
در صورت تنظیم، مبدأ رویدادها را به طور خودکار پیراسته می‌کند. هر رویداد دارای یک مبدأ است که معمولاً به صورت \fInick!host@ircserver\fP است. این مبدأها نمی‌توانند در دستورات IRC استفاده شوند و باید بخش میزبان و سرور جدا شود. این کار با فعال کردن این گزینه به طور خودکار انجام می‌گیرد.
.INDENT 0.0
.TP
.B LIBIRC_OPTION_SSL_NO_VERIFY 
.UNINDENT
.sp
به طور پیش‌فرض اتصال SSL با بررسی اینکه گواهینامه ارائه‌شده توسط یک مرجع صدور گواهی معتبر امضا شده باشد احراز هویت می‌شود. از آنجا که این موارد هزینه دارد، برخی سرورهای IRC از گواهینامه‌های خودامضا استفاده می‌کنند. این گزینه در صورت تنظیم، بررسی گواهینامه را غیرفعال می‌کند و کتابخانه هر گواهینامه‌ای را خواهد پذیرفت.
.sp
این گزینه باید پیش از فراخوانی تابع \X'tty: link #c.irc_connect'\fI\%irc_connect\fP\X'tty: link' تنظیم شود.
.SH "پیوست (APPENDIX)"
.SS "پرسش‌های متداول (Frequently asked questions)"
.SS "چرا در Win32 هنگام استفاده از کتابخانه ایستا خطای LIBIRC_ERR_SOCKET دریافت می‌کنم؟"
.sp
زیرا در Win32 باید قبل از استفاده، رابط Winsock API را مقداردهی اولیه کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
WSADATA wsaData;

if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
    // گزارش خطا

// اکنون می‌توانید از libircclient استفاده کنید
.EE
.UNINDENT
.UNINDENT
.sp
شما باید این کار را فقط یک بار در برنامه خود انجام دهید، و از آنجا که libircclient نمی‌داند آیا قبلاً آن را مقداردهی کرده‌اید یا خیر، شامل هیچ کد مقداردهی اولیه Winsock نیست.
.SS "اینکه می‌گویند پروتکل IRC مبتنی بر رویداد است به چه معناست؟"
.sp
خود پروتکل IRC ناهمگام و هدایت‌شده توسط سرور است. برای شما، این به معنای موارد زیر است:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
برای هر دستور IRC، دریافت پاسخ فوری مبنی بر موفقیت یا شکست دستور امکان‌پذیر نیست. در عوض، سرور پاسخ را در بازه زمانی کوتاه (یا طولانی) ارسال خواهد کرد.
.IP \(bu 2
برای برخی از دستورات IRC اصلاً پاسخ «موفقیت» وجود ندارد. به عنوان مثال، وقتی پیامی متنی می‌فرستید، سرور IRC پاسخی برای تایید ارسال پیام نخواهد فرستاد.
.IP \(bu 2
می‌توانید چندین دستور را به سرور IRC ارسال کنید، و سپس پاسخ‌های متعددی را در مورد هر دستور دریافت کنید. ترتیب پاسخ‌هایی که دریافت می‌کنید به طور کلی نامشخص است.
.IP \(bu 2
بسیاری از رویدادهای IRC ارسالی برای شما توسط کاربران دیگر یا خود سرور IRC تولید می‌شوند و دقیقاً در زمان تولید برای شما فرستاده می‌شوند.
.IP \(bu 2
فهرست‌های طولانی (به عنوان مثال، فهرست کانال‌ها) نیز به عنوان رویداد ارسال می‌شوند. علاوه بر این، این رویدادها می‌توانند توسط رویدادهای دیگر (پیام‌ها یا اعلان‌ها) از هم جدا شوند. وظیفه شماست که داده‌ها را (با استفاده از کدهای رویداد) تفکیک کنید و از نوعی ساختار داده برای نگهداری آن تا زمان تکمیل داده‌ها استفاده نمایید. امکان پرس‌وجوی ساده فهرست کانال‌ها و انتظار دریافت فوری تمام محتوای آن وجود ندارد.
.IP \(bu 2
ممکن است درخواستی ارسال کنید و در صورت موفقیت پاسخی دریافت نکنید (مانند ارسال پیام). ممکن است درخواستی ارسال کنید و موفقیت آن تنها زمانی تایید شود که پاسخی دریافت کنید (که ممکن است پس از دریافت ده رویداد نامرتبط دیگر باشد). یا می‌توانید حتی بدون ارسال هیچ درخواستی پاسخی دریافت کنید، مانند مورد JOIN - این امکان وجود دارد که سرور شما را به طور ضمنی وارد یک کانال خاص کند.
.IP \(bu 2
شما باید برای رویدادهای غیرمنتظره از سوی سرور IRC آماده باشید. برای مثال سرور می‌تواند نام مستعار شما را تغییر دهد (که در اکثر سرورهای با احراز هویت nickserv دیده می‌شود). ممکن است شما «مجبور» به ورود به کانال، گفتن چیزی، خروج از کانال، تغییر حالت کاربری و غیره شوید. به آنچه سرور IRC به شما می‌گوید گوش فرا دهید و عمل کنید.
.UNINDENT
.UNINDENT
.UNINDENT
.SS "چرا تابع irc_cmd_join خطا برنمی‌گرداند؟"
.sp
یک نمونه معمولی این است که فراخوانی \X'tty: link #c.irc_cmd_join'\fI\%irc_cmd_join()\fP\X'tty: link' همیشه موفقیت برمی‌گرداند حتی زمانی که تلاش می‌کنید به یک کانال دارای گذرواژه ملحق شوید. سپس مدتی بعد سرور IRC خطا را بازمی‌گرداند. این به این دلیل است که توابع خانواده _irc_cmd زمانی موفقیت را بازمی‌گردانند که دستور با موفقیت به سرور IRC فرستاده شود. ماهیت ناهمگام پروتکل IRC دریافت فوری نتیجه دستور را غیرممکن می‌سازد. لطفاً پرسش بالا را مطالعه کنید.
.SS "چگونه با NICKSERV ثبت‌نام یا احراز هویت کنیم؟"
.sp
هیچ روش «استانداردی» وجود ندارد. سرویس‌های NICKSERV، CHANSERV و موارد مشابه در RFC مشخص نشده‌اند. آن‌ها افزونه‌های IRC هستند که دقیقاً مانند سایر کاربران IRC رفتار می‌کنند اما اختیارات بیشتری دارند. معمولاً پیام‌های آن‌ها از طریق رویدادهای Notice ارسال می‌شود، بنابراین می‌توانید از الگوریتم زیر برای مدیریت ثبت‌نام در Nickserv استفاده کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
static void event_notice (irc_session_t * session, const char * event,
                                                 const char * origin, const char ** params, unsigned int count)
{
        char buf[256];

        if ( !origin )
                return;

        if ( strcasecmp (origin, \(dqnickserv\(dq) )
                return;

        if ( strstr (params[1], \(dqThis nick is not registered\(dq) == params[1] )
        {
                sprintf (buf, \(dqREGISTER %s NOMAIL\(dq, gCfg.irc_nickserv_password);
                irc_cmd_msg(session, \(dqnickserv\(dq, buf);
        }
        else if ( strstr (params[1], \(dqThis nickname is registered and protected\(dq) == params[1] )
        {
                sprintf (buf, \(dqIDENTIFY %s\(dq, gCfg.irc_nickserv_password);
                irc_cmd_msg(session, \(dqnickserv\(dq, buf);
        }
        else if ( strstr (params[1], \(dqPassword accepted \- you are now recognized\(dq) == params[1] )
                printf (\(dqNickserv authentication succeed.\(dq);
}
.EE
.UNINDENT
.UNINDENT
.sp
ایده اصلی، تجزیه پیام‌های ارسال‌شده از NICKSERV و واکنش مناسب به الگوهای خاص در صورت تطابق است.
.SS "پروتکل CTCP چیست؟"
.sp
مخفف CTCP به عنوان "Client\-to\-Client Protocol" (پروتکل کارخواه به کارخواه) شناخته می‌شود. این پروتکل بین کلاینت‌های IRC برای استعلام داده‌ها از کلاینت راه دور، یا ارسال برخی اطلاعات استفاده می‌شود - به عنوان مثال، پیام‌های me/ از طریق CTCP ارسال می‌شوند.
.sp
هیچ فهرست استانداردی از درخواست‌های ممکن CTCP وجود ندارد و کلاینت‌های مختلف IRC اغلب کدهای CTCP اختصاصی خود را اضافه می‌کنند. گرداننده داخلی به پرس‌وجوهای CTCP با عنوان‌های TIME، VERSION، PING و FINGER واکنش نشان می‌دهد. اگر نیاز به واکنش به درخواست‌های دیگر دارید، باید گرداننده CTCP اختصاصی خود را بنویسید. کد منبع تابع libirc_event_ctcp_internal را بررسی کنید تا نحوه نوشتن آن را متوجه شوید.
.SS "چرا وقتی اپراتور کانال (+o) می‌شوم، event_umode را دریافت نمی‌کنم؟"
.sp
تبدیل شدن به یک اپراتور کانال، \fBحالت کانال (channel mode)\fP را تغییر می‌دهد نه حالت کاربر را. بنابراین شما رویداد \fBevent_mode\fP را دریافت خواهید کرد نه \fBevent_umode\fP\&.
.sp
اگر رویداد event_umode را با o+ دریافت کنید، به این معنی است که حساب کاربری شما یک اپراتور سرور IRC است.
.SS "اگر برنامه من از epoll استفاده کند چه؟"
.sp
این کتابخانه به دلایل تاریخی فقط مستقیماً از حلقه‌های مبتنی بر ()select پشتیبانی می‌کند، بنابراین epoll و سایر روش‌های نظرسنجی مستقیماً توسط کتابخانه پشتیبانی نمی‌شوند. اما در صورت لزوم، می‌توان آن را با تبدیل توصیف‌کننده‌ها میان select و epoll به صورت زیر شبیه‌سازی کرد:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP \(bu 2
فراخوانی irc_add_select_descriptors با یک FD_SET خالی
.IP \(bu 2
استخراج توصیف‌کننده‌ها از آرایه‌های fd_set (به یاد داشته باشید fd_set یک آرایه بیتی است نه آرایه مقادیر عددی ساده). در صورت وجود نشست‌های DCC ممکن است بیش از یک توصیف‌کننده وجود داشته باشد.
.IP \(bu 2
ارسال آن توصیف‌کننده‌ها به poll/epoll با استفاده از رویدادهای مربوطه (یعنی استفاده از EPOLLIN برای توصیف‌کننده‌های موجود در \fIin_set\fP)
.IP \(bu 2
برای آن دسته از توصیف‌کننده‌هایی که رویدادها را برانگیخته‌اند، ساختارهای مربوط به in_set و out_set را پر کنید (دوباره ماسک‌های بیتی را به خاطر بسپارید!) و آن‌ها را به \X'tty: link #c.irc_process_select_descriptors'\fI\%irc_process_select_descriptors()\fP\X'tty: link' بفرستید
.UNINDENT
.UNINDENT
.UNINDENT
.sp
اگرچه این کار تا حدی دشوار است، اما عملیات بسیار ساده هستند (اساساً عملیات ماسک بیتی روی یک ساختار کوچک) و هیچ افت سرعت چشمگیری به برنامه شما اضافه نخواهند کرد.
.SS "مجوز عمومی همگانی گنو کمتر جامع (GNU LESSER GENERAL PUBLIC LICENSE)"
.sp
نسخه ۳، ۲۹ ژوئن ۲۰۰۷
.sp
حق نشر © ۲۰۰۷ بنیاد نرم‌افزار آزاد، <\X'tty: link http://fsf.org'\fI\%http://fsf.org\fP\X'tty: link'>
.sp
کپی و توزیع نسخه‌های عین کلمه این سند مجوز برای همگان مجاز است، اما تغییر آن مجاز نمی‌باشد.
.sp
این نسخه از مجوز عمومی همگانی گنو کمتر جامع، شرایط و ضوابط نسخه ۳ مجوز عمومی همگانی گنو (GNU GPL) را به همراه مجوزهای اضافی ذکرشده در زیر در بر می‌گیرد.
.INDENT 0.0
.IP 0. 4
تعاریف تکمیلی.
.UNINDENT
.sp
اصطلاح «این مجوز» به نسخه ۳ مجوز عمومی همگانی گنو کمتر جامع، و «GNU GPL» به نسخه ۳ مجوز عمومی همگانی گنو اشاره دارد.
.sp
«کتابخانه» به اثر تحت پوشش این مجوز اشاره دارد، به جز برنامه‌ها یا آثار ترکیبی طبق تعاریف زیر.
.sp
یک «برنامه» هر اثری است که از رابط ارائه‌شده توسط کتابخانه استفاده می‌کند اما بر پایه کتابخانه بنا نشده باشد. تعریف یک زیرکلاس از کلاسی که توسط کتابخانه تعریف شده حالتی از استفاده از رابط تلقی می‌شود.
.sp
یک «اثر ترکیبی» اثری است که از ترکیب یا پیوند دادن یک برنامه با کتابخانه تولید شده باشد. نسخه خاصی از کتابخانه که اثر ترکیبی با آن ایجاد شده «نسخه پیوند‌یافته» نامیده می‌شود.
.sp
«سورس حداقلی متناظر» برای یک اثر ترکیبی به معنای سورس متناظر برای اثر ترکیبی است، به استثنای هرگونه کد منبع برای بخش‌هایی از اثر ترکیبی که به صورت مجزا بر پایه برنامه باشند نه بر پایه نسخه پیوندیافته.
.sp
«کد متناظر برنامه» برای اثر ترکیبی به معنی کد شیء و/یا کد منبع برنامه است، شامل تمام داده‌ها و برنامه‌های کمکی لازم برای بازتولید اثر ترکیبی از برنامه، اما بدون احتساب کتابخانه‌های سیستمی اثر ترکیبی.
.IP 1. 3
استثنای بخش ۳ از GNU GPL.
.sp
شما می‌توانید یک اثر تحت پوشش را تحت بخش‌های ۳ و ۴ این مجوز بدون پایبندی به بخش ۳ از GNU GPL منتقل کنید.
.IP 2. 3
انتقال نسخه‌های تغییریافته.
.sp
اگر نسخه‌ای از کتابخانه را تغییر دهید و در تغییرات شما، یک امکان به تابع یا داده‌ای ارائه‌شده توسط برنامه‌ای که از آن استفاده می‌کند رجوع نماید، می‌توانید نسخه‌ای از نسخه تغییریافته را منتقل کنید:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP a. 3
تحت این مجوز، مشروط بر اینکه تلاشی با حسن نیت انجام دهید تا اطمینان یابید در صورتی که برنامه‌ای تابع یا داده را ارائه نکرد، آن امکان همچنان کار کند، یا
.IP b. 3
تحت GNU GPL، بدون هیچ‌یک از مجوزهای اضافی این مجوز برای آن نسخه.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 3. 3
کد شیء دربردارنده مطالبی از فایل‌های سرآیند کتابخانه.
.UNINDENT
.sp
شکل کد شیء یک برنامه ممکن است مطالبی از فایل سرآیند کتابخانه را در خود جای دهد. شما می‌توانید چنین کد شیئی را تحت شرایط انتخابی خود منتقل کنید، مشروط بر اینکه اگر مطالب وارد شده محدود به پارامترهای عددی، جانمایی ساختار داده و توابع دسترسی، یا ماکروهای کوچک، توابع درون‌خطی و الگوها (ده خط یا کمتر) نباشد، هر دو مورد زیر را رعایت کنید:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP a. 3
همراه با هر نسخه از کد شیء، اطلاعیه برجسته‌ای ارائه دهید که کتابخانه در آن استفاده شده و تحت این مجوز قرار دارد.
.IP b. 3
کد شیء را با نسخه‌ای از GNU GPL و این سند مجوز همراه کنید.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 4. 3
آثار ترکیبی.
.UNINDENT
.sp
شما می‌توانید یک اثر ترکیبی را تحت شرایط انتخابی خود منتقل کنید که مجموعاً تغییری در بخش‌های کتابخانه موجود در اثر ترکیبی و مهندسی معکوس برای اشکال‌زدایی چنین تغییراتی را محدود نکند، مشروط بر اینکه هر یک از موارد زیر را نیز انجام دهید:
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.IP a. 3
همراه هر نسخه از اثر ترکیبی اخطاریه‌ای ارائه دهید که کتابخانه در آن به کار رفته و تحت این مجوز قرار دارد.
.IP b. 3
اثر ترکیبی را با نسخه‌ای از GNU GPL و این سند مجوز همراه سازید.
.IP c. 3
برای یک اثر ترکیبی که در زمان اجرا اخطاریه‌های حق نشر را نمایش می‌دهد، اخطاریه حق نشر کتابخانه را نیز در میان آن‌ها بگنجانید.
.IP d. 3
.INDENT 3.0
.TP
.B یکی از کارهای زیر را انجام دهید:
.INDENT 7.0
.IP 0. 4
سورس حداقلی متناظر را تحت شرایط این مجوز و کد متناظر برنامه را به شکلی مناسب منتقل کنید تا کاربر بتواند آن را با نسخه تغییریافته مجدداً پیوند دهد.
.IP 1. 4
از یک مکانیزم مناسب کتابخانه مشترک برای پیوند با کتابخانه استفاده کنید.
.UNINDENT
.UNINDENT
.IP e. 3
ارائه اطلاعات نصب در صورتی که تحت بخش ۶ از GNU GPL الزامی باشد.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.IP 5. 3
کتابخانه‌های ترکیبی.
.UNINDENT
.sp
شما می‌توانید امکانات کتابخانه را که اثری بر پایه کتابخانه است در کنار سایر امکاناتی که تحت پوشش این مجوز نیستند در یک کتابخانه واحد قرار دهید و تحت شرایط انتخابی خود منتقل کنید، مشروط بر اینکه نسخه بدون ترکیب را نیز تحت شرایط این مجوز ارائه دهید و اطلاعیه برجسته‌ای همراه آن درج نمایید.
.INDENT 0.0
.IP 6. 3
نسخه‌های بازبینی‌شده مجوز عمومی همگانی گنو کمتر جامع.
.UNINDENT
.sp
بنیاد نرم‌افزار آزاد ممکن است نسخه‌های بازبینی‌شده یا جدیدی از مجوز عمومی همگانی گنو کمتر جامع را منتشر کند. چنین نسخه‌های جدیدی از نظر روح کلی شبیه به نسخه فعلی خواهند بود، اما ممکن است در جزئیات برای رفع مشکلات جدید تفاوت‌هایی داشته باشند.
.SS "نمایه‌ها و جدول‌ها (Indices and tables)"
.INDENT 0.0
.IP \(bu 2
\fI\%Index\fP (نمایه)
.IP \(bu 2
\fI\%Module Index\fP (نمایه ماژول‌ها)
.IP \(bu 2
\fI\%Search Page\fP (صفحه جستجو)
.UNINDENT
.SH "نویسنده (AUTHOR)"
George Yunaev
.SH "حق نشر (COPYRIGHT)"
2005-2024 George Yunaev, http://www.ulduzsoft.com/linux/libircclient
.\" Generated by docutils manpage writer.
.