Skip to content

Latest commit

 

History

History
841 lines (560 loc) · 30.4 KB

readme.ar.md

File metadata and controls

841 lines (560 loc) · 30.4 KB

HTTP

[English]

مكتبة لإنشاء خوادم بروتوكول نقل النص الفائق (HTTP) بلغة الأسس. تعتمد هذه المكتبة هلى مكتبة civetweb.

الإضافة إلى المشروع

أضف المكتبة لمشروعك باستخدام مدير الحزم:

اشمل "مـحا"؛
مـحا.اشمل_ملف("Alusus/Http"، "بـننف.أسس")؛

import "Apm.alusus";
Apm.importFile("Alusus/Http");

مثال

اشمل "مـتم/طـرفية.أسس"؛
اشمل "مـتم/نـص.أسس"؛
اشمل "مـتم/ذاكـرة.أسس"؛
اشمل "مـحا"؛
مـحا.اشمل_ملف("Alusus/Http"، "بـننف.أسس")؛

وحدة أخـتبار_الوحدة {
    استخدم مـتم؛

    دالة ابدا() {
        // نقوم بتعريف متغير من النمط مؤشر على سـياق بحيث يمثل السياق الخاص بالسيرفر
        // تم إنشاء السيرفر لينفذ التابع المعطى على المنفذ 8080
        عرف سياق: مؤشر[بـننف.سـياق] = بـننف.شغل_الخادم(طلب_المنادى~مؤشر, "8080")؛

        طـرفية.اطبع("شُغّل الخادم على المنفذ 8080.\جhttp://localhost:8080\جاضغط زر الإدخال لإغلاق الخادم.")؛
        // ننتظر أن يقوم المستخدم بالضغط على أي زر لإيقاف السيرفر
        طـرفية.أدخل_محرفا()؛
        // عندما نصل هنا يكون المستخدم قد ضغط على زر ما
        // بالتالي نقوم بإغلاق السيرفر
        بـننف.أوقف_الخادم(سياق)؛
        طـرفية.اطبع("أغلق الخادم.\جاضغط زر الإدخال للخروج.")؛
        طـرفية.أدخل_محرفا()؛
    }

    // الدالة التي سيقوم السيرفر بتنفيذها
    دالة طلب_المنادى (اتصال: مؤشر[بـننف.اتـصال]): صحيح{
        // نفوم بتعريف المتغير اللازم لتخزين معلومات الطلب الخاص بالاتصال المعطى
        عرف معلومات_الطلب: مؤشر[بـننف.مـعلومات_الطلب] = بـننف.هات_معلومات_الطلب(اتصال)؛
        // نقوم بتعريف متغير لتخزين المحتوى
        عرف سياق: مصفوفة[محرف, 1024]؛

        // نفوم بتهيئة المحتوى بكود html بسيط
        نـص.عيّن(
            سياق~مؤشر, "<div dir=rtl><h1>مرحبًا بك في خادم ب.ن.ن.ف للغة الأسس</h1><p>أنت الآن تتصفح \"%s\"</p></div>",
            معلومات_الطلب~محتوى.المعرف_المحلي
        )؛

        // نقوم بكتابة بيانات عبر الاتصال المعطى
        // هذه البيانات تمثل بعض المعلومات عن الطلب بالإضافة للمحتوى
        بـننف.اطبع(اتصال, "HTTP/1.1 200 OK\r\n")؛
        بـننف.اطبع(اتصال,  "Content-Type: text/html; charset=utf-8\r\n")؛
        بـننف.اطبع(اتصال,  "Content-Length: %d\r\n\r\n", نـص.هات_الطول(سياق~مؤشر))؛
        بـننف.اطبع(اتصال, سياق~مؤشر)؛

        أرجع 1؛
    }
}

أخـتبار_الوحدة.ابدا()؛

import "Srl/Console.alusus";
import "Srl/String.alusus";
import "Srl/Memory.alusus";
import "Apm.alusus";
Apm.importFile("Alusus/Http");

module TestModule {
    use Srl;

    func start() {
        
        // نقوم بتعريف متغير من النمط مؤشر على سـياق بحيث يمثل السياق الخاص بالسيرفر
        // تم إنشاء السيرفر لينفذ التابع المعطى على المنفذ 8080
        def context: ptr[Http.Context] = Http.startServer(callbackRequest~ptr, "8080");

        Console.print("Server is listening on port 8080\nhttp://localhost:8080/\nPress enter to close server.");
        // ننتظر أن يقوم المستخدم بالضغط على أي زر لإيقاف السيرفر
        Console.getChar();
        // عندما نصل هنا يكون المستخدم قد ضغط على زر ما
        // بالتالي نقوم بإغلاق السيرفر
        Http.stopServer(context);

        Console.print("Server closed.\nPress enter to exit.");
        Console.getChar();
    };

    // الدالة التي سيقوم السيرفر بتنفيذها
    func callbackRequest(connection: ptr[Http.Connection]): Int {
        // نفوم بتعريف المتغير اللازم لتخزين معلومات الطلب الخاص بالاتصال المعطى
        def requestInfo: ptr[Http.RequestInfo] = Http.getRequestInfo(connection);
        // نقوم بتعريف متغير لتخزين المحتوى
        def content: array[Char, 1024];

        // نفوم بتهيئة المحتوى بكود html بسيط
        String.assign(content~ptr, "<h1>Welcome from Alusus</h1><p> you are in \"%s\"", requestInfo~cnt.localUri);

        // نقوم بكتابة بيانات عبر الاتصال المعطى
        // هذه البيانات تمثل بعض المعلومات عن الطلب بالإضافة للمحتوى
        Http.print(connection, "HTTP/1.1 200 OK\r\n");
        Http.print(connection, "Content-Type: text/html\r\n");
        Http.print(connection, "Content-Length: %d\r\n\r\n", String.getLength(content~ptr));
        Http.print(connection, content~ptr);

        return 1;
    };
};

TestModule.start();

الأصناف والوظائف

سـياق (Context)

صنف سـياق {
    عرف علم_التوقف: صحيح؛
}

class Context{
    def stopFlag: int;
};

يُستعمل هذا الصنف لتخزين المعلومات الخاصة بالسياق.

علم_التوقف (stopFlag): يحدد إن كان يجب إيقاف حلقة الأحداث.

مـناديات (Callbacks)

صنف مـناديات {
    عرف بداية_الطلب: منادى_الطلب؛
    عرف نهاية_الطلب: مؤشر[دالة(اتصال:مؤشر[اتصال]، رمز_حالة_الرد: صحيح): صحيح]؛
    عرف تسجيل_رسالة: مؤشر[دالة(اتصال:مؤشر[اتصال]، رسالة: مؤشر[محرف]): صحيح]؛
    عرف تسجيل_ولوج: مؤشر[دالة(اتصال:مؤشر[اتصال]، رسالة: مؤشر[محرف]): صحيح]؛
    عرف تهيئة_طما:مؤشر[دالة(سياق_طما:مؤشر[فراغ]، بيانات_المستخدم: مؤشر[فراغ]): صحيح]؛
    عرف غلق_الاتصال: مؤشر[دالة(اتصال:مؤشر[اتصال]): فراغ]؛
    عرف خطأ_بننف: مؤشر[دالة(اتصال:مؤشر[اتصال]، الحالة: صحيح، رسالة: مؤشر[مصفوفة[محرف]]): صحيح]؛
    عرف تهيئة_السياق: مؤشر[دالة(سياق:مؤشر[سياق]): فراغ]؛
    عرف نهاية_السياق: مؤشر[دالة(سياق:مؤشر[سياق]): فراغ]؛
    عرف تهيئة_الموضوع: مؤشر[دالة(سياق:مؤشر[سياق]، نمط_المسلك: صحيح): فراغ]؛
}

class Callbacks{
    def beginRequest: RequestCallback;
    def endRequest: ptr[func (connection: ptr[Connection], replyStatusCode: Int)];
    def logMessage: ptr[func (connection: ptr[Connection], message: CharsPtr): Int];
    def logAccess: ptr[func (connection: ptr[Connection], message: CharsPtr): Int];
    def initSsl: ptr[func (sslContext: ptr[Void], userData: ptr[Void]): Int];
    def connectionClose: ptr[func (connection: ptr[Connection]): Void];
    def httpError: ptr[func (connection: ptr[Connection], status: Int, msg: ptr[array[Char]]): Int];
    def initContext: ptr[func (context: ptr[Context]): Void];
    def exitContext: ptr[func (context: ptr[Context]): Void];
    def initThread: ptr[func (context: ptr[Context], threadType: Int): Void];
};

يحتوي هذا الصنف على المناديات الأساسية التي يمكن استعمالها مع بروتوكول ب.ن.ن.ف

كل منادى هو مؤشر إلى دالة يستدعيها السيرفر.

بداية_الطلب (beginRequest): يستدعيها الخادم عند بدء طلب ما.

القيمة المرجعة:

  • 0 في حال لم يتم معالجة الطلب.

  • 1 ~ 99 المكتبة تترك عملية معالجة الطلب للدالة.

نهاية_الطلب (endRequest): يُستدعى عند إنهاء الطلب على اتصال معين وبرمز حالة رد معين.

تسجيل_رسالة (logMessage): يستعمل لتسجيل رسالة معينة على اتصال معين.

القيمة المرجعة:

  • 0: يتم استعمال الروتين المعتاد لتسجيل الرسائل.

  • قيمة غير صفرية: يتم اعتبار أن تسجيل الرسائل قد تم ولا يتم تسجيل رسائل أخرى.

تسجيل_ولوج (logAccess): يستعمل لتسجيل رسالة على اتصال معين لتوضيح حالة الوصول.

القيمة المرجعة:

  • 0 يتم استعمال الروتين المعتاد لتسجيل رسائل الوصول.

  • قيمة غير صفرية يتم اعتبار أن تسجيل رسائل الوصول قد تم و لا يتم تسجيل رسائل أخرى

تهيئة_طما (initSsl): يُستدعى عند تهيئة بروتوكول طبقة المقابل الآمنة (SSL).

القيمة المرجعة:

  • 0 يجب على المكتبة إعداد شهادة ط.م.آ.

  • 1 تم إعداد الشهادة ولا حاجة للمكتبة للقيام بذلك.

  • -1 حدث خطأ أثناء تهيئة الطما

غلق_الاتصال (connectionClose): يُستدعى عند إغلاق اتصال.

خطأ_بننف (httpError): يستدعى عند حصول خطأ على اتصال ما مع الحالة ورسالة توضح الخطأ.

القيمة المرجعة:

  • 0 في حال قامت الدالة بإرسال صفحة الخطأ بنفسها.

  • قيمة غير صفرية في حال لم يتم إرسال صفحة الخطأ من قبل الدالة و بالتالي يقوم السيرفر بذلك

تهيئة_السياق (initContext): يُستدعى لتهيئة السياق المستعمل في مسلك ما.

نهاية_السياق (exitContext): يُستدعى عند إنهاء سياق.

تهيئة_الموضوع (initThread) يُستدعى لتهيئة مسلك بسياق ما مع تحديد نمط المسلك.

مـعلومات_الطلب (RequestInfo)

صنف مـعلومات_الطلب {
    عرف طريقة_الطلب: مؤشر[محرف]؛
    عرف معرف_الطلب: مؤشر[محرف]؛
    عرف المعرف_المحلي: مؤشر[محرف]؛
    عرف إصدار_بننف: مؤشر[محرف]؛
    عرف نص_الاستعلام: مؤشر[محرف]؛
    عرف المستخدم_البعيد: مؤشر[محرف]؛
    عرف العنوان_البعيد: مصفوفة[محرف، 48]؛
    عرف طول_المحتوى: صحيح[64]؛
    عرف المنفذ_البعيد: صحيح؛
    عرف مشفر: صحيح؛
    عرف بيانات_المستخدم: مؤشر[فراغ]؛
    عرف بيانات_الاتصال: مؤشر[فراغ]؛
    عرف عدد_الترويسات: صحيح؛
    عرف ترويسات_بننف: مصفوفة[ترويسة، 64]؛
}

class RequestInfo {
    def requestMethod: CharsPtr;
    def requestUri: CharsPtr;
    def localUri: CharsPtr;
    def httpVersion: CharsPtr;
    def queryString: CharsPtr;
    def remoteUser: CharsPtr;
    def remoteAddr: array[Char, 48];
    def contentLength: Int[64];
    def remotePort: Int;
    def isSsl: Int;
    def userData: ptr[Void];
    def connData: ptr[Void];
    def numberHeaders: Int;
    def httpHeaders: array[Header, 64];
};

يستعمل هذا الصنف لتخزين المعلومات الأساسية عن طلب ما.

طريقة_الطلب (requestMethod): نوع الطلب المستخدم مثلاً: GET.

معرف_الطلب (requestUri): الرابط الذي نرسل عليه الطلب.

المعرف_المحلي (localUri): الرابط المحلي للطلب، يمكن استعماله مع من أجل الطلبات ضمن نفس الخادم.

إصدار_بننف (httpVersion): نسخة البروتوكول المستعمل في هذا الطلب.

نص_الاستعلام (queryString): بارامترات الطلب الموجودة في الرابط.

المستخدم_البعيد (remoteUser): المستخدم البعيد الذي نتعامل معه.

العنوان_البعيد (remoteAddr): عنوان ال IP للمستخدم البعيد.

طول_المحتوى (contentLength): طول جسم الطلب مقدراً بالبايت، و يكون -1 في حال لم يكن الطول محدداً.

المنفذ_البعيد (remotePort): المنفذ المستعمل على جهاز المستخدم البعيد.

مشفر (isSsl): هل الاتصال مشفر بتقنية ط.م.آ؟

بيانات_المستخدم (userData): بيانات خاصة بالمستخدم,

بيانات_الاتصال (connData): بيانات خاصة بالاتصال.

عدد_الترويسات (numberHeaders): عدد ترويسات الطلب,

ترويسات_بننف (httpHeaders): الترويسات الخاصة بالطلب.

تـرويسة (Header)

صنف تـرويسة {
    عرف اسم: مؤشر[محرف]؛
    عرف قيمة: مؤشر[محرف]؛
}

class Header {
    def name: CharsPtr;
    def value: CharsPtr;
};

يستعمل هذا الصنف لتخزين بيانات ترويسة للطلب.

اسم (name): اسم الترويسة، و هي بمثابة مفتاح.

قيمة (value): قيمة الترويسة و هي بمثابة القيمة المخزنة بهذا المفتاح.

اتـصال (Connection)

صنف اتـصال {
    عرف معلومات_الطلب: مؤشر[مـعلومات_الطلب]؛
    عرف سياق: مؤشر[سـياق]؛
    عرف طما: مؤشر؛
    عرف سياق_طما_للعميل: مؤشر؛
    عرف عميل: مؤشر؛
    عرف موعد_الاتصال: صحيح؛
    عرف وقت_الطلب: صحيح؛
    عرف عدد_البايت_المرسلة: صحيح[64]؛
    عرف حجم_المحتوى: صحيح[64]؛
    عرف المحتوى_المستهلك: صحيح[64]؛
    عرف مقطع: صحيح؛
    عرف باقي_التقطيع: كلمة[64]؛
    عرف صوان: مؤشر[محرف]؛
    عرف معلومات_المسار: مؤشر[محرف]؛
    عرف يجب_الاغلاق: صحيح؛
    عرف معالج_الاخطاء: صحيح؛
    عرف خطأ_داخلي: صحيح؛
    عرف حجم_الصوان: صحيح؛
    عرف حجم_الطلب: صحيح؛
    عرف حجم_البيانات: صحيح؛
    عرف رمز_الحالة: صحيح؛
    عرف خنق: صحيح؛
    عرف آخر_وقت_خنق: صحيح؛
    عرف آخر_بايتات_خنق: صحيح[64]؛
    عرف قفل_المزامنة: صحيح[64]؛
}

class Connection {
    def requestInfo: ptr[RequestInfo];
    def context: ptr[Context];
    def ssl: ptr;
    def clientSslContext: ptr;
    def client: ptr;
    def connectionBirthTime: Int;
    def requestTime: Int;
    def numberBytesSent: int[64];
    def contentLen: int[64];
    def consumedContent: int[64];
    def isChunked: int;
    def chunkRemainder: word[64];
    def buf: CharsPtr;
    def pathInfo: CharsPtr;
    def mustClose: int;
    def inErrorHandler: int;
    def internalError: int;
    def bufSize: int;
    def requestLen: int;
    def dataLen: int;
    def statusCode: int;
    def throttle: int;
    def lastThrottleTime: int;
    def lastThrottleBytes: int[64];
    def mutex: int[64];
};

يستعمل هذا الصنف لتخزين المعلومات المختلفة عن الاتصال.

معلومات_الطلب (requestInfo): معلومات الطلب المرافق للاتصال.

سياق (context): معلومات السياق المستعمل في هذا الاتصال.

طما (ssl): واصف بروتوكول ط.م.ا.

سياق_طما_للعميل (clientSslContext): السياق الخاص بالمستخدم وفق بروتوكول ط.م.ا.

عميل (client): العميل المتصل عبر هذا الاتصال.

موعد_الاتصال (connectionBirthTime): الوقت الذي تم فيه إنشاء الاتصال.

وقت_الطلب (requestTime): الوقت الذي تم فيه إنشاء الاتصال بالنسبة لوقت الخادم.

عدد_البايت_المرسلة (numberBytesSent): عدد البايتات التي تم إرسالها إلى العميل.

حجم_المحتوى (contentLen): قيمة الترويسة حجم_المحتوى.

المحتوى_المستهلك (consumedContent): عدد بايتات المحتوى التي تم قراءتها.

مقطع (isChunked): هل تم تقطيع النقل، يأخذ القيم التالية:

  • 0 في حال لم يكن النقل مقطع

  • 1 في حال كان النقل مقطع و يوجد بيانات لقراءتها

  • 2 في حال كان النقل مقطع و تم الانتهاء من قراءة كل البيانات

باقي_التقطيع (chunkRemainder): البيانات التي لم يتم قراءتها بعد من آخر مقطع.

صوان (buf): صوان يستعمل من أجل البيانات التي يتم تلقيها.

معلومات_المسار (pathInfo): المعلومات الخاصة بالمسار ضمن الرابط.

يجب_الاغلاق (mustClose): هل يجب إغلاق الاتصال.

معالج_الاخطاء (inErrorHandler): هل تتم معالجة الأخطاء؟

خطأ_داخلي (internalError): هل حدث خطأ أثناء معالجة الطلب؟

حجم_الصوان (bufSize): حجم الصوان.

حجم_الطلب (requestLen): الحجم الكلي بالبايتات للطلب بالإضافة للترويسات ضمن الصوان.

حجم_البيانات (dataLen): الحجم الكلي بالبايتات للبيانات ضمن الصوان.

رمز_الحالة (statusCode): رمز الحالة للرد ضمن بروتوكول ب.ن.ن.ف.

خنق (throttle): قيمة الخنق.

آخر_وقت_خنق (lastThrottleTime): آخر وقت تم إرسال فيه بيانات مخنوقة.

آخر_بايتات_خنق (lastThrottleBytes): البايتات التي تم إرسالها في هذه الثانية.

قفل_المزامنة (mutex): يمكن استعمالها لقفل الاتصال من أجل الوصول المتزامن الآمن.

شغل_الخادم (startServer)

@تصدير[mg_start]
دالة شغل_الخادم(مناديات: مؤشر[مـناديات]، بيانات_المستخدم: صـحيح، خيارات: مؤشر[مـؤشر_محارف]): مؤشر[سـياق]؛

@expname[mg_start]
func startServer(callbacks: ptr[Callbacks], user_data: Int, options: ptr[CharsPtr]): ptr[Context];

تستخدم هذه الدالة لتهيئة الخادم و تشغيله.

آلية عمل الخادم الذي سيتم إنشاءه يتم التحكم بها عن طريق مجموعة من المناديات و مجموعة من الخيارات التي يمكن للمستخدم إعطاؤها للدالة.

في حال كان أحد المناديات غير موجود، أي يشير إلى لاشيء، فيتم استبداله بمنادي افتراضي من قبل الخادم.

المعطيات:

مناديات (callbacks): المناديات التي يمكن عن طريقها تحديد آلية عمل الخادم في حالات مختلفة و كيفية معالجته للطلبات.

بيانات_المستخدم (user_data): بيانات مستخدم اختيارية.

خيارات (options): عدد من الخيارات التي يتم استعمالها لتهيئة الخادم.

القيمة المرجعة:

مؤشر إلى السياق المرتبط بالخادم أو مؤشر إلى لاشيء في حال فشل إنشاء الخادم.

دالة  شغل_الخادم(منادي: مـنادى_الطلب، خيارات: سند[مـتم.مـصفوفة[مؤشر[مـحرف]]]): مؤشر[سـياق]؛

func startServer (callback: RequestCallback, options: ref[Srl.Array[CharsPtr]]): ptr[Context];

المعطيات:

منادي (callback): المنادي الذي يقوم الخادم بتنفيذه.

خيارات (options): خيارات خاصة بالخادم مثل المنفذ الذي سيستمع إليه الخادم.

دالة  شغل_الخادم(منادي: مـنادى_الطلب، عدد_الخيارات: صـحيح، خيارات: ...مؤشر[محرف]): مؤشر[سـياق]؛

func startServer (callback: RequestCallback, optsCount: Int, opts: ...CharsPtr): ptr[Context];

المعطيات:

منادي (callback): المنادي الذي يقوم الخادم بتنفيذه.

عدد_الخيارات (optsCount): عدد الخيارات التي نريد ضبطها على هذا الخادم.

خيارات (opts): خيارات خاصة بالسيرفر مثل المنفذ الذي سيستمع إليه السيرفر.

دالة  شغل_الخادم(منادي: مـنادى_الطلب، منفذ: مؤشر[محرف]): مؤشر[سـياق]؛

func startServer(callback: RequestCallback, port: CharsPtr): ptr[Context];

منادي (callback): المنادي الذي يقوم السيرفر بتنفيذه.

منفذ (port): المنفذ الذي سيستمع إليه السيرفر.

أوقف_الخادم (stopServer)

دالة أوقف_الخادم(سياق: مؤشر[سـياق])؛

@expname[mg_stop]
func stopServer(context: ptr[Context]);

تستعمل هذه الدالة لإيقاف الخادم وتحرير أي موارد كان يستعملها، تنتظر هذه الدالة حتى يتم إنهاء كل المسالك التي يتم تنفيذها و بعدها يقوم بتحرير الموارد و إغلاق الخادم.

المعطيات:

سياق (context): مؤشر إلى السياق الخاص بالخادم الذي نريد إغلاقه.

اقرأ (read)

دالة اقرأ(اتصال: مؤشر[اتـصال]، صوان: مؤشر، حجم_صوان: صحيح): صحيح؛

@expname[mg_read]
func read(connection: ptr[Connection], buffer: ptr, bufferSize: Int): Int;

تقوم هذه الدالة بقراءة البيانات من الاتصال المشار إليه عن طريق اتصال.

يتم التعامل مع البيانات على أنها بيانات ثنائية و يتم تخزينها في الصوان المشار إليه من قبل صوان.

المعطيات:

اتصال (connection): مؤشر إلى الاتصال المراد قراءة البيانات منه.

صوان (buffer): مؤشر إلى الصوان الذي نريد تخزين البيانات فيه.

حجم_صوان (bufferSize): الحجم الأقصى بالبايتات للبيانات التي يمكن تخزينها في الصوان.

القيمة المرجعة:

عند نجاح القراءة، عدد البايتات التي تمت قراءتها.

عند غلق الاتصال من قبل الطرف الآخر، القيمة 0.

عند عدم وجود بيانات باقية يمكن قراءتها، قيمة سالبة.

اكتب (write)

دالة اكتب(اتصال: مؤشر[اتـصال]، صوان: مؤشر[مـحرف]، حجم_صوان: صـحيح): صـحيح؛

@expname[mg_write]
func write(connection: ptr[Connection], buffer: CharsPtr, bufferSize: Int): Int;

تستعمل هذه الدالة لإرسال البيانات عبر اتصال ما.

المعطيات:

اتصال (connection): مؤشر إلى الاتصال المراد إرسال البيانات عبره.

صوان (buffer): الصوان الذي يحوي البيانات التي نريد إرسالها.

حجم_صوان (bufferSize): حجم الصوان المشار له ب صوان بالبايت.

القيمة المرجعة:

عدد البايتات المرسلة في حال نجاح الإرسال، وإلا -1 في حال فشل الإرسال.

اطبع (print)

دالة اطبع(اتصال: مؤشر[اتـصال]، تنسيق: مؤشر[مـحرف]، أي_معطيات_أخرى...): صـحيح؛

@expname[mg_printf]
func print(connection: ptr[Connection], format: CharsPtr, ...any): Int;

تستعمل هذه الدالة لإرسال رسائل منسقة عبر اتصال ما.

المعطيات:

اتصال (connection): مؤشر إلى الاتصال المراد إرسال الرسالة عبره.

تنسيق (format): التنسيق الخاص بالرسالة المراد إرسالها.

أي معطيات أخرى: المعطيات التي يحتاجها التنسيق ليشكل رسالة.

القيمة المرجعة:

عند إغلاق الاتصال، القيمة 0.

عند حدوث خطأ، القيمة -1.

عند نجاح الإرسال، عدد البايتات التي تم إرسالها.

أرسل_ملف (sendFile)

دالة أرسل_ملف(اتصال: مؤشر[اتـصال]، اسم_الملف: مؤشر[مـحرف]): فـارغ؛

@expname[mg_send_file]
func sendFile(connection: ptr[Connection], fileName: CharsPtr): Void;

تستعمل هذه الدالة لإرسال ملف عبر اتصال ما.

تقوم هذه الدالة تلقائياً بإضافة الترويسات اللازمة.

المعطيات:

اتصال (connection): مؤشر إلى الاتصال المراد إرسال الملف عبره.

اسم_الملف (fileName): اسم الملف الذي نريد إرساله.

هات_الارتباط (getCookie)

دالة هات_الارتباط(
    نص_الكعكات: مؤشر[مـحرف]، اسم_الكعكة: مؤشر[مـحرف]، محتوى_الكعكة: مؤشر[مـحرف]، حجم_الكعكة: كـلمة[64]
): كـلمة[64]؛

@expname[mg_get_cookie]
func getCookie(
    cookiesString: CharsPtr, cookieName: CharsPtr, outCookieContent: CharsPtr, outCookieSize: Word[64]
): Int;

تستعمل هذه الدالة لجلب قيمة متغير معين ضمن كعكة ما.

المعطيات:

نص_الكعكات (cookiesString): اسم الكعكة.

اسم_الكعكة (cookieName): اسم المتغير ضمن الكعكة المشار له ب نص_الكعكات.

محتوى_الكعكة (outCookieContent): الصوان الذي سيتم تخزين المحتوى ضمنه.

حجم_الكعكة (outCookieSize): حجم الصوان المشار له ب محتوى_الكعكة.

القيمة المرجعة:

عند النجاح، حجم الكعكة بالبايت.

عند عدم القدرة على إيجاد الكعكة، القيمة -1.

عند عدم القدرة على التخزين في الصوان، القيمة -2.

هات_الترويسة (getHeader)

دالة هات_الترويسة(اتصال: مؤشر[اتـصال]، اسم_الترويسة: مؤشر[مـحرف]): مؤشر[مـحرف]؛

@expname[mg_get_header]
func getHeader(connection: ptr[Connection], headerName: CharsPtr): CharsPtr;

تستعمل هذه الدالة لجلب الترويسة عبر اتصال ما.

المعطيات:

اتصال (connection): الاتصال المراد جلب الترويسة عبره.

اسم_الترويسة (headerName): اسم الترويسة المراد جلبها.

القيمة المرجعة:

مؤشر إلى السلسلة النصية التي تعبر عن قيمة الترويسة وإلا مؤشر إلى لا شيء.

هات_معلومات_الطلب (getRequestInfo)

دالة هات_معلومات_الطلب(اتصال: مؤشر[اتـصال]): مؤشر[اتـصال]؛

@expname[mg_get_request_info]
func getRequestInfo(connection: ptr[Connection]): ptr[RequestInfo];

تستعمل هذه الدالة لجلب معلومات الطلب عبر اتصال ما.

المعطيات:

اتصال (connection): الاتصال المراد جلب معلومات الطلب منه.

القيمة المرجعة:

مؤشر إلى معلومات الطلب.

هات_متغير (getVariable)

دالة هات_متغير(
    بيانات: مؤشر[مـحرف]، حجم_البيانات: صـحيح، اسم_المتغير: مؤشر[مـحرف]، متغير_الخرج: مؤشر[مـحرف]، حجم_متغير_الخرج: صـحيح
): صـحيح؛

@expname[mg_get_var]
func getVariable(
    data: CharsPtr, dataSize: Int, variableName: CharsPtr, outVariable: CharsPtr, outVariableSize: Int
): Int;

تستعمل هذه الدالة لجلب قيمة متغير ما من الخادم. هذا المتغير تم تمريره إلى الخادم إما عن طريق طلب POST أي ضمن الجسم الخاص بالطلب، أو عن طريق طلب GET ضمن الرابط الخاص بالطلب. و هذه البيانات هي ما يشير إليه المؤشر بيانات.

المعطيات:

بيانات (data): البيانات التي تم تخزينها في الصوان من طلب POST أو من رابط طلب GET.

حجم_البيانات (dataSize): حجم البيانات المشار إليها ب بيانات.

اسم_المتغير (variableName): اسم المتغير الذي نريد جلب قيمته.

متغير_الخرج (outVariable): صوان الخرج الذي نريد تخزين قيمة المتغير فيه.

حجم_متغير_الخرج (outVariableSize): حجم صوان الخرج المشار له ب متغير_الخرج.

القيمة المرجعة:

عند النجاح، حجم المتغير بالبايت.

تعند عدم القدرة على إيجاد المتغير، القيمة -1.

عند عدم القدرة على التخزين في الصوان، القيمة -2.