الكتابة والقراءة

هذه الدوال هي جميع الطرق المتاحة للتواصل مع أجهزة USB المتصلة في إضافاتك. تنقسم الأوامر إلى نوعين من القراءة والكتابة حسب بروتوكولات الجهاز، بالإضافة إلى عمليات نقل التحكم التي تتيح أوامر المصافحة والوظائف المتقدمة.

للاطلاع على الطرق المتقدمة (bulk_transfer وcontrol_transfer وinput_report) والاتصال عبر الشبكة/المنفذ التسلسلي، راجع الاتصال المتقدم.

device.write()[send_report]

تُنفّذ هذه الدالة أمر Hid_Write على نقطة النهاية المحددة حاليًا للجهاز. هذه هي دالة الكتابة التي تستخدمها معظم الأجهزة، وستكون الأمر الأكثر استخدامًا.

• ملاحظة: هناك نوع آخر من الكتابة هو device.send_report. وهو أمر الكتابة المستخدم لإرسال تقارير ميزات HID إلى الجهاز. وظيفته فيما عدا ذلك مماثلة لـ device.write().
• ملاحظة: ضبط طول أكبر من مصفوفة البيانات المقدَّمة سيؤدي إلى حشو نهاية المصفوفة بـ 0x00.
• ملاحظة: معظم أجهزة HID تحشو بداية أوامر الكتابة الخاصة بها بصفر. يتم ذلك بوضع 0x00 إضافي في مقدمة DataArray وزيادة الطول بمقدار واحد. يزيل الجهاز هذه القيم أثناء نقل البيانات. يحدث هذا بشكل أساسي عندما لا يكون للجهاز معرّف تقرير (Report ID) لنقطة النهاية المحددة.

المعامل	النوع	الوصف	مثال
DataArray	مصفوفة أحادية البعد	مصفوفة تحتوي على بايتات سداسية عشرية لإرسالها إلى الجهاز	[0x08,0xAB,0xFF,0x37]
Length	Int	قيمة عددية صحيحة تمثل الطول الإجمالي للحزمة المراد إرسالها	4

فيما يلي مثال على حزمة من وحدات التحكم في LED من ASUS يوضح إنشاءها وإرسالها إلى الجهاز.

var packet = [];
packet[0] = 0xEC; //This is the Report Id
packet[1] = 0x40; //Command
packet[2] = apply ? 0x80 | channel : channel; //Channel Number
packet[3] = start; //Led to Start on
packet[4] = count; //Led Count
packet = packet.concat(RGBData); //Array of RGB values in a [R,G,B ...] format

device.write(packet, 65);  //Writing the packet to the device in 65 Bytes

device.read()[get_report]

يأخذ استدعاء هذه الدالة مصفوفة تحتوي على معرّف تقرير نقطة النهاية وعدد البايتات المراد قراءتها، ويُنفّذ أمر Hid_Read على الجهاز. تُرجع الدالة مصفوفة من البايتات المقروءة من الجهاز. تتطلب بعض الأجهزة إجراء قراءة لمنع تجاوز سعة المخزن المؤقت، وتحتاج أحيانًا إلى قراءة بيانات التهيئة أو الإعدادات من الأجهزة.

• ملاحظة: هناك نوع آخر من القراءة هو device.get_report. وهو أمر القراءة المستخدم للحصول على تقارير ميزات HID من الجهاز. وظيفته فيما عدا ذلك مماثلة لـ device.read().

المعامل	النوع	الوصف	مثال	الافتراضي
DataArray	مصفوفة أحادية البعد	مصفوفة تحتوي على معرّف التقرير اللازم لأمر القراءة	[0x08, 0x02]
Length	Int	قيمة عددية صحيحة تمثل عدد البايتات المراد قراءتها	65
Timeout	Int	عدد المللي ثانية لانتظار البيانات قبل الإرجاع. مرّر 0 لإجراء فحص غير حاجب.	100	100

القيمة المُرجعة	النوع	الوصف	مثال
DataArray	مصفوفة أحادية البعد	مصفوفة تحتوي على جميع البايتات السداسية العشرية المقروءة من الجهاز، أو مصفوفة فارغة إذا انتهت المهلة دون بيانات	[0x08, 0x02,0x00,0x64]

• ملاحظة: تُرجع هذه الدالة مصفوفة بيانات تطابق طول تقرير الجهاز. إذا كنت بحاجة إلى العدد الفعلي للبايتات المقروءة، فاستخدم device.getLastReadSize().
• ملاحظة: عندما تنتهي المهلة دون بيانات، تكون القيمة المُرجعة مصفوفة فارغة وتُرجع device.getLastReadSize() القيمة 0.

// Standard blocking read (100ms default timeout)
var config = device.read(packet, 65);

// Non-blocking peek — returns immediately, use getLastReadSize() to check if data arrived
var data = device.read([], 64, 0);
if(device.getLastReadSize() > 0) {
    processResponse(data);
}

device.getLastReadSize()

تُرجع هذه الدالة عدد البايتات المقروءة في آخر عملية read/get_report أُجريت على الجهاز.

القيمة المُرجعة	النوع	الوصف	مثال
BytesRead	Int	عدد البايتات المقروءة من الجهاز	64

فيما يلي مثال من ماوس Glorious Model 0.

function CheckPacketLength(){

    var packet = [0x52]

    packet = device.get_report(packet,200) //attempts to read up to 200 bytes

    return device.getLastReadSize(); //Returns 186 on a successful read of the config packet

}

device.clearReadBuffer()

تمسح أي بيانات معلّقة في قائمة انتظار المخزن المؤقت للقراءة في الجهاز. استدعِها قبل أي قراءة حرجة لضمان تلقي بيانات جديدة بدلًا من استجابة قديمة مخزّنة مؤقتًا.

• ملاحظة: تعتمد فائدة هذه الدالة على الجهاز ونقطة النهاية. إذا كان الجهاز لا يدعم التفريغ، فأفرغه يدويًا بتكرار عمليات القراءة حتى تُرجع device.getLastReadSize() القيمة 0.

device.clearReadBuffer();
device.write(requestPacket, 64);
var response = device.read([], 64);

device.flush()

تحاول هذه الدالة مسح المخزن المؤقت للقراءة في الجهاز بالكامل باستخدام آلية التفريغ الأصلية للجهاز. يُفضَّل استخدام device.clearReadBuffer() في معظم حالات الاستخدام.

export function Initialize(){
    device.flush()
     if(Corsair_Get(CORSAIR_MODE) == CORSAIR_HARDWARE_MODE){
         EnableSoftwareControl();
     }
}

device.control_transfer()

راجع الاتصال المتقدم للاطلاع على التوثيق الكامل لـ control_transfer وbulk_transfer وinput_report.