معرفی (Introduction)

نمای کلی (Overview)

کتابخانه Libircclient یک کتابخانه کوچک اما بسیار قدرتمند است که پروتکل کارخواه (کلاینت) IRC را پیاده‌سازی می‌کند. این کتابخانه به گونه‌ای طراحی شده است که سبک، سریع، قابل‌حمل و سازگار با استانداردهای RFC و همچنین ویژگی‌های غیر استاندارد اما پرکاربرد باشد. این کتابخانه انتخابی عالی برای ساخت کلاینت‌ها و ربات‌های IRC است.

ویژگی‌ها (Features)

مشکلات شناخته‌شده (Known issues)

هرچند با استفاده از چندین نشست امکان‌پذیر است، اما این کتابخانه برای اتصال همزمان به تعداد بسیار زیادی از سرورهای IRC مناسب نیست. اگر همچنان می‌خواهید از آن بدین منظور استفاده کنید، باید بر موارد زیر فائق آیید:

نویسنده (Author)

این کتابخانه توسط George Yunaev ساخته شده است، حق نشر ۲۰۰۴-۲۰۱۶. لطفاً ببینید: http://www.ulduzsoft.com/linux/libircclient

مجوز (License)

کتابخانه Libircclient تحت مجوز Lesser General Public License نسخه ۳ یا بالاتر منتشر شده است. متن کامل مجوز در بخش پیوست ارائه شده است.

یکپارچه‌سازی (Integration)

نیازمندی‌ها (Requirements)

سیستم‌عامل‌ها و کامپایلرهای پشتیبانی‌شده (Supported operating systems and compilers)

این کتابخانه به طور گسترده روی پلتفرم‌های لینوکس x86 و x86_64 آزمایش شده است. همچنین روی پلتفرم‌های سولاریس x86، لینوکس روی معماری‌های ARM و MIPS، مک او اس (Mac OS X) روی x86 و نسخه‌های مختلف مایکروسافت ویندوز آزمایش شده است.

کامپایل (Compilation)

در لینوکس، FreeBSD و Mac OS X این کتابخانه پیش از استفاده باید کامپایل و نصب شود، مگر اینکه از بسته پیش‌کامپایل‌شده توزیع سیستم‌عامل خود استفاده کنید. در صورت ارائه بسته توزیع، استفاده از آن توصیه می‌شود زیرا هنگام رفع اشکالات از مخزن مرکزی به‌روزرسانی خواهد شد.

در مایکروسافت ویندوز فایل‌های باینری رسمی کتابخانه ارائه می‌شوند، بنابراین نیازی به بیلد آن ندارید. مگر اینکه تجربه بیلد با Cygwin را داشته باشید، توصیه می‌شود از سورس بیلد نکنید و از باینری رسمی استفاده کنید.

کتابخانه‌های مورد نیاز (Required libraries)

این کتابخانه فقط به libc (بسته glibc-devel در لینوکس) و gcc وابسته است، هرچند برنامه‌های نمونه به libstdc++ (بسته libstdc++-devel) و g++ نیز نیاز دارند. حداقل نسخه پشتیبانی‌شده glibc نسخه ۲.۲ است، اگرچه در صورت درخواست IPv6 حداقل نسخه ۲.۴ از glibc الزامی است.

اگر کتابخانه با پشتیبانی از SSL بیلد شود، بسته توسعه openssl (بسته openssl-devel) باید نصب باشد.

در مایکروسافت ویندوز باید محیط Cygwin به همراه بسته‌های توسعه لازم (و همچنین openssl-devel) نصب شده باشد.

کامپایل کردن (Compiling)

کتابخانه به روش استاندارد یونیکس پیکربندی و بیلد می‌شود:

./configure [--enable-openssl] [--enable-ipv6]
make

نصب (Installing)

اگرچه برای استفاده از کتابخانه‌ها نیازی به نصب نیست، اما هدف نصب برای راحتی ارائه شده و با اجرای دستور sudo make install قابل فراخوانی است.

پیوند دادن (Linking)

برنامه خود را بسته به نیاز به libircclient.a یا libircclient.so پیوند دهید. اگر از کتابخانه ارائه‌شده توسط سیستم استفاده می‌کنید، لطفاً با libircclient.so پیوند دهید.

اگر کتابخانه را با پشتیبانی از SSL بیلد کرده‌اید، لازم است با کتابخانه‌های OpenSSL پیوند برقرار کنید؛ فلگ‌های -lcrypto -lssl را به LDFLAGS خود بیفزایید.

در مایکروسافت ویندوز لطفاً با libircclient.lib پیوند دهید که به طور ضمنی با libircclient.dll پیوند می‌خورد.

کدنویسی (Coding)

مقداردهی اولیه (Initialization)

درج فایل‌های سرآیند (Include the headers)

پیش از استفاده از کتابخانه باید سرآیند کتابخانه libircclient.h را درج کنید. همچنین ممکن است بخواهید libirc_rfcnumeric.h را که کدهای RFC را فراهم می‌کند، اضافه نمایید:

#include "libircclient.h"
#include "libirc_rfcnumeric.h"

ایجاد گرداننده‌های رویداد (Create event handlers)

برخلاف بیشتر پروتکل‌های شبکه مانند HTTP یا SMTP، پروتکل IRC مبتنی بر رویداد است. رویدادها به صورت ناهمگام از سرور می‌آیند. برخی رویدادها با عمل شما ایجاد می‌شوند (مانند پیوستن به کانال یا تغییر نام مستعار)، برخی توسط سایر کاربران IRC ایجاد می‌شوند (مانند ارسال پیام برای شما)، و برخی توسط خود سرور IRC تولید می‌شوند (مانند ارسال یادداشت‌های عملیاتی یا فراخوانی سرویس‌های NickServ).

کتابخانه Libircclient با ارائه ساختار مدیریت رویداد به مدیریت این رویدادها کمک می‌کند. این ساختار رویدادهایی را اعلام می‌کند که می‌توانید در برنامه خود تعریف کنید، و هنگامی که چنین رویدادی از سرور دریافت شد، فراخوانی بازگشتی (callback) مناسب صدا زده خواهد شد. تعداد رویدادهایی که باید مدیریت کنید به پیچیدگی کلاینت شما و عملکردهایی که پشتیبانی می‌کند بستگی دارد.

به طور کلی فقط دو رویداد وجود دارند که برای ارائه حداقل عملکرد باید آن‌ها را مدیریت کنید: event_connect و event_numeric. با این حال توصیه می‌شود یک تابع تخلیه رویداد (dump) ایجاد کنید و از آن برای تمام رویدادهای استفاده‌نشده استفاده کنید تا مطمئن شوید به دلیل انتظار برای یک رویداد اشتباه، رویداد مهمی را از دست نمی‌دهید. تابع dump_event را در فایل examples/irctest.c ببینید.

مقداردهی اولیه ویژه ویندوز (Windows-specific initialization)

اگر در مایکروسافت ویندوز با کتابخانه ایستا (static) پیوند می‌دهید، باید قبل از فراخوانی توابع کتابخانه، کتابخانه Winsock2 را مقداردهی اولیه کنید. این کار به صورت زیر انجام می‌شود:

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

با این حال اگر با کتابخانه پویا (dynamic) (یعنی libircclient.dll) پیوند می‌دهید که در بیلد رسمی پیش‌فرض است، نیازی به این کار نیست زیرا DLL در زمان بارگذاری این کار را به صورت خودکار انجام می‌دهد.

ایجاد یک نشست IRC (Create an IRC session)

برای استفاده از کتابخانه باید حداقل یک نشست IRC (IRC session) ایجاد شود. یک نشست می‌تواند برای برقراری یک اتصال واحد به یک سرور IRC برای یک نام مستعار استفاده شود. با این حال در صورت نیاز می‌توان بیش از یک نشست ایجاد کرد.

برای ایجاد یک نشست، تابع irc_create_session() را فراخوانی کنید:

// ساختار کال‌بک‌های 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 )
    // مدیریت خطا

این کد می‌تواند به تعداد دفعات مورد نیاز برای ایجاد چندین نشست تکرار شود. همان ساختار فراخوانی بازگشتی می‌تواند برای چندین نشست مجدداً استفاده شود.

تنظیم گزینه‌ها (Set options)

علاوه بر اشکال‌زدایی، دو گزینه وجود دارد که ممکن است به آن‌ها نیاز داشته باشید. گزینه LIBIRC_OPTION_STRIPNICKS تجزیه خودکار نام‌های مستعار را فعال می‌کند، و از آنجا که به سختی می‌توان موردی را تصور کرد که این گزینه نباید فعال باشد، ما آن را فعال می‌کنیم:

irc_option_set( session, LIBIRC_OPTION_STRIPNICKS );

گزینه دومی که ممکن است در صورت استفاده از اتصالات SSL و اتصال به سرورهایی با گواهینامه‌های خودامضا (self-signed) نیاز داشته باشید، در مستندات LIBIRC_OPTION_SSL_NO_VERIFY شرح داده شده است.

اتصال به سرور (Connect to the server)

برای شروع اتصال به سرور IRC، تابع irc_connect() را فراخوانی کنید:

// اتصال به یک سرور معمولی IRC
if ( irc_connect (session, "irc.example.com", 6667, 0, "mynick", "myusername", "myrealname" ) )
  // مدیریت خطا: ()irc_strerror و ()irc_errno

برای شروع اتصال به سرور IRC از طریق SSL، تابع irc_connect() را فراخوانی کنید و پیشوند نام میزبان یا نشانی IP را با یک علامت هش (#) قرار دهید:

// اتصال به سرور SSL؛ درج 192.168.1.1# نیز ممکن است
if ( irc_connect (session, "#irc.example.com", 6669, 0, "mynick", "myusername", "myrealname" ) )
  // مدیریت خطا: ()irc_strerror و ()irc_errno

این تابع فقط اتصال را آغاز می‌کند، بنابراین هنگامی که با موفقیت بازمی‌گردد، اتصال تنها آغاز شده است اما هنوز برقرار نشده است. سپس پس از فراخوانی گرداننده شبکه یکی از موارد زیر رخ می‌دهد:

اتصال به سرور IPv6 (Connect to the IPv6 server)

برای آغاز اتصال به سرور IPv6، تابع irc_connect6() را فراخوانی کنید:

if ( irc_connect6 (session, "2001:0db8:85a3:0042:1000:8a2e:0370:7334", 6669, 0, "mynick", "myusername", "myrealname" ) )
  // مدیریت خطا: ()irc_strerror و ()irc_errno

بقیه جزئیات، از جمله مقدار بازگشتی و SSL همانند اتصال معمولی است.

شروع حلقه شبکه (Start the networking loop)

برای اینکه به کتابخانه اجازه دهید رویدادها را مدیریت کند، دو سناریو وجود دارد. می‌توانید حلقه شبکه داخلی را فراخوانی کنید که عملیات شبکه را مدیریت کرده و رویدادهای شما را فراخوانی می‌کند، یا می‌توانید حلقه خود را بنویسید.

فراخوانی حلقه شبکه داخلی ساده‌تر اما محدود است. از آنجا که این حلقه تا زمان پایان اتصال اجرا می‌شود، برای یک برنامه دارای رابط کاربری گرافیکی (GUI) مناسب نیست (مگر اینکه حلقه را در یک نخ جداگانه اجرا کنید که این کار امکان‌پذیر است). و از آنجا که این حلقه فقط می‌تواند یک نشست را مدیریت کند، در صورتی که بخواهید چندین نشست IRC را مدیریت کنید استفاده از آن غیرممکن است. در این موارد باید از حلقه شبکه سفارشی که در زیر توضیح داده شده استفاده شود.

برای شروع حلقه رویداد، تابع irc_run() را فراخوانی کنید:

if ( irc_run (s) )
  // یا اتصال به سرور برقرار نشد یا قطع شد. به ()irc_errno مراجعه کنید

به یاد داشته باشید که فراخوانی ()irc_run تا زمانی که اتصال سرور دیگر فعال نباشد بازنخواهد گشت.

استفاده از حلقه شبکه سفارشی (Use the custom networking loop)

اگر از چندین نشست استفاده می‌کنید یا گرداننده سوکت خودتان را دارید، می‌توانید از حلقه شبکه سفارشی استفاده کنید. در این حالت برنامه شما باید مبتنی بر select() باشد (اگر می‌خواهید از روش‌های دیگر نظرسنجی استفاده کنید، پرسش‌های متداول (FAQ) را ببینید). و باید حلقه زیر را اجرا کنید:

// مطمئن شوید که تمام نشست‌های 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) )
    // اتصال با شکست روبرو شد یا سرور ارتباط را قطع کرد. آن را مدیریت کنید.
// تکرار مجدد

کانال‌ها و کاربران (Channels and users)

پیش از فراخوانی هر یک از این توابع مطمئن شوید که به سرور متصل شده‌اید.

ورود به کانال و خروج از آن (Join and leave a channel)

برای ورود به کانال، تابع irc_cmd_join() را همراه با نام کانال فراخوانی کنید:

// ورود به کانال #linux
if ( irc_cmd_join( session, "#linux", 0 ) )
  // احتمالاً خطای اتصال
// ورود به کانال science$ محافظت‌شده با کلید سری *superpassword*
if ( irc_cmd_join( session, "$science", "superpassword" ) )
  // احتمالاً خطای اتصال

می‌توانید به هر تعداد کانال که می‌خواهید ملحق شوید، اگرچه ممکن است سرور تعداد کانال‌هایی را که می‌توانید همزمان در آن‌ها عضو باشید محدود کند.

اگر پیوستن موفقیت‌آمیز باشد، رویداد event_join را دریافت خواهید کرد. قبل از اینکه بتوانید هرگونه عملیات کانال (مانند ارسال پیام) را انجام دهید، باید منتظر این رویداد بمانید. با این حال نیازی نیست برای صدور دستور دوم JOIN همان‌طور که در مثال بالا نشان داده شد، منتظر این رویداد بمانید.

اگر پیوستن موفقیت‌آمیز نبود، خطا را از طریق event_numeric دریافت خواهید کرد.

برای خروج از کانال، تابع irc_cmd_part() را همراه با نام کانال فراخوانی کنید:

// خروج از کانال #linux
if ( irc_cmd_part( session, "#linux" ) )
  // احتمالاً خطای اتصال
// خروج از کانال science$
if ( irc_cmd_part( session, "$science" ) )
  // احتمالاً خطای اتصال

ارسال پیام به یک کانال یا کاربر (Send a message to a channel or to a user)

پس از ورود به کانال، می‌توانید با استفاده از تابع irc_cmd_msg() همراه با نام کانال، پیامی به آن بفرستید:

// ارسال پیام "!Hi" به همه در کانال #linux
if ( irc_cmd_msg( session, "#linux", "Hi!" ) )
  // احتمالاً خطای اتصال

از نظر فنی، پروتکل کاربر را ملزم نمی‌کند که برای ارسال پیام به یک کانال، حتماً عضو آن باشد. اما اکثر سرورها به طور پیش‌فرض حالت کانالی را تنظیم می‌کنند که مانع از ارسال پیام توسط کاربرانی می‌شود که به کانال نپیوسته‌اند.

از همین تابع برای ارسال یک پیام «خصوصی» به کاربر دیگر استفاده می‌شود. پیام‌های «خصوصی» از کانال‌ها عبور نمی‌کنند، اما همچنان از سرور IRC (گاهی چندین سرور) عبور می‌کنند و توسط مدیران شبکه IRC قابل مشاهده یا حتی ثبت هستند.

// ارسال پیام "!Hi" به کاربر john در IRC
if ( irc_cmd_msg( session, "john", "Hi!" ) )
  // احتمالاً خطای اتصال

اگر پیام با موفقیت ارسال شود، هیچ تأییدیه یا رویدادی دریافت نخواهید کرد. فقط در صورتی که پیام ارسال نشود، خطا را از طریق event_numeric دریافت خواهید کرد.

دریافت پیام‌ها از یک کانال یا کاربر (Receive messages from a channel or from a user)

شما پیام‌های کانال را با مدیریت رویداد event_channel دریافت می‌کنید. هر بار که کسی در کانال سخنی می‌گوید این رویداد فراخوانی می‌شود.

پیام‌های «خصوصی» از دیگر کاربران را با مدیریت رویداد event_privmsg دریافت می‌کنید.

این گرداننده‌های رویداد باید در برنامه شما ایجاد شوند و هنگام ایجاد نشست IRC به کتابخانه فرستاده شوند.

ارسال پیام کنش (Send an action message)

پیام‌های «کنش» (Action) که پیام‌های me/ نیز نامیده می‌شوند، پیام‌های CTCP با قالب‌بندی ویژه هستند. با این حال کتابخانه شامل یک تابع ویژه به نام irc_cmd_me() برای ارسال آن‌ها است. کنش‌های ارسال‌شده توسط افراد دیگر توسط رویداد event_ctcp_action مدیریت می‌شوند.

همانند ارسال پیام، در صورت موفقیت هیچ تاییدیه‌ای دریافت نمی‌شود.

ارسال درخواست CTCP (Send a CTCP request)

سایر درخواست‌های CTCP مانند PING، VERSION و غیره باید با فراخوانی irc_cmd_ctcp_request() ارسال شوند. در صورت دریافت پاسخ CTCP، رویداد event_ctcp_rep آن را مدیریت می‌کند.

مدیریت گفتگوی DCC (Handling DCC chat)

پیاده‌سازی فراخوانی بازگشتی DCC (Implementing the DCC callback)

صرف‌نظر از اینکه قصد شروع گفتگوهای DCC را دارید یا پاسخ دادن به آن‌ها، باید کال‌بک DCC را پیاده‌سازی کنید:

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, "Hello!" );
   }
   else
   {
       // پیام گفتگو از طرف مقابل دریافت شد
       printf ("Remote party said: %s\n", data );
   }
}

این کال‌بک باید یا به تابع irc_dcc_chat() که درخواست را آغاز می‌کند، یا به تابع irc_dcc_accept() که درخواست DCC CHAT آغاز شده توسط کاربر دیگر را می‌پذیرد، فرستاده شود.

شروع گفتگوی DCC (Initiating the DCC CHAT)

می‌توانید گفتگوی DCC را با کاربر دیگری با فراخوانی irc_dcc_chat() آغاز کنید:

// شناسه نشست گفتگوی DCC در این متغیر بازگردانده می‌شود
irc_dcc_t dccid;
// آغاز گفتگوی DCC با کاربر john در IRC
if ( irc_dcc_chat( session, 0, "john", dcc_callback, &dccid ) )
  // گزارش خطا

اکنون می‌توانید به کارهای دیگر ادامه دهید. هنگامی که جان گفتگو را پذیرفت یا رد کرد، dcc_callback() فراخوانی خواهد شد و امکان استفاده از تابع irc_dcc_text() برای ارسال پیام‌های گفتگو فراهم خواهد بود. این فراخوانی بازگشتی همچنین هر بار که پیام گفتگوی جدیدی دریافت شود، یا زمانی که گفتگو به پایان برسد یا به دلیل خطای شبکه قطع شود، فراخوانی خواهد شد.

پاسخ به درخواست‌های گفتگوی DCC (Responding to DCC CHAT requests)

برای پاسخ دادن به درخواست‌های DCC CHAT، برنامه شما باید رویداد event_dcc_chat_req را پیاده‌سازی کند. این فراخوانی بازگشتی می‌تواند به صورت زیر پیاده‌سازی شود:

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, "CHAT from " + nick + " IP address: " + addr  );
}

و در زمان ایجاد نشست IRC ثبت شود. اگر برنامه شما اصلاً DCC را مدیریت نمی‌کند، می‌توانید تابع irc_dcc_decline() را داخل این کال‌بک صدا بزنید.

اگر مدیریت می‌کند، ما فقط این اطلاعات را در کال‌بک ذخیره کرده و بازمی‌گردیم. زیرا پردازش رویدادها تا زمان بازگشت کال‌بک متوقف خواهد شد، بنابراین نمایش پنجره گفتگو برای درخواست تایید از کاربر، پردازش رویدادهای بعدی مانند پیام‌های کانال را متوقف می‌کند. حتی اگر برنامه شما خودکار است و پنجره‌ای نمایش نمی‌دهد، باز هم بهتر است منطق گفتگو را از منطق فراخوانی بازگشتی جدا کنید.

کمی بعدتر برنامه در نخ GUI صف را بررسی می‌کند، این اطلاعات را دریافت کرده و پنجره درخواست نظر کاربر را نمایش می‌دهد. سپس اگر درخواست گفتگو پذیرفته شد، برنامه تابع irc_dcc_accept() را فراخوانی می‌کند، و اگر رد شد، تابع irc_dcc_decline() را صدا می‌زند. هر دو تابع شناسه dccid را می‌پذیرند که این درخواست خاص را مشخص می‌کند:

// جایی در نخ 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 );
}

ارسال پیام‌های گفتگوی DCC (Send CHAT messages)

پس از برقراری نشست گفتگو، می‌توانید پیام‌های گفتگو را با استفاده از تابع irc_dcc_text() ارسال کنید. توجه داشته باشید که به جای نام مستعار، باید شناسه نشست dcc را ارسال کنید:

irc_dcc_text( session, dccid, "Hello there!" );

مدیریت انتقال فایل DCC (Handling DCC file transfer)

این بخش مدیریت ارسال و دریافت فایل‌ها از طریق DCC را پوشش می‌دهد.

پیاده‌سازی فراخوانی بازگشتی (Implementing the callback)

صرف‌نظر از اینکه قصد ارسال یا دریافت فایل‌ها از طریق dcc را دارید، باید کال‌بک DCC را پیاده‌سازی کنید. در حالی که ممکن است از همان کال‌بک برای هر دو مورد ارسال و دریافت استفاده شود، اما به دلیل تفاوت منطق، این کار توصیه نمی‌شود. بنابراین پیاده‌سازی پیشنهادی استفاده از کال‌بک‌های متفاوت به صورت زیر است:

// این کال‌بک هنگام ارسال فایل به طرف مقابل استفاده می‌شود
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 ("Sent bytes: %d\n", 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 ("File has been received successfully\n" );
   }
   else
   {
       // بخش دیگری از محتوای فایل دریافت شد. آن را در حافظه ذخیره کنید، روی دیسک بنویسید یا موارد مشابه
       printf ("Received %d bytes of data\n", length );
   }
}

این کال‌بک باید یا به تابع irc_dcc_sendfile() که درخواست را آغاز می‌کند، یا به تابع irc_dcc_accept() که درخواست DCC RECVFILE آغاز شده توسط کاربر دیگر را می‌پذیرد، فرستاده شود.

ارسال فایل از طریق DCC (Sending the file via DCC)

می‌توانید ارسال فایل از طریق DCC به کاربر دیگر را با فراخوانی irc_dcc_sendfile() آغاز کنید:

// شناسه نشست DCC در این متغیر بازگردانده می‌شود
irc_dcc_t dccid;
// آغاز ارسال فایل "/etc/passwd" از طریق گفتگوی DCC به کاربر "john" در IRC
if ( irc_dcc_sendfile( session, 0, "john", "/etc/passwd", callback_dcc_send_file, &dccid ) )
  // گزارش خطا

اکنون می‌توانید به کارهای دیگر ادامه دهید. وقتی جان درخواست را بپذیرد، فایل ارسال می‌شود و callback_dcc_send_file() هر بار که تکه‌ای از فایل ارسال می‌شود فراخوانی خواهد شد. همچنین پس از ارسال کامل فایل یا هنگامی که ارسال به دلیل خطای شبکه متوقف شود، این کال‌بک فراخوانی خواهد شد.

دریافت فایل از طریق DCC (Receive a file via DCC)

برای دریافت فایل از طریق DCC، یک کاربر دوردست باید درخواست DCC برای ارسال فایلی به شما را آغاز کند. برای دریافت این درخواست، برنامه شما باید رویداد event_dcc_send_req را پیاده‌سازی کند. این کال‌بک می‌تواند به صورت زیر پیاده‌سازی شود:

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, "CHAT from " + nick + " IP address: " + addr + ", filename " + filename  );
}

اگر برنامه شما اصلاً DCC را مدیریت نمی‌کند، می‌توانید تابع irc_dcc_decline() را داخل کال‌بک صدا بزنید.

اگر مدیریت می‌کند، ما فقط این اطلاعات را در کال‌بک ذخیره کرده و بازمی‌گردیم. زیرا پردازش رویدادها تا زمان بازگشت کال‌بک متوقف می‌شود، بنابراین نمایش کادر محاوره‌ای برای درخواست تایید از کاربر، پردازش رویدادهای بعدی مانند پیام‌های کانال را متوقف می‌کند. حتی اگر برنامه شما خودکار باشد و پنجره‌ای نمایش ندهد، باز هم بهتر است منطق گفتگو را از منطق فراخوانی بازگشتی جدا کنید.

کمی بعدتر برنامه در نخ GUI صف را بررسی می‌کند، این اطلاعات را دریافت کرده و کادر محاوره‌ای درخواست تایید کاربر را نمایش می‌دهد. سپس اگر درخواست پذیرفته شد، برنامه تابع irc_dcc_accept() را صدا می‌زند، و اگر رد شد، تابع irc_dcc_decline() را فراخوانی می‌کند. هر دو تابع شناسه dccid را می‌پذیرند که این درخواست خاص را مشخص می‌کند:

// جایی در نخ 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 );
}

توجه داشته باشید که امکان ارسال درخواست به یک کاربر دوردست برای فرستادن یک فایل به شما وجود ندارد.

مدیریت رنگ‌ها (Handling colors)

حذف رنگ‌ها از پیام (Stripping colors from the message)

اگر ربات شما به پیام‌های متنی واکنش نشان می‌دهد، باید پیش از پردازش پیام‌ها رنگ‌ها را از آن‌ها پاک کنید. در غیر این صورت کاربری که پیام رنگی ارسال می‌کند پاسخی مشابه کاربری که از رنگ استفاده نکرده دریافت نخواهد کرد، و برخی کاربران به طور پیش‌فرض از رنگ‌ها استفاده می‌کنند.

از تابع irc_color_strip_from_mirc() برای پاک کردن رنگ‌های ANSI از پیام متنی استفاده کنید. این تابع پیامی را که از رنگ استفاده نکرده تغییر نمی‌دهد.

تبدیل رنگ (Color conversion)

این کتابخانه از تبدیل رنگ پشتیبانی می‌کند و می‌تواند رنگ‌ها را بین رنگ‌های ANSI مورد استفاده کلاینت‌های IRC و نمایش متنی آن‌ها تبدیل کند. استفاده از رنگ‌ها معمولاً به پیام‌ها و دلایل مشخص‌شده توسط کاربر محدود می‌شود. نمی‌توانید از رنگ‌ها به عنوان بخشی از نام مستعار یا نام کانال خود استفاده کنید.

از تابع irc_color_convert_from_mirc() برای تبدیل رنگ‌ها از ANSI به نمایش متنی کتابخانه، و از تابع irc_color_convert_to_mirc() برای تبدیل نمایش متنی رنگ‌ها در کتابخانه به ANSI استفاده کنید.

فراموش نکنید که پس از پایان استفاده، اشاره‌گر بازگردانده‌شده را با free() آزاد کنید.

متفرقه (Miscellaneous)

ردیابی نام‌های مستعار کاربران (Tracking user nicks)

اگر برنامه شما سهمیه‌های خاصی را برای هر کاربر نگهداری می‌کند، ردیابی تغییرات نام مستعار اهمیت دارد. از آنجا که نام مستعار تنها شناسه در دسترس شماست، هر بار که کاربر نام مستعار خود را تغییر می‌دهد باید پایگاه داده سهمیه خود را به‌روزرسانی کنید. برای انجام این کار باید رویداد event_nick را شنود کنید. برای جزئیات به examples/censor.c مراجعه کنید.

فراخوانی‌های بازگشتی (Callbacks)

این بخش فراخوانی‌های بازگشتی (کال‌بک‌ها) پشتیبانی‌شده توسط کتابخانه را شرح می‌دهد.

irc_event_callback_t

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

هر رویداد IRC یک فراخوانی بازگشتی ایجاد می‌کند. این نوع کال‌بک سراسری است و تقریباً توسط تمام رویدادهای IRC استفاده می‌شود. بسته به ماهیت رویداد، می‌تواند صفر یا چند پارامتر داشته باشد. برای هر نوع رویداد، تعداد پارامترهای ارائه‌شده ثابت است و معنای آن‌ها در ساختار irc_callbacks_t توصیف شده است.

هر رویداد دارای یک مبدأ است (یعنی چه کسی رویداد را آغاز کرده است). در برخی موارد متغیر origin ممکن است NULL باشد که نشان می‌دهد مبدأ رویداد ناشناخته است. مبدأ معمولاً شبیه به nick!host@ircserver است، مانند tim!home@irc.server.net. چنین مبدأهایی نمی‌توانند در دستورات IRC استفاده شوند و قبل از استفاده باید پیراسته شوند (یعنی بخش میزبان و سرور باید حذف شود). این کار می‌تواند یا به صورت دستی با فراخوانی irc_target_get_nick() یا به صورت خودکار برای همه رویدادها با تنظیم گزینه LIBIRC_OPTION_STRIPNICKS از طریق irc_option_set() انجام گیرد.

irc_event_dcc_chat_t

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این کال‌بک زمانی فراخوانی می‌شود که شخصی از شما درخواست DCC CHAT کند. گفتگوی DCC نوعی گفتگو است که به جای عبور از سرور IRC، مستقیماً میان کلاینت‌ها صورت می‌گیرد. از آنجا که برای برقراری آن باید اتصال TCP تشکیل شود، معمولاً آغازکننده باید IP عمومی داشته باشد یا از نرم‌افزار ویژه‌ای روی فایروال برای هدایت پورت (port forwarding) استفاده کند.

شما باید به درخواست گفتگو یا با فراخوانی irc_dcc_accept() برای پذیرش آن، یا با فراخوانی irc_dcc_decline() برای رد آن پاسخ دهید.

irc_event_dcc_send_t

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این کال‌بک زمانی فراخوانی می‌شود که کسی بخواهد با استفاده از DCC SEND فایلی برای شما ارسال کند. ارسال با DCC SEND مستقیماً میان کلاینت‌ها انجام می‌شود و نیازمند برقراری اتصال TCP است. بنابراین آغازکننده باید IP عمومی یا تنظیمات هدایت پورت در فایروال داشته باشد.

شما باید به درخواست گفتگو یا با فراخوانی irc_dcc_accept() برای پذیرش آن، یا با فراخوانی irc_dcc_decline() برای رد آن پاسخ دهید.

irc_dcc_callback_t

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این کال‌بک برای تمام توابع DCC هنگامی که تغییر وضعیت رخ دهد فراخوانی می‌شود.

irc_eventcode_callback_t

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این یک کال‌بک پیشرفته برای کسانی است که می‌خواهند رویدادها را در سطحی عمیق‌تر مدیریت کنند. در بیشتر مواقع سرور IRC به اقدامات شما با رویدادهای عددی پاسخ می‌دهد. بیشتر این رویدادها کدهای خطا هستند، و برخی نشانگرهای شروع و پایان فهرست هستند. هر کد مجموعه پارامترهای خود را دارد؛ برای جزئیات می‌توانید آزمایش کنید یا RFC 1459 را بخوانید (البته انتظار نداشته باشید سرورها دقیقاً از آن پیروی کنند).

هر رویداد دارای یک مبدأ است (یعنی چه کسی رویداد را آغاز کرده است). در برخی موارد متغیر origin ممکن است NULL باشد که نشان می‌دهد مبدأ رویداد ناشناخته است. مبدأ معمولاً شبیه به nick!host@ircserver است، مانند tim!home@irc.server.net. چنین مبدأهایی نمی‌توانند در دستورات IRC استفاده شوند و قبل از استفاده باید پیراسته شوند (یعنی بخش میزبان و سرور باید حذف شود). این کار می‌تواند یا به صورت دستی با فراخوانی irc_target_get_nick() یا به صورت خودکار برای همه رویدادها با تنظیم گزینه LIBIRC_OPTION_STRIPNICKS از طریق irc_option_set() انجام گیرد.

توابع (Functions)

این بخش توابع تعریف‌شده در کتابخانه را شرح می‌دهد که بر اساس هدف گروه‌بندی شده‌اند.

راه‌اندازی و خاتمه کتابخانه (Library initialization and shutdown)

irc_create_session

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

یک نشست جدید IRC ایجاد و آغاز می‌کند. هر نشست نشان‌دهنده یک اتصال واحد کاربر به یک سرور IRC منفرد است، و احتمالاً به یک یا چند کاربر دیگر از طریق DCC. تقریباً تمام توابع کتابخانه نیازمند ارسال این شیء هستند، و بنابراین این تابع باید در ابتدا فراخوانی شود. چندین نشست را می‌توان برای پشتیبانی از اتصالات متعدد تخصیص داد.

هنگامی که دیگر نیازی به نشست نباشد، باید با فراخوانی تابع irc_destroy_session() از بین برود.

مقدار بازگشتی (Return value):

یک شیء irc_session_t، یا 0 در صورت شکست عملیات ایجاد. معمولاً شکست به دلیل خطای کمبود حافظه رخ می‌دهد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود. ساختار کال‌بک یکسان می‌تواند توسط چندین نخ مجدداً استفاده شود.

irc_destroy_session

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع یک نشست IRC را نابود می‌کند، اتصال به سرور IRC را می‌بندد و تمام منابع استفاده‌شده را آزاد می‌نماید. پس از فراخوانی این تابع دیگر نباید از این شیء نشست استفاده کنید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

اتصال، قطع اتصال و اجرای حلقه رویداد اصلی (Connecting, disconnecting and running the main event loop)

irc_connect6

پیش‌نمونه (Prototype):

irc_connect

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع اتصال به سرور IRC در پروتکل IPv4 (تابع irc_connect) یا IPv6 (تابع irc_connect6) را آغاز می‌کند. سرور می‌تواند با نشانی IP یا نام دامنه DNS مشخص شود. تابع irc_connect6 تنها در صورتی کار می‌کند که کتابخانه با پشتیبانی از IPv6 بیلد شده باشد.

اگر کتابخانه با پشتیبانی از OpenSSL بیلد شده باشد و نشانی IP یا نام میزبان با یک علامت هش پیشوند شود (مانند "#irc.example.com")، کتابخانه تلاش می‌کند اتصال SSL برقرار کند.

اتصال به صورت ناهمگام برقرار می‌شود و پس از برقراری موفق، رویداد event_connect فراخوانی می‌گردد.

یک شیء نشست IRC تنها می‌تواند به یک سرور IRC متصل باشد و فقط با یک نام مستعار، به این معنی که امکان استفاده چند نام مستعار به صورت مشترک از یک اتصال واحد وجود ندارد.

مقدار بازگشتی (Return value):

در صورت آغاز موفقیت‌آمیز اتصال، مقدار 0 برمی‌گرداند. این به معنای برقراری کامل اتصال نیست؛ هنگامی که اتصال برقرار شود رویداد event_connect فراخوانی می‌شود. اگر اتصال برقرار نشود، یا تابع irc_run() یا تابع irc_process_select_descriptors() یک خطا بازمی‌گردانند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود، اما نه با استفاده از شیء نشست یکسان.

irc_disconnect

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع اتصال IRC را می‌بندد. پس از بسته شدن اتصال، اگر libirc در حلقه irc_run() قفل شده باشد، به طور خودکار از حلقه خارج شده و تابع irc_run() بازمی‌گردد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود، اما نه با استفاده از یک شیء نشست یکسان.

irc_is_connected

پیش‌نمونه (Prototype):

پارامترها (Parameters):

مقدار بازگشتی (Return value):

این تابع در صورتی که اتصال به سرور IRC برقرار باشد مقدار 1 و در غیر این صورت مقدار 0 برمی‌گرداند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_run

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع وارد یک حلقه بی‌پایان می‌شود، رویدادهای IRC را پردازش می‌کند و فراخوانی‌های بازگشتی مربوطه را صدا می‌زند. این تابع تا زمانی که اتصال سرور قطع نشود (یا توسط سرور یا با فراخوانی irc_cmd_quit) بازنخواهد گشت. این تابع فقط در صورتی باید استفاده شود که از یک نشست منفرد IRC استفاده می‌کنید و نیازی به پردازش درخواست‌های ناهمگام ندارید (یعنی ربات شما فقط به رویدادها واکنش نشان می‌دهد و آن‌ها را به صورت ناهمگام تولید نمی‌کند). حتی در حالت آخر، همچنان می‌توانید این تابع را فراخوانی کرده و نخ ناهمگام را در گرداننده رویداد event_connect آغاز کنید. مثال‌ها را ببینید.

مقدار بازگشتی (Return value):

این تابع در صورتی که اتصال به سرور IRC برقرار نشود یا قطع شود، یک مقدار غیرصفر بازمی‌گرداند.

امنیت نخ (Thread safety):

این تابع نمی‌تواند از چندین نخ فراخوانی شود. به جای آن از irc_add_select_descriptors() و irc_process_select_descriptors() استفاده کنید.

irc_add_select_descriptors

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع باید پس از فراخوانی irc_connect() استفاده شود. زمانی مفید است که حلقه پردازش رویداد مبتنی بر select اختصاصی خود را داشته باشید. برای استفاده از آن باید توصیف‌کننده‌های خود را در مجموعه‌ها قرار دهید، این تابع را برای افزودن توصیف‌کننده(های) کتابخانه به مجموعه فراخوانی کنید و سپس ()select را صدا بزنید. پس از بازگشت آن، باید irc_process_select_descriptors() را فراخوانی کنید که رویدادها را مدیریت کرده و کال‌بک‌های شما را صدا می‌زند(!). سپس می‌توانید رویدادهای سوکت خود را از مجموعه پردازش کنید. مثال را ببینید.

اگر از epoll استفاده می‌کنید چه؟ پرسش‌های متداول (FAQ) را ببینید.

مقدار بازگشتی (Return value):

این تابع در صورتی که irc_connect() پیش از فراخوانی این تابع صدا زده نشده باشد، مقدار غیرصفر برمی‌گرداند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود، اما به ندرت منطقی است.

irc_process_select_descriptors

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع باید به همراه تابع irc_add_select_descriptors() استفاده شود، که مستندات آن نحوه عملکرد مشترک آن‌ها را شرح می‌دهد.

توجه داشته باشید که هنگام پردازش رویدادها، این تابع کال‌بک‌های شما را فراخوانی می‌کند و تا زمانی که همه کال‌بک‌های شما بازنگردند، بازنخواهد گشت. در صورتی که در برنامه خود یک کادر محاوره‌ای (مانند تایید DCC CHAT یا DCC SEND) باز می‌کنید، این نکته را به خاطر داشته باشید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 به معنی موفقیت است. مقادیر دیگر به معنی خطا هستند و کد خطا را می‌توان از طریق ()irc_errno دریافت کرد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ تنها برای اشیاء نشست متفاوت IRC فراخوانی شود.

مدیریت کانال‌های IRC: ورود، خروج، دعوت (Managing the IRC channels: joining, leaving, inviting)

irc_cmd_join

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

از این تابع برای پیوستن به یک کانال جدید IRC استفاده کنید. اگر کانال وجود نداشته باشد، به طور خودکار توسط سرور IRC ایجاد خواهد شد. توجه داشته باشید که برای ورود به کانال دارای گذرواژه، باید گذرواژه را بدانید و آن را در آرگومان key مشخص کنید. در صورت موفقیت‌آمیز بودن پیوستن، رویداد event_join فراخوانی خواهد شد (با نام مستعار شما به عنوان مبدأ)، سپس معمولاً event_topic فراخوانی می‌شود و پس از آن فهرست کاربران حاضر در کانال را (با استفاده از LIBIRC_RFC_RPL_NAMREPLY) دریافت خواهید کرد که شامل کاربری که به تازگی پیوسته است نیز می‌شود.

مقدار بازگشتی (Return value):

کد بازگشتی 0 به این معنی است که دستور با موفقیت به سرور IRC ارسال شده است. این به معنی موفقیت‌آمیز بودن قطعی عملیات نیست، و شما باید منتظر رویداد مناسب یا کد خطا از طریق رویداد event_numeric بمانید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_part

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

از این تابع برای خروج از کانال IRC که قبلاً به آن پیوسته‌اید استفاده کنید. تلاش برای ترک کانالی که در آن حضور ندارید منجر به خطای سرور LIBIRC_RFC_ERR_NOTONCHANNEL می‌شود.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC ارسال شد. این به معنای موفقیت کامل عملیات نیست و باید منتظر رویداد مربوطه یا کد خطا از طریق event_numeric بمانید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_invite

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای دعوت شخصی به یک کانال «فقط‌دعوتی» استفاده می‌شود. «فقط‌دعوتی» (Invite-only) یک حالت کانال است که پیوستن به کانال را برای همه، به جز دعوت‌شدگان، محدود می‌کند. پس از دعوت، کاربر می‌تواند به این کانال بپیوندد. کاربری که دعوت شده رویداد event_invite را دریافت خواهد کرد. توجه داشته باشید که برای دعوت کاربران باید اپراتور کانال باشید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است. شما باید منتظر رویداد مربوطه یا کد خطا از طریق event_numeric باشید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_names

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای درخواست فهرست کاربرانی که به کانال مشخص‌شده پیوسته‌اند از سرور IRC استفاده می‌شود. می‌توانید تمام نام‌های مستعاری را که برای شما در هر کانال قابل مشاهده است فهرست کنید. فهرست کاربران با استفاده از کدهای عددی LIBIRC_RFC_RPL_NAMREPLY و LIBIRC_RFC_RPL_ENDOFNAMES بازگردانده می‌شود.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور فرستاده شد. برای تایید نهایی باید منتظر رویداد مربوطه باشید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_list

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای درخواست فهرست کانال‌های فعال (موجود) از سرور IRC استفاده می‌شود. این فهرست با توالی رویدادهای LIBIRC_RFC_RPL_LISTSTART، چندین LIBIRC_RFC_RPL_LIST و LIBIRC_RFC_RPL_LISTEND بازگردانده خواهد شد. توجه داشته باشید که کانال‌های «خصوصی» (بدون موضوع آن‌ها) به صورت کانال "Prv" فهرست می‌شوند، مگر اینکه کلاینت ارسال‌کننده پرس‌وجو واقعاً در آن کانال حضور داشته باشد. به همین ترتیب کانال‌های مخفی اصلاً فهرست نمی‌شوند مگر اینکه کلاینت در کانال مورد نظر فعال باشد.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_topic

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای تغییر یا مشاهده موضوع (عنوان) یک کانال استفاده می‌شود. توجه داشته باشید که بسته به حالت t+ کانال، ممکن است برای تغییر موضوع کانال ملزم به داشتن دسترسی اپراتور کانال باشید.

اگر دستور موفقیت‌آمیز باشد، سرور IRC یک پیام LIBIRC_RFC_RPL_NOTOPIC یا LIBIRC_RFC_RPL_TOPIC تولید می‌کند که حاوی موضوع قدیمی یا تغییر یافته است. همچنین سرور IRC می‌تواند (اما الزامی نیست) پیام غیر RFC با عنوان LIBIRC_RFC_RPL_TOPIC_EXTRA تولید کند که حاوی نام مستعار فرد تغییردهنده موضوع و تاریخ و زمان آخرین تغییر است.

مقدار بازگشتی (Return value):

کد بازگشتی 0 نشان می‌دهد که دستور با موفقیت به سرور ارسال شده است.

اگر تغییر موضوع درخواست شده و با موفقیت انجام شده باشد، رویداد event_topic نیز تولید می‌شود.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_channel_mode

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای تغییر یا مشاهده حالت‌های کانال به کار می‌رود. توجه داشته باشید که تنها اپراتورهای کانال می‌توانند حالت آن را تغییر دهند.

حالت کانال با ترکیبی از چندین حرف نشان داده می‌شود. هر حرف در حالت‌های کانال معنای خاص خود را دارد. بیشتر حروف حالت‌های کانال بولی هستند (یعنی فقط می‌توانند تنظیم یا بازنشانی شوند)، اما تعداد کمی از آن‌ها پارامتر می‌پذیرند. تمام گزینه‌های کانال با افزودن علامت مثبت قبل از حرف فعال، و با افزودن علامت منفی غیرفعال می‌شوند.

در اینجا فهرستی از حالت‌های «استاندارد» کانال آورده شده است:

توجه داشته باشید که فهرست واقعی حالت‌های کانال به سرور IRC بستگی دارد و می‌تواند بزرگ‌تر باشد.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_user_mode

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای تغییر یا مشاهده حالت‌های کاربر استفاده می‌شود. توجه داشته باشید که بر خلاف حالت‌های کانال، برخی حالت‌های کاربر اصلاً قابل تغییر نیستند.

حالت کاربر با ترکیبی از حروف نشان داده می‌شود. تمام حروف حالت کاربر بولی هستند (یعنی فقط می‌توانند فعال یا غیرفعال شوند)، آن‌ها با اضافه کردن علامت مثبت فعال و با علامت منفی غیرفعال می‌شوند.

فهرست حالت‌های «استاندارد» کاربر:

توجه داشته باشید که فهرست واقعی حالت‌های کاربر به سرور IRC بستگی دارد و می‌تواند گسترده‌تر باشد.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.

اطلاعات حالت قبلی با استفاده از کد عددی LIBIRC_RFC_RPL_UMODEIS بازگردانده می‌شود:

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_kick

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای اخراج یک شخص از کانال استفاده می‌شود. توجه داشته باشید که برای اخراج دیگران از یک کانال باید اپراتور کانال باشید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است.

اگر دستور موفق شود، رویداد event_kick تولید خواهد شد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

ارسال پیام‌ها، اعلان‌ها، پیام‌های /me و کار با CTCP (Sending the messages, notices, /me messages and working with CTCP)

irc_cmd_msg

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای ارسال پیام به یک کانال یا به طور خصوصی به یک نام مستعار دیگر استفاده می‌شود. در اینجا منظور از «خصوصی» این است که پیام به صورت عمومی منتشر نمی‌شود، اما همچنان از سرور IRC عبور می‌کند و توسط مدیران شبکه IRC قابل مشاهده است. مقصد پیام با آرگومان nch مشخص می‌شود: اگر یک نام مستعار باشد، یک پیام خصوصی خواهد بود، اما اگر نام کانال باشد در آن کانال ارسال می‌شود.

پروتکل شما را ملزم نمی‌کند که برای ارسال پیام حتماً عضو کانال باشید، اما بیشتر کانال‌ها حالتی را تنظیم می‌کنند که از ارسال پیام توسط افرادی که عضو نیستند جلوگیری می‌کند.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد. این به معنای موفقیت کامل عملیات نیست. باید منتظر رویداد مربوطه یا کد خطا از طریق رویداد event_numeric بمانید.

اگر دستور موفق شود، به طور معمول رویدادی جز احتمال LIBIRC_RFC_RPL_AWAY تولید نمی‌شود.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_me

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای ارسال پیام me/ (کنش CTCP یا CTCP ACTION) به یک کانال یا به طور خصوصی به نام مستعار دیگر استفاده می‌شود. در اینجا منظور از «خصوصی» این است که پیام به طور عمومی منتشر نمی‌شود، اما همچنان از سرور IRC می‌گذرد و توسط مدیران شبکه IRC قابل مشاهده است. مقصد پیام با آرگومان nch مشخص می‌شود: اگر نام مستعار باشد پیامی خصوصی خواهد بود، و اگر نام کانال باشد در کانال ارسال خواهد شد.

پروتکل نیازی به عضویت در کانال برای ارسال پیام به آن ندارد، اما بیشتر کانال‌ها حالتی دارند که ارسال پیام توسط افراد غیرعضو را مسدود می‌کند.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور فرستاده شد.

در صورت موفقیت دستور، معمولاً هیچ رویدادی به جز احتمال LIBIRC_RFC_RPL_AWAY تولید نمی‌شود.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_notice

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای ارسال اعلان (notice) به کانال یا به صورت خصوصی به یک نام مستعار استفاده می‌شود. مقصد با آرگومان nch تعیین می‌گردد.

تنها تفاوت میان یک پیام معمولی و یک اعلان در این است که RFC صریحاً تأکید می‌کند که ربات‌های خودکار هرگز نباید به طور خودکار به NOTICE پاسخ دهند.

مقدار بازگشتی (Return value):

کد بازگشتی 0 به این معنی است که دستور با موفقیت ارسال شده است.

در صورت موفقیت دستور، معمولاً رویدادی تولید نمی‌شود مگر احتمال LIBIRC_RFC_RPL_AWAY.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_ctcp_request

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای ارسال یک درخواست CTCP استفاده می‌شود. چهار درخواست CTCP توسط بیشتر کلاینت‌های IRC پشتیبانی می‌شوند:

برخی کلاینت‌ها ممکن است از درخواست‌های دیگر نیز پشتیبانی کنند. سند RFC این درخواست‌ها را فهرست نکرده و هیچ‌گونه پشتیبانی از CTCP را اجباری ندانسته است.

اگر یک درخواست CTCP ارسال می‌کنید، مطمئن شوید که گرداننده‌ای برای event_ctcp_rep جهت پردازش پاسخ تعریف کرده‌اید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور فرستاده شد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_ctcp_reply

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای ارسال پاسخ به یک درخواست CTCP دریافت شده از رویداد event_ctcp_req استفاده می‌شود. توجه داشته باشید که این رویداد را دریافت نخواهید کرد مگر اینکه در زمان مقداردهی اولیه نشست IRC گرداننده اختصاصی خود را مشخص کرده باشید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

متفرقه: نسخه کتابخانه، داده‌های خام، تغییر نام مستعار، خروج (Miscellaneous: library version, raw data, changing nick, quitting)

irc_cmd_nick

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای تغییر نام مستعار فعلی شما به یک نام مستعار دیگر استفاده می‌شود. توجه داشته باشید که چنین تغییری همیشه ممکن نیست؛ به عنوان مثال نمی‌توانید نام مستعار خود را به یک نام مستعار موجود یا (در برخی سرورها) به یک نام مستعار ثبت‌شده تغییر دهید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_whois

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع اطلاعات مختلفی را درباره یک نام مستعار استعلام می‌کند. میزان اطلاعات به سرور IRC بستگی دارد اما معمولاً شامل نام کاربری، نام واقعی (تعریف‌شده توسط کلاینت در زمان ورود)، سرور IRC مورد استفاده، کانال‌هایی که کاربر در آن‌ها حضور دارد، زمان بی‌کاری، حالت غیبت (away) و غیره است.

مقدار بازگشتی (Return value):

کد بازگشتی 0 نشان‌دهنده ارسال موفقیت‌آمیز دستور به سرور IRC است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_cmd_quit

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description): این تابع دستور QUIT را به سرور IRC می‌فرستد. این دستور سرور IRC را وادار می‌کند تا اتصال IRC را ببندد و نشست را خاتمه دهد.

تفاوت میان این دستور و فراخوانی irc_disconnect در این است که این دستور امکان تعیین دلیل خروج را می‌دهد که به تمام کاربران حاضر در کانال‌های شما نمایش داده خواهد شد. همچنین مشخص می‌کند که شما عمداً کانال‌های IRC را ترک کرده‌اید، نه اینکه اتصال شما صرفاً قطع شده باشد.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_send_raw

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع داده‌های خام را به همان شکل به سرور IRC ارسال می‌کند. از آن برای تولید یک دستور سرور استفاده کنید که هنوز مستقیماً توسط libircclient ارائه نشده است.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور ارسال شده است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_target_get_nick

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

برای بیشتر رویدادها سرور IRC مبدأ 'origin' (یعنی شخصی که این رویداد را ایجاد کرده) را در فرمت اصطلاحاً «رایج» بازمی‌گرداند، مانند nick!host@domain. با این حال تمام توابع _irc_cmd فقط به یک نام مستعار ساده نیاز دارند. این تابع این مبدأ را تجزیه کرده و نام مستعار را استخراج می‌کند و آن را در بافر ارائه‌شده توسط کاربر ذخیره می‌نماید.

یک بافر به اندازه 128 بایت باید برای بیشتر نام‌های مستعار کافی باشد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_target_get_host

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

برای بیشتر رویدادها سرور IRC مبدأ 'origin' را به صورت رایج nick!host@domain بازمی‌گرداند. این تابع این مبدأ را تجزیه کرده و میزبان (host) را استخراج می‌کند و در بافر ارائه‌شده توسط کاربر ذخیره می‌نماید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

شروع و پذیرش نشست‌های گفتگوی DCC، ارسال و دریافت فایل‌ها (DCC initiating and accepting chat sessions, sending and receiving files)

irc_dcc_chat

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع درخواست یک DCC CHAT میان شما و کاربر دیگر IRC می‌دهد. گفتگوی DCC شبیه به گفتگوی خصوصی است اما مستقیماً بین دو کاربر برقرار می‌شود و از سرور IRC عبور نمی‌کند. درخواست DCC CHAT پیش از اینکه بتوانید چیزی ارسال کنید باید توسط طرف مقابل پذیرفته شود.

هنگامی که گفتگو پذیرفته، رد یا متوقف شود، یا داده‌ای دریافت گردد، تابع callback فراخوانی می‌شود. به طور مشخص، این فراخوانی بازگشتی زمانی صدا زده خواهد شد که:

جزئیات را در اعلان irc_dcc_callback_t ببینید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی دستور با موفقیت به سرور IRC فرستاده شد. این به معنای موفقیت قطعی عملیات نیست و باید منتظر رویداد مربوطه یا کد خطا از طریق event_numeric بمانید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_dcc_msg

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع برای ارسال پیام DCC CHAT به یک گفتگوی فعال DCC استفاده می‌شود. برای فعال بودن، درخواست DCC CHAT باید توسط یک طرف آغاز شده و توسط طرف دیگر پذیرفته شده باشد.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی موفقیت. مقدار دیگر نشان‌دهنده خطا است و کد خطا از طریق ()irc_errno قابل دریافت است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_dcc_accept

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع یک درخواست گفتگوی DCC یا انتقال فایل از راه دور را می‌پذیرد. پس از پذیرش درخواست، تابع callback برای رویدادهای بعدی DCC، از جمله خاتمه نشست DCC، فراخوانی خواهد شد. اطلاعات کال‌بک DCC را ببینید.

این تابع باید تنها پس از دریافت رویدادهای event_dcc_chat_req یا event_dcc_send_req فراخوانی شود. شما مجبور نیستید بلافاصله در تابع پردازش رویداد ()irc_dcc_accept یا ()irc_dcc_decline را صدا بزنید - می‌توانید فقط dccid را ذخیره کرده و بازگردید، و این توابع را بعداً فراخوانی کنید. اما برای جلوگیری از نشت حافظه باید ظرف ۶۰ ثانیه پس از دریافت هر درخواست ورودی DCC، یکی از این دو تابع را صدا بزنید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی موفقیت. مقادیر دیگر یعنی خطا، کد خطا را می‌توان از طریق irc_errno() دریافت کرد.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_dcc_decline

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع یک درخواست گفتگوی دوردست DCC یا انتقال فایل را رد می‌کند.

این تابع باید تنها پس از دریافت رویدادهای event_dcc_chat_req یا event_dcc_send_req فراخوانی شود. برای جلوگیری از نشت حافظه باید ظرف ۶۰ ثانیه یکی از توابع رد یا پذیرش را فراخوانی کنید.

از این تابع برای بستن اجباری نشست DCC که قبلاً پذیرفته شده یا آغاز شده است استفاده نکنید. به جای آن از irc_dcc_destroy() استفاده نمایید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی موفقیت. مقدار دیگر نشان‌دهنده خطا است و کد خطا از طریق irc_errno() قابل دریافت است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_dcc_sendfile

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع یک درخواست DCC SEND برای ارسال فایل ایجاد می‌کند. هنگامی که پذیرفته شد، فایل به طرف مقابل ارسال می‌شود و نشست DCC بسته خواهد شد. پیشرفت و نتیجه عملیات ارسال را می‌توان در کال‌بک بررسی کرد. اطلاعات کال‌بک DCC را ببینید.

مقدار بازگشتی (Return value):

کد بازگشتی 0 به این معنی است که دستور با موفقیت به سرور ارسال شده است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_dcc_destroy

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع اتصال DCC را می‌بندد (در صورت وجود)، و نشست DCC را نابود کرده و منابع استفاده‌شده را آزاد می‌نماید. می‌توان آن را در هر زمانی فراخوانی کرد، حتی از داخل کال‌بک‌ها یا از نخ‌های مختلف.

توجه داشته باشید که وقتی نشست DCC به پایان برسد (چه با موفقیت و چه با شکست)، نباید آن را دستی نابود کنید؛ این کار به طور خودکار انجام خواهد شد.

مقدار بازگشتی (Return value):

کد بازگشتی 0 یعنی موفقیت. مقدار دیگر نشان‌دهنده خطا است و کد خطا از طریق irc_errno() به دست می‌آید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

مدیریت پیام‌های رنگی (Handling the colored messages)

irc_color_strip_from_mirc

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع تمام کدهای رنگ ANSI را از پیام حذف کرده و یک پیام جدید بدون اطلاعات رنگ بازمی‌گرداند. برای ربات‌هایی که به رشته‌ها واکنش نشان می‌دهند مفید است تا در صورت استفاده رشته از رنگ‌ها دچار سردرگمی نشوند.

این تابع پیامی را که از رنگ استفاده نکرده تغییر نمی‌دهد.

مقدار بازگشتی (Return value):

پیام جدیدی را با کدهای رنگ حذف‌شده بازمی‌گرداند. توجه داشته باشید که حافظه پیام جدید با ()malloc تخصیص داده می‌شود، بنابراین وقتی دیگر استفاده نمی‌شود باید آن را با ()free آزاد کنید. اگر تخصیص حافظه ناموفق باشد، 0 برمی‌گرداند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_color_convert_from_mirc

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع تمام کدهای رنگ و گزینه‌های قالب‌بندی را به رنگ‌های داخلی libircclient تبدیل می‌کند.

مقدار بازگشتی (Return value):

اشاره‌گری به پیام جدید با کدهای رنگ ANSI و گزینه‌های قالب‌بندی تبدیل‌شده بازمی‌گرداند. برای جزئیات به راهنمای irc_color_convert_to_mirc مراجعه کنید.

توجه داشته باشید که حافظه پیام جدید با ()malloc تخصیص یافته است، بنابراین هنگام پایان استفاده باید آن را با ()free آزاد کنید. در صورت شکست تخصیص حافظه، 0 بازمی‌گرداند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_color_convert_to_mirc

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع تمام کدهای رنگ و گزینه‌های قالب‌بندی را از رنگ‌های داخلی libircclient به کدهای ANSI مورد استفاده mIRC و سایر کلاینت‌های IRC تبدیل می‌کند.

مقدار بازگشتی (Return value):

پیام جدیدی با کدهای رنگ و گزینه‌های قالب‌بندی تبدیل‌شده، یا 0 در صورت عدم امکان تخصیص حافظه برمی‌گرداند. حافظه تخصیص‌یافته با ()malloc باید با ()free آزاد شود.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

سیستم رنگ در libircclient به گونه‌ای طراحی شده که استفاده از آن آسان و بین کلاینت‌های مختلف IRC قابل‌حمل باشد. هر رنگ یا گزینه قالب‌بندی با دستورات متنی ساده داخل براکت توصیف می‌شود.

نمونه‌هایی از توالی رنگ‌ها:

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]

تغییر گزینه‌های کتابخانه (Changing the library options)

irc_get_version

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع نسخه libircclient را برمی‌گرداند. می‌توانید از نسخه برای بررسی در دسترس بودن گزینه‌های لازم یا نمایش نسخه استفاده کنید. رشته فرمت توصیه‌شده شبیه printf برای چاپ نسخه به این صورت است:

printf ("Version: %d.%02d", high, low);

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_set_ctx

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع بافت تعریف‌شده توسط کاربر را برای این نشست IRC تنظیم می‌کند. این بافت توسط libircclient استفاده نمی‌شود. هدف آن ذخیره داده‌های کاربری ویژه نشست است که ممکن است بعداً با فراخوانی irc_get_ctx به دست آید. توجه داشته باشید که libircclient فقط این اشاره‌گر را حمل می‌کند. اگر حافظه‌ای تخصیص دهید و نشانی آن را در ctx ذخیره کنید، مسئولیت آزادسازی آن قبل از فراخوانی irc_destroy_session() با خود شما است.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_get_ctx

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع بافت نشست IRC را که توسط irc_set_ctx تنظیم شده بود برمی‌گرداند.

مقدار بازگشتی (Return value):

اگر بافتی تنظیم نشده باشد، این تابع NULL برمی‌گرداند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_option_set

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع گزینه libircclient را تنظیم می‌کند و رفتار کتابخانه را تغییر می‌دهد. برای معنای هر گزینه به فهرست گزینه‌ها مراجعه کنید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

irc_option_reset

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع گزینه libircclient را بازنشانی می‌کند و رفتار libircclient را تغییر می‌دهد. برای معنای هر گزینه به فهرست گزینه‌ها مراجعه کنید.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

مدیریت خطاها (Handling the errors)

irc_errno

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع آخرین کد خطای مرتبط با آخرین عملیات این نشست IRC را بازمی‌گرداند. کدهای خطای ممکن در libirc_errors.h تعریف شده‌اند.

همانند همیشه، قواعد رایج errno اعمال می‌شوند:

مقدار بازگشتی (Return value):

کد خطا.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود. کد خطای محلی به ازای هر بافت IRC است، نه به ازای هر نخ.

irc_strerror

پیش‌نمونه (Prototype):

پارامترها (Parameters):

توضیحات (Description):

این تابع نمایش متنی کد خطای داده‌شده را بازمی‌گرداند.

مقدار بازگشتی (Return value):

یک رشته داخلی انگلیسی همراه با شرح مختصری از کد خطا بازمی‌گرداند.

امنیت نخ (Thread safety):

این تابع می‌تواند به طور همزمان از چندین نخ فراخوانی شود.

انواع داده (Types)

این بخش انواع داده‌های مختلف تعریف‌شده توسط کتابخانه را شرح می‌دهد.

irc_session_t

دستگیره نشست IRC که با فراخوانی irc_create_session() ایجاد می‌شود. اکثر فراخوانی‌های توابع کتابخانه این دستگیره را به عنوان پارامتر دریافت می‌کنند. می‌توانید به هر تعداد که مایلید دستگیره بسازید. هر دستگیره می‌تواند برای برقراری یک اتصال IRC به سرور IRC به عنوان یک کاربر منفرد استفاده شود.

هنگامی که دیگر از این دستگیره استفاده نمی‌شود، باید با فراخوانی irc_destroy_session() نابود شود.

irc_dcc_session_t

این ساختار یک نشست DCC مورد استفاده در libircclient را شرح می‌دهد. اعضای آن مربوط به بخش‌های داخلی libircclient هستند و نباید مستقیماً استفاده شوند.

irc_dcc_t

این نوع یک شناسه نشست DCC است، که برای شناسایی نشست‌های DCC در فراخوانی‌های بازگشتی و توابع مختلف استفاده می‌شود.

irc_callbacks_t

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;
}

ساختار فراخوانی‌های بازگشتی رویداد را توصیف می‌کند که در ثبت کال‌بک‌ها استفاده می‌شود.

تمام ارتباطات با شبکه IRC مبتنی بر رویدادها است. به طور کلی رویداد هر چیزی است که توسط فرد دیگری در شبکه یا توسط خود سرور IRC تولید می‌شود. «شخصی پیامی برای شما می‌فرستد»، «شخصی به کانال پیوست»، «شخصی از IRC خارج شد» - همه این پیام‌ها رویداد هستند.

هر رویداد دارای گرداننده اختصاصی خود است که هنگام دریافت رویداد مناسب فراخوانی می‌شود. شما مجبور نیستید تمام گرداننده‌های رویداد را تعریف کنید؛ فقط گرداننده‌هایی را تعریف کنید که باید آن‌ها را شنود کنید و اشاره‌گر گرداننده‌های باقی‌مانده را روی NULL قرار دهید.

این رویداد زمانی فعال می‌شود که اتصال به سرور IRC با موفقیت برقرار شده و پیام روز (MOTD) دریافت شود. بسته به سرور، ممکن است ارسال دستورات قبل از این رویداد نیز امکان‌پذیر باشد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام NICK رخ می‌دهد. زمانی اتفاق می‌افتد که یکی از کاربران (از جمله خود شما) در یکی از کانال‌هایی که نظارت می‌کنید (پیوسته‌اید) نام مستعار خود را تغییر دهد.

تغییر نام مستعار خودتان نیز این رویداد را تولید می‌کند. توجه داشته باشید که ممکن است سرور نام مستعار شما را به طور مستقل تغییر دهد، بنابراین باید این رویداد را دنبال کنید.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام QUIT فعال می‌شود. زمانی رخ می‌دهد که یکی از کاربران در یکی از کانال‌هایی که در آن حضور دارید از سرور IRC قطع اتصال کند.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت پیام JOIN فعال می‌شود. زمانی رخ می‌دهد که کاربر جدیدی به کانالی که نظارت می‌کنید (پیوسته‌اید) ملحق شود. همچنین زمانی که خودتان به کانال جدیدی بپیوندید نیز رخ می‌دهد.

توجه داشته باشید که ممکن است شما بدون ارسال دستور JOIN مجبور به پیوستن به کانال شوید (و در نتیجه این رویداد را دریافت کنید). یک حالت متداول زمانی است که ربات NickServ روی سرور طوری پیکربندی شده که شما را به صورت خودکار به کانال‌های خاصی ملحق کند.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام PART فعال می‌شود. زمانی رخ می‌دهد که کاربری کانالی را که در آن حضور دارید ترک کند. همچنین وقتی خودتان کانالی را ترک کنید رخ می‌دهد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام MODE کانال فعال می‌شود. زمانی رخ می‌دهد که شخصی حالت(های) کانالی را که در آن حضور دارید تغییر دهد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت پیام MODE کاربر فعال می‌شود. زمانی رخ می‌دهد که حالت کاربری شما تغییر کند.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت پیام TOPIC فعال می‌شود. زمانی رخ می‌دهد که شخصی موضوع کانالی را که در آن حضور دارید تغییر دهد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام KICK فعال می‌شود. زمانی رخ می‌دهد که شخصی (از جمله شما) فردی را (از جمله خود شما) از کانالی که در آن عضو هستید اخراج کند. اخراج کردن خودتان از کانال نیز امکان‌پذیر است.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت پیام PRIVMSG ارسال‌شده به کانال رخ می‌دهد. زمانی فعال می‌شود که شخصی (به جز شما) پیامی به کانال مورد نظارت ارسال کند.

پیام‌های خودتان این رویداد را فعال نمی‌کنند. با این حال سرور می‌تواند با تولید این رویداد شما را مجبور به ارسال پیام به کانال کند.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت یک پیام PRIVMSG ارسال‌شده به صورت خصوصی برای شما رخ می‌دهد. زمانی فعال می‌شود که کسی برای شما پیام فرستاده باشد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام NOTICE فعال می‌شود. این پیام مشابه PRIVMSG است. طبق RFC 1459، تنها تفاوت میان NOTICE و PRIVMSG این است که شما هرگز نباید به طور خودکار به پیام‌های NOTICE پاسخ دهید. متأسفانه این قاعده اغلب توسط خود سرورهای IRC نقض می‌شود - برای مثال، پیام‌های NICKSERV نیازمند پاسخ هستند و به عنوان NOTICE ارسال می‌شوند.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت پیام NOTICE ارسال‌شده به کانال رخ می‌دهد. این پیام مشابه PRIVMSG کانال است. طبق RFC 1459 نباید به طور خودکار به پیام‌های NOTICE پاسخ داد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت پیام INVITE فعال می‌شود. زمانی رخ می‌دهد که شخصی شما را به کانالی با حالت i+ (فقط‌دعوتی) دعوت کند.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

همچنین ببینید: irc_cmd_invite()

این رویداد پس از دریافت یک درخواست CTCP فعال می‌شود. به طور پیش‌فرض از گرداننده داخلی درخواست CTCP استفاده می‌گردد. کلاینت mIRC پیام‌های PING، FINGER، VERSION، TIME و ACTION را تولید می‌کند که در صورت عدم مدیریت این رویداد توسط برنامه شما، به طور خودکار توسط کتابخانه مدیریت و پاسخ داده می‌شوند؛ به جز پیام ACTION که رویداد event_ctcp_action را فعال می‌کند. اگر نیاز به مدیریت انواع بیشتری از پیام‌ها دارید، این گرداننده رویداد را تعریف کنید و کد مبدأ تابع libirc_event_ctcp_internal را برای نحوه نوشتن گرداننده اختصاصی بررسی نمایید. حداقل باید از CTCP PING پشتیبانی کنید تا بررسی جعل هویت برخی سرورهای IRC را پشت سر بگذارید.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پاسخ CTCP فعال می‌شود. بنابراین اگر پیام CTCP ارسال کنید و کاربر دوردست پاسخ دهد، این گرداننده رویداد فراخوانی خواهد شد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت پیام کنش CTCP ACTION فعال می‌شود. تنها زمانی فراخوانی می‌شود که گرداننده رویداد event_ctcp_req را تعریف نکرده باشید.

چنین پیام‌هایی معمولاً در کلاینت IRC به این شکل دیده می‌شوند:

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد با دریافت یک پیام ناشناخته که توسط کتابخانه مدیریت نمی‌شود فعال می‌گردد.

این رویداد از کال‌بک irc_event_callback_t با مقادیر زیر استفاده می‌کند:

این رویداد پس از دریافت هر پیام عددی از سرور فعال می‌شود. فهرست ناقصی از این پاسخ‌ها در RFC 1459 یافت می‌شود. مدیریت این رویداد برای هر کلاینت معناداری ضروری است.

این رویداد از کال‌بک اختصاصی irc_eventcode_callback_t استفاده می‌کند. مستندات کال‌بک را ببینید.

این رویداد زمانی که شخصی تلاش کند گفتگوی DCC CHAT با شما برقرار کند فعال می‌شود.

این رویداد از کال‌بک اختصاصی irc_event_dcc_chat_t استفاده می‌کند. مستندات کال‌بک را ببینید.

این رویداد زمانی فعال می‌شود که شخصی تلاش کند فایلی را از طریق DCC SEND برای شما بفرستد.

این رویداد از کال‌بک اختصاصی irc_event_dcc_send_t استفاده می‌کند. مستندات کال‌بک را ببینید.

ثوابت (Constants)

این بخش ثوابت کتابخانه مانند گزینه‌ها و کدهای خطا را شرح می‌دهد.

خطاها (Errors)

(0): بدون خطا

(1): مقدار نامعتبر برای یکی از آرگومان‌های یک تابع داده شده است. به عنوان مثال، ارسال مقدار NULL به عنوان آرگومان کانال در irc_cmd_join() این خطا را تولید می‌کند.

(2): نام میزبان ارائه‌شده برای تابع irc_connect() نتوانست به یک نشانی IP معتبر تفکیک شود.

(3): سوکت جدید نمی‌تواند ایجاد شود یا به حالت غیرمسدودکننده درآید. معمولاً به این معنی است که سرور با کمبود منابع مواجه شده یا اشکالی در libircclient وجود دارد. همچنین ببینید: چرا در Win32 هنگام استفاده از کتابخانه ایستا خطای LIBIRC_ERR_SOCKET دریافت می‌کنم؟

(4): سوکت نتوانست به سرور IRC یا بخش مقصد DCC متصل شود. معمولاً یعنی سرور IRC از کار افتاده یا نشانی آن نامعتبر است. برای DCC دلیل معمولاً فایروال رایانه شما یا رایانه مقصد است که انتقال DCC را رد می‌کند.

(5): اتصال IRC توسط سرور IRC بسته شد (که می‌تواند به این معنی باشد که یک اپراتور IRC شما را از سرور اخراج کرده است)، یا اتصال DCC توسط طرف مقابل بسته شد. معمولاً این مورد یک خطای فنی نیست.

(6): دو دلیل ممکن برای این خطا وجود دارد: اول اینکه حافظه برای استفاده داخلی libircclient تخصیص نیافت، و این خطا معمولاً مهلک است. دلیل دوم این است که بافر دستورات (که دستورات آماده ارسال به سرور IRC را صف‌بندی می‌کند) پر است و هنوز نمی‌تواند دستورات بیشتری را بپذیرد. در مورد اخیر باید کمی صبر کنید و دستور را بعداً تکرار نمایید.

(7): اتصال گفتگوی/ارسال DCC از طرف مقابل نتوانست پذیرفته شود. یا اتصال قبل از پذیرش قطع شده یا اشکالی در libircclient وجود دارد.

(9): نام فایل ارائه‌شده به irc_dcc_sendfile() نتوانست ارسال شود. یا یک فایل معمولی نیست (مثلاً یک دایرکتوری یا یک سوکت است) یا قابل خواندن نبوده است. همچنین ببینید: LIBIRC_ERR_OPENFILE

(10): یا فایل DCC قابل خواندن نبود (مثلاً در حین ارسال کوتاه شد)، یا سوکت DCC خطای خواندن برگرداند که معمولاً به این معنی است که اتصال شبکه قطع شده است.

(11): یا فایل DCC نتوانست نوشته شود (مثلاً فضای خالی روی دیسک وجود ندارد)، یا سوکت DCC خطای نوشتن برگرداند که نشان‌دهنده قطع اتصال شبکه است.

(12): تابع در زمانی فراخوانی شده که مجاز به فراخوانی نبوده است. به عنوان مثال، irc_cmd_join() پیش از برقراری اتصال به سرور IRC و قبل از فراخوانی event_connect صدا زده شده است.

(13): مهلت زمانی درخواست DCC به پایان رسید. تایمری برای هر درخواست DCC وجود دارد که اتصال، پذیرش و درخواست‌های پذیرفته‌نشده/رد‌شده DCC را ردیابی می‌کند. این تایمر روی ۶۰ ثانیه تنظیم شده است. اگر درخواست در این مدت متصل، پذیرفته یا رد نشود، با این خطا متوقف خواهد شد.

(14): فایل مشخص‌شده در irc_dcc_sendfile() باز نشد.

(15): اتصال به سرور IRC قطع شد.

(16): تابعی که نیازمند پشتیبانی IPv6 است فراخوانی شد، اما پشتیبانی IPv6 در برنامه کامپایل نشده است.

(17): اتصال SSL نیاز بود اما کتابخانه با پشتیبانی از SSL کامپایل نشده است.

(18): کتابخانه SSL نتوانست مقداردهی اولیه شود.

(19): دست‌تکانی SSL هنگام تلاش برای اتصال به سرور با شکست مواجه شد. معمولاً به این معنی است که شما سعی در استفاده از SSL روی یک پورت غیر SSL دارید.

(20): سرور از یک گواهینامه نامعتبر یا خودامضا استفاده می‌کند. از گزینه LIBIRC_OPTION_SSL_NO_VERIFY برای اتصال به آن استفاده کنید.

گزینه‌ها (Options)

در صورت تنظیم، خروجی‌های اضافی اشکال‌زدایی را فعال می‌کند که به STDOUT فرستاده می‌شوند.

در صورت تنظیم، مبدأ رویدادها را به طور خودکار پیراسته می‌کند. هر رویداد دارای یک مبدأ است که معمولاً به صورت nick!host@ircserver است. این مبدأها نمی‌توانند در دستورات IRC استفاده شوند و باید بخش میزبان و سرور جدا شود. این کار با فعال کردن این گزینه به طور خودکار انجام می‌گیرد.

به طور پیش‌فرض اتصال SSL با بررسی اینکه گواهینامه ارائه‌شده توسط یک مرجع صدور گواهی معتبر امضا شده باشد احراز هویت می‌شود. از آنجا که این موارد هزینه دارد، برخی سرورهای IRC از گواهینامه‌های خودامضا استفاده می‌کنند. این گزینه در صورت تنظیم، بررسی گواهینامه را غیرفعال می‌کند و کتابخانه هر گواهینامه‌ای را خواهد پذیرفت.

این گزینه باید پیش از فراخوانی تابع irc_connect تنظیم شود.

پرسش‌های متداول (Frequently asked questions)

چرا در Win32 هنگام استفاده از کتابخانه ایستا خطای LIBIRC_ERR_SOCKET دریافت می‌کنم؟

زیرا در Win32 باید قبل از استفاده، رابط Winsock API را مقداردهی اولیه کنید:

WSADATA wsaData;
if ( WSAStartup ( MAKEWORD (2, 2), &wsaData) != 0 )
    // گزارش خطا
// اکنون می‌توانید از libircclient استفاده کنید

شما باید این کار را فقط یک بار در برنامه خود انجام دهید، و از آنجا که libircclient نمی‌داند آیا قبلاً آن را مقداردهی کرده‌اید یا خیر، شامل هیچ کد مقداردهی اولیه Winsock نیست.

اینکه می‌گویند پروتکل IRC مبتنی بر رویداد است به چه معناست؟

خود پروتکل IRC ناهمگام و هدایت‌شده توسط سرور است. برای شما، این به معنای موارد زیر است:

چرا تابع irc_cmd_join خطا برنمی‌گرداند؟

یک نمونه معمولی این است که فراخوانی irc_cmd_join() همیشه موفقیت برمی‌گرداند حتی زمانی که تلاش می‌کنید به یک کانال دارای گذرواژه ملحق شوید. سپس مدتی بعد سرور IRC خطا را بازمی‌گرداند. این به این دلیل است که توابع خانواده _irc_cmd زمانی موفقیت را بازمی‌گردانند که دستور با موفقیت به سرور IRC فرستاده شود. ماهیت ناهمگام پروتکل IRC دریافت فوری نتیجه دستور را غیرممکن می‌سازد. لطفاً پرسش بالا را مطالعه کنید.

چگونه با NICKSERV ثبت‌نام یا احراز هویت کنیم؟

هیچ روش «استانداردی» وجود ندارد. سرویس‌های NICKSERV، CHANSERV و موارد مشابه در RFC مشخص نشده‌اند. آن‌ها افزونه‌های IRC هستند که دقیقاً مانند سایر کاربران IRC رفتار می‌کنند اما اختیارات بیشتری دارند. معمولاً پیام‌های آن‌ها از طریق رویدادهای Notice ارسال می‌شود، بنابراین می‌توانید از الگوریتم زیر برای مدیریت ثبت‌نام در Nickserv استفاده کنید:

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, "nickserv") )
                return;
        if ( strstr (params[1], "This nick is not registered") == params[1] )
        {
                sprintf (buf, "REGISTER %s NOMAIL", gCfg.irc_nickserv_password);
                irc_cmd_msg(session, "nickserv", buf);
        }
        else if ( strstr (params[1], "This nickname is registered and protected") == params[1] )
        {
                sprintf (buf, "IDENTIFY %s", gCfg.irc_nickserv_password);
                irc_cmd_msg(session, "nickserv", buf);
        }
        else if ( strstr (params[1], "Password accepted - you are now recognized") == params[1] )
                printf ("Nickserv authentication succeed.");
}

ایده اصلی، تجزیه پیام‌های ارسال‌شده از NICKSERV و واکنش مناسب به الگوهای خاص در صورت تطابق است.

پروتکل CTCP چیست؟

مخفف CTCP به عنوان "Client-to-Client Protocol" (پروتکل کارخواه به کارخواه) شناخته می‌شود. این پروتکل بین کلاینت‌های IRC برای استعلام داده‌ها از کلاینت راه دور، یا ارسال برخی اطلاعات استفاده می‌شود - به عنوان مثال، پیام‌های me/ از طریق CTCP ارسال می‌شوند.

هیچ فهرست استانداردی از درخواست‌های ممکن CTCP وجود ندارد و کلاینت‌های مختلف IRC اغلب کدهای CTCP اختصاصی خود را اضافه می‌کنند. گرداننده داخلی به پرس‌وجوهای CTCP با عنوان‌های TIME، VERSION، PING و FINGER واکنش نشان می‌دهد. اگر نیاز به واکنش به درخواست‌های دیگر دارید، باید گرداننده CTCP اختصاصی خود را بنویسید. کد منبع تابع libirc_event_ctcp_internal را بررسی کنید تا نحوه نوشتن آن را متوجه شوید.

چرا وقتی اپراتور کانال (+o) می‌شوم، event_umode را دریافت نمی‌کنم؟

تبدیل شدن به یک اپراتور کانال، حالت کانال (channel mode) را تغییر می‌دهد نه حالت کاربر را. بنابراین شما رویداد event_mode را دریافت خواهید کرد نه event_umode.

اگر رویداد event_umode را با o+ دریافت کنید، به این معنی است که حساب کاربری شما یک اپراتور سرور IRC است.

اگر برنامه من از epoll استفاده کند چه؟

این کتابخانه به دلایل تاریخی فقط مستقیماً از حلقه‌های مبتنی بر ()select پشتیبانی می‌کند، بنابراین epoll و سایر روش‌های نظرسنجی مستقیماً توسط کتابخانه پشتیبانی نمی‌شوند. اما در صورت لزوم، می‌توان آن را با تبدیل توصیف‌کننده‌ها میان select و epoll به صورت زیر شبیه‌سازی کرد:

اگرچه این کار تا حدی دشوار است، اما عملیات بسیار ساده هستند (اساساً عملیات ماسک بیتی روی یک ساختار کوچک) و هیچ افت سرعت چشمگیری به برنامه شما اضافه نخواهند کرد.

مجوز عمومی همگانی گنو کمتر جامع (GNU LESSER GENERAL PUBLIC LICENSE)

نسخه ۳، ۲۹ ژوئن ۲۰۰۷

حق نشر © ۲۰۰۷ بنیاد نرم‌افزار آزاد، <http://fsf.org>

کپی و توزیع نسخه‌های عین کلمه این سند مجوز برای همگان مجاز است، اما تغییر آن مجاز نمی‌باشد.

این نسخه از مجوز عمومی همگانی گنو کمتر جامع، شرایط و ضوابط نسخه ۳ مجوز عمومی همگانی گنو (GNU GPL) را به همراه مجوزهای اضافی ذکرشده در زیر در بر می‌گیرد.

اصطلاح «این مجوز» به نسخه ۳ مجوز عمومی همگانی گنو کمتر جامع، و «GNU GPL» به نسخه ۳ مجوز عمومی همگانی گنو اشاره دارد.

«کتابخانه» به اثر تحت پوشش این مجوز اشاره دارد، به جز برنامه‌ها یا آثار ترکیبی طبق تعاریف زیر.

یک «برنامه» هر اثری است که از رابط ارائه‌شده توسط کتابخانه استفاده می‌کند اما بر پایه کتابخانه بنا نشده باشد. تعریف یک زیرکلاس از کلاسی که توسط کتابخانه تعریف شده حالتی از استفاده از رابط تلقی می‌شود.

یک «اثر ترکیبی» اثری است که از ترکیب یا پیوند دادن یک برنامه با کتابخانه تولید شده باشد. نسخه خاصی از کتابخانه که اثر ترکیبی با آن ایجاد شده «نسخه پیوند‌یافته» نامیده می‌شود.

«سورس حداقلی متناظر» برای یک اثر ترکیبی به معنای سورس متناظر برای اثر ترکیبی است، به استثنای هرگونه کد منبع برای بخش‌هایی از اثر ترکیبی که به صورت مجزا بر پایه برنامه باشند نه بر پایه نسخه پیوندیافته.

«کد متناظر برنامه» برای اثر ترکیبی به معنی کد شیء و/یا کد منبع برنامه است، شامل تمام داده‌ها و برنامه‌های کمکی لازم برای بازتولید اثر ترکیبی از برنامه، اما بدون احتساب کتابخانه‌های سیستمی اثر ترکیبی.

1.

استثنای بخش ۳ از GNU GPL.

شما می‌توانید یک اثر تحت پوشش را تحت بخش‌های ۳ و ۴ این مجوز بدون پایبندی به بخش ۳ از GNU GPL منتقل کنید.

2.

انتقال نسخه‌های تغییریافته.

اگر نسخه‌ای از کتابخانه را تغییر دهید و در تغییرات شما، یک امکان به تابع یا داده‌ای ارائه‌شده توسط برنامه‌ای که از آن استفاده می‌کند رجوع نماید، می‌توانید نسخه‌ای از نسخه تغییریافته را منتقل کنید:

شکل کد شیء یک برنامه ممکن است مطالبی از فایل سرآیند کتابخانه را در خود جای دهد. شما می‌توانید چنین کد شیئی را تحت شرایط انتخابی خود منتقل کنید، مشروط بر اینکه اگر مطالب وارد شده محدود به پارامترهای عددی، جانمایی ساختار داده و توابع دسترسی، یا ماکروهای کوچک، توابع درون‌خطی و الگوها (ده خط یا کمتر) نباشد، هر دو مورد زیر را رعایت کنید:

شما می‌توانید یک اثر ترکیبی را تحت شرایط انتخابی خود منتقل کنید که مجموعاً تغییری در بخش‌های کتابخانه موجود در اثر ترکیبی و مهندسی معکوس برای اشکال‌زدایی چنین تغییراتی را محدود نکند، مشروط بر اینکه هر یک از موارد زیر را نیز انجام دهید:

شما می‌توانید امکانات کتابخانه را که اثری بر پایه کتابخانه است در کنار سایر امکاناتی که تحت پوشش این مجوز نیستند در یک کتابخانه واحد قرار دهید و تحت شرایط انتخابی خود منتقل کنید، مشروط بر اینکه نسخه بدون ترکیب را نیز تحت شرایط این مجوز ارائه دهید و اطلاعیه برجسته‌ای همراه آن درج نمایید.

بنیاد نرم‌افزار آزاد ممکن است نسخه‌های بازبینی‌شده یا جدیدی از مجوز عمومی همگانی گنو کمتر جامع را منتشر کند. چنین نسخه‌های جدیدی از نظر روح کلی شبیه به نسخه فعلی خواهند بود، اما ممکن است در جزئیات برای رفع مشکلات جدید تفاوت‌هایی داشته باشند.

نمایه‌ها و جدول‌ها (Indices and tables)