کتابخانه انتقال داده cURL

cURL چیست؟

cURL یک ابزار خط فرمان یا اسکریپت برای دریافت(downloading) یا ارسال داده (uploading) شامل فایل‌ها توسط قواعد URL است. بخش اول و دوم نام cURL، بخاطر سمت کاربر (client-side) بودن و استفاده از URL برای انتقال داده گرفته شده است. این ابزار در ماشین، TV، روتر، پرینتر، تجهیزات صوتی، گوشی موبایل، تبلت در هزاران نرم افزار کاربری بعتوان موتور انتقال داده است.

cURL از POP3S ,RTMP ,RTMPS ,RTSP ,SCP ,SFTP ,SMB ,SMBS ,SMTP ,SMTPS ,TELNET و TFTP پشتیبانی می‌کند. همچنبن از گواهی‌های SSL ،HTTP POST ,HTTP PUT و آپلود FTP، آپلود برپایه فرم HTTP و proxies HTTP/2 ,HTTP/3، کوکی‌ها، احراز هویت با نام‌کاربری+رمزعبور (Basic ,Plain ,Digest ,CRAM-MD5 SCRAM-SHA ,NTLM ,Negotiate و Kerberos)، انتقال فایل با قابلیت از سرگیری، پروکسی tunneling و بیشتر پشتیبانی نیز می‌کند.

دو بخش اصلی cURL

ابزار خط فرمان curl
کتابخانه libcurl انتقال داده با رابط کاربری C

استفاده از cURL در خط فرمان

ساده ترین روش استفاده از cURL، به سادگی با تایپ دستور curl و سپس URL هدف است، که خروجی اطلاعات متنی سایت را برای شما نمایش خواهد داد:

 curl www.example.com

استفاده از libcurl

ابتدا باید یک easy handle ایجاد شود. این ساختار یک transfer را مدیریت می‌کند.

CURL *easy_handle = curl_easy_init();

سپس باید option ها را برای کنترل transfer تنظیم کنید. تنظیم URL توسط آرگومان CURLOPT_URL مربوط به تابع curl_easy_setopt انجام می‌شود:

curl_easy_setopt(easy_handle, CURLOPT_URL, “http://example.com/”);

دقت کنید که easy_handle (ساختار تعریف شده‌ی cURL) بعنوان آرگومان اول و CURLOPT_URL بعنوان آرگومان دوم هستند. تابع ()curl_easy_setopt در صورتی که CURLE_OK را برگرداند، تنظیم با موفقیت ذخیره شده است. CURLE_OK یکی از کدهای خطای libcurl بوده و به معنی اتمام فرآیند با موفقیت است.

ساخت easy_handle و تنظیم option ها بر روی آن، باعث هیچ انتقال داده‌ای نمی‌شود. غیر از آنکه کتابخانه libcurl موارد تنظیم شده‌ی شما را برای استفاده‌ی بعدی که انتقال داده انجام شود، ذخیره می‌کند. اگر که curl_easy_setopt خطایی برای شما صادر نکرد، به این معنی نیست که ورودی صحیح و معتبر بوده است. ممکن است بعداً خطایی دریافت کنید. برای اطلاعات بیشتر به easy options مراجعه کنید.

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

هنگامی که ارتباط در جریان است، libcurl توابع ویژه‌ای به نام callback ها را فراخوانی کرده تا داده‌ای تحویل، خوانده یا روندی را انجام دهد.

بعد از اتمام ارتباط easy_handle، می‌توانید بفهمید که آیا موفق‌شده‌است یا نه و آمار و اطلاعات دیگر را که حین ارتباط توسط libcurl از easy_handle گردآوری شده را استخراج کنید. برای اینکار Post transfer info بررسی کنید.

ساختار easy_handle به گونه ای طراحی شده است که قابلیت استفاده مجدد داشته باشد. وقتی یک ارتباط به اتمام برسد، میتوانید بلافاصله ارتباط جدید را شروع کنید. تمام option ها در easy_handle تا زمانی که بخواهید آنها را تغییر دهید یا ()curl_easy_reset را فراخوانی کنید، باقی خواهند ماند. به زبان ساده شما در ارتباط دوم همان option های تنظیم شده را دوباره استفاده خواهید کرد.

راه اندزای ارتباط cURL

کتابخانه libcurl، سه روش مختلف برای برقراری ارتباط فراهم میکند:

روش easy – امکان برقراری یک ارتباط به صورت همزمان انجام دهید. کتابخانه libcurl تمام ارتباط را انجام داده و کنترل را به برنامه اصلی شما (زمانی که به پایان رسید) برمیگرداند (successful یا failed).
روش multi – برای مواقعی است که مایل به برقراری بیشتر از یک ارتباط یا یک ارتباط non-blocking باشید.
روش multi_socket – یک ارتباط مبتنی بر رویداد است و این API پیشنهادی برای استفاده در صورتی که قصد دارید تعداد انتقال‌های همزمان را به صدها یا هزاران یا بیشتر افزایش دهید.

راه اندزای ارتباط cURL با روش easy

نام easy، برای این انتخاب شده است که واقعا نشان دهد این روش ساده ترین نوع ارتباط libcurl است، البته چندین محدودیت دارد، بعنوان مثال فقط یک ارتباط را مدیریت کرده و تمام ارتباط را با یک فراخوانی تابع انجام داده و یک خروجی برمیگرداند.

res = curl_easy_perform( easy_handle );

اگر سرعت سرور کند است، اگر حجم داده‌ی ارتباط زیاد است یا اگر وقفه‌های زمانی ناخوشایند در شبکه یا موارد مشابه دارید، این تابع میتواند ارتباط طولانی مدت را ادامه ندهد. میتوانید با تعیین timeout توسط CURLOPT_TIMEOUT بیش از N ثانیه امکان ادامه ارتباط را ندهید:

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout);

اگر میخواهید برنامه شما فرآیند دیگری را حین کار ارتباط libcurl با روش easy انجام دهد، میتوانید از چندین thread استفاده کنید. در حالی که اگر بخواهید چندین ارتباط با روش easy را همزمان داشته باشید باید هر ارتباط را در thread جداگانه انجام دهید.

استفاده مجدد از ارتباط

کتابخانه libcurl یک آرشیو از ارتباط قدیمی را به صورت آماده نگه میدارد. بنابرین به جای ایجاد ارتباط جدید امکان استفاده از ارتباط قبلی مزایای قابل توجهی در سرعت و منابع مورد نیاز ارائه میدهد.

هنگام استفاده از روش easy یا ()curl_easy_perform، کتابخانه libcurl آرشیو ارتباط وابسته به easy_handle را برای استفاده مجدد ارتباط نگهداری می‌کند.

توابع Callback کتابخانه libcurl

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

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

توابع Callback نوع Write

تابع Callback، نوع Write توسط CURLOPT_WRITEFUNCTION تنظیم میشود:

curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_callback);

تابع write_callback بایستی مطابق با نمونه اولیه زیر باشد:

size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);

این تابع Callback، زمانی توسط libcurl فراخوانی میشود که داده‌ای دریافت شده و نیاز به ذخیره‌ی آن باشد.

اشاره گر ptr به داده‌ی دریافت شده دارد،
اندازه داده، ضرب size در nmemb است.
در صورتی که تابع Callback تعریف نشده باشد، کتابخانه libcurl به صورت پیش فرض از fwrite استفاده می‌کند.
تابع Callback نوع Write، نباید هیچ فرضی برای داده‌های دریافتی داشته باشد. ممکن است یک یا هزاران بایت باشد. حداکثر مقدار داده‌ در فایل هدر curl.h در تعریف CURL_MAX_WRITE_SIZE (پیش‌فرض 16KB) ذخیره شده است. اگر CURLOPT_HEADER برای این انتقال فعال باشد، که باعث می‌شود داده‌های header نیز به Callback نوع Write ارسال شوند، می‌توانید تا CURL_MAX_HTTP_HEADER بایت از داده‌های header را دریافت کنید. این معمولاً به مقدار 100KB است.
در صورتی که ارتباط خالی باشد، این تابع به تعداد 0 عدد داده فراخوانی می‌شود.
داده های منتقل شده به این تابع با منتهی به zero نیستند، به این معنی که نمی توان توسط تابع printf با اپراتور s% چاپ شوند.
تابع Callback باید تعداد بایت های واقعی را برگشت دهد، اگر مغایرتی وجود داشته باشد، یک خطا را نمایش میدهد و کتابخانه libcurl باید CURLE_WRITE_ERROR را برگشت دهد.
اشاره گر وارد شده به Callback در آرگومان userdata، توسط CURLOPT_WRITEDATA تنظیم شده است: