.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "org.bluez.GattCharacteristic" "5" "اکتبر 2023" "BlueZ" "مدیریت سیستم لینوکس"
.SH "نام (NAME)"
org.bluez.GattCharacteristic \- مستندات واسط D-Bus مشخصه GATT در BlueZ
.SH "توضیحات (DESCRIPTION)"
.sp
نمایش ویژگی‌های مشخصه (characteristic attribute) محلی/سرور و دوردست/کلاینت در GATT از یک واسط سطح‌بالای یکسان D\-Bus بهره می‌برند.
.sp
اصطلاح محلی/سرور (Local/Server) به مشخصه‌های مبتنی بر GATT اشاره دارد که توسط یک افزونه (plugin) یا یک برنامه خارجی ارائه شده‌اند.
.sp
اصطلاح دوردست/کلاینت (Remote/Client) به مشخصه‌های GATT اشاره دارد که توسط دستگاه مقابل (peer) ارائه شده‌اند.
.SH "رابط (INTERFACE)"
.SS "کلاینت (Client)"
.INDENT 0.0
.TP
.B سرویس (Service)
org.bluez
.TP
.B رابط (Interface)
org.bluez.GattCharacteristic1
.TP
.B مسیر شیء (Object path)
[variable prefix]/{hci0,hci1,...}/dev_{BDADDR}/service#/char#
.TP
.B مورد استفاده توسط (Used by)
\fBbluetoothctl\-gatt(1)\fP
.UNINDENT
.SS "سرور (Server)"
.INDENT 0.0
.TP
.B سرویس (Service)
نام یکتا (unique name)
.TP
.B رابط (Interface)
org.bluez.GattCharacteristic1
.TP
.B مسیر شیء (Object path)
قابل تعریف به‌صورت آزاد (freely definable)
.UNINDENT
.SS "متدها (Methods)"
.SS array{byte} ReadValue(dict options)
.sp
درخواستی برای خواندن مقدار مشخصه ارسال می‌کند و در صورت موفقیت‌آمیز بودن عملیات، مقدار را برمی‌گرداند.
.sp
گزینه‌های ممکن:
.INDENT 0.0
.TP
.B uint16 offset
آفست شروع خواندن برحسب بایت.
.TP
.B uint16 mtu (فقط سرور)
مقدار MTU مبادله‌شده برحسب بایت.
.TP
.B object device (فقط سرور)
شیء دستگاه.
.TP
.B string link (فقط سرور)
نوع پیوند.
.sp
مقادیر ممکن:
.INDENT 7.0
.TP
.B \(dqBR/EDR\(dq
.TP
.B \(dqLE\(dq
.UNINDENT
.UNINDENT
.sp
خطاهای ممکن:
.INDENT 0.0
.TP
.B org.bluez.Error.Failed
مقادیر ممکن: رشته 0x80 \- 0x9f
.TP
.B org.bluez.Error.InProgress
.TP
.B org.bluez.Error.NotPermitted
.TP
.B org.bluez.Error.NotAuthorized
.TP
.B org.bluez.Error.InvalidOffset
.TP
.B org.bluez.Error.NotSupported
.UNINDENT
.sp
مثال‌ها:
.INDENT 0.0
.TP
.B bluetoothctl
> gatt.read [offset]
.UNINDENT
.SS void WriteValue(array{byte} value, dict options)
.sp
درخواستی برای نوشتن مقدار مشخصه ارسال می‌کند.
.sp
گزینه‌های ممکن:
.INDENT 0.0
.TP
.B uint16 offset
آفست شروع نوشتن برحسب بایت.
.TP
.B string type
مقادیر ممکن:
.INDENT 7.0
.TP
.B \(dqcommand\(dq
استفاده از روال نوشتن بدون پاسخ (Write without response).
.TP
.B \(dqrequest\(dq
استفاده از روال نوشتن با پاسخ (Write with response).
.TP
.B \(dqreliable\(dq
استفاده از روال نوشتن قابل اطمینان (Reliable Write).
.UNINDENT
.TP
.B uint16 mtu
مقدار MTU مبادله‌شده (فقط سرور).
.TP
.B object device
مسیر دستگاه (فقط سرور).
.TP
.B string link
نوع پیوند (فقط سرور).
.sp
مقادیر ممکن:
.INDENT 7.0
.TP
.B \(dqBR/EDR\(dq
.TP
.B \(dqLE\(dq
.UNINDENT
.TP
.B boolean prepare\-authorize
در صورت آماده‌سازی درخواست مجوز (prepare authorization request)، مقدار True است.
.UNINDENT
.sp
خطاهای ممکن:
.INDENT 0.0
.TP
.B org.bluez.Error.Failed
مقادیر ممکن: رشته 0x80 \- 0x9f
.TP
.B org.bluez.Error.InProgress
.TP
.B org.bluez.Error.NotPermitted
.TP
.B org.bluez.Error.InvalidValueLength
.TP
.B org.bluez.Error.NotAuthorized
.TP
.B org.bluez.Error.NotSupported
.TP
.B org.bluez.Error.ImproperlyConfigured
.UNINDENT
.sp
مثال‌ها:
.INDENT 0.0
.TP
.B bluetoothctl
> gatt.write <data=xx xx ...> [offset] [type]
.UNINDENT
.SS fd, uint16 AcquireWrite(dict options) [optional]
.sp
توصیف‌کننده فایل (file descriptor) و MTU را برای نوشتن دریافت می‌کند. تنها از سوکت‌ها پشتیبانی می‌شود. استفاده از WriteValue قفل خواهد شد و باعث بازگرداندن خطای NotPermitted می‌شود.
.sp
برای سرور، مقدار MTU بازگردانده‌شده باید مساوی یا کوچک‌تر از MTU توافق‌شده باشد.
.sp
برای کلاینت، تنها با مشخصه‌ای کار می‌کند که دارای ویژگی \fBWriteAcquired\fP باشد که خود متکی بر \fBFlag\fP از نوع write\-without\-response است.
.sp
برای آزادسازی قفل، کلاینت باید توصیف‌کننده فایل را ببندد؛ در صورت قطع اتصال دستگاه، یک سیگنال HUP ایجاد می‌شود.
.sp
نکته: توافق بر سر MTU تنها یک بار امکان‌پذیر است و متقارن می‌باشد، بنابراین این متد ممکن است برای تکمیل فرایند تبادل MTU با تاخیر مواجه شود؛ به همین دلیل، در صورت اتصال مجدد، توصیف‌کننده فایل بسته می‌شود چرا که MTU باید دوباره توافق شود.
.sp
گزینه‌های ممکن:
.INDENT 0.0
.TP
.B object device
شیء دستگاه (فقط سرور).
.TP
.B uint16 mtu
مقدار MTU مبادله‌شده (فقط سرور).
.TP
.B string link
نوع پیوند (فقط سرور).
.sp
مقادیر ممکن:
.INDENT 7.0
.TP
.B \(dqBR/EDR\(dq
.TP
.B \(dqLE\(dq
.UNINDENT
.UNINDENT
.sp
خطاهای ممکن:
.INDENT 0.0
.TP
.B org.bluez.Error.Failed
.TP
.B org.bluez.Error.NotSupported
.UNINDENT
.sp
مثال‌ها:
.INDENT 0.0
.TP
.B bluetoothctl
> gatt.acquire\-write
.UNINDENT
.SS fd, uint16 AcquireNotify(dict options) [optional]
.sp
توصیف‌کننده فایل و MTU را برای اعلان (notify) دریافت می‌کند. تنها از سوکت‌ها پشتیبانی می‌شود.
.sp
استفاده از StartNotify قفل خواهد شد و باعث بازگرداندن خطای \fBorg.bluez.Error.NotPermitted\fP می‌شود.
.sp
برای سرور، مقدار MTU بازگردانده‌شده باید مساوی یا کوچک‌تر از MTU توافق‌شده باشد.
.sp
تنها با مشخصه‌ای کار می‌کند که دارای ویژگی \fBNotifyAcquired\fP باشد که خود متکی بر وجود \fBFlag\fP با مقدار \fB\(dqnotify\(dq یا \(dqindicate\(dq\fP است و هیچ کلاینت دیگری \fBStartNotify()\fP را فراخوانی نکرده باشد.
.sp
اعلان‌ها در طول این رویه فعال هستند، بنابراین \fBStartNotify()\fP نباید فراخوانی شود؛ هرگونه اعلانی از طریق توصیف‌کننده فایل ارسال خواهد شد، از این رو در مدت زمانی که دریافت اعلان (notify) تصاحب شده است، ویژگی Value تحت تاثیر قرار نمی‌گیرد.
.sp
برای آزادسازی قفل، کلاینت باید توصیف‌کننده فایل را ببندد؛ در صورت قطع اتصال دستگاه، یک سیگنال HUP ایجاد می‌شود.
.sp
در حالت کلاینت، اگر از رویه نشانه (indication) استفاده شود، تاییدیه پس از دریافت به صورت خودکار ایجاد می‌شود؛ برای سرور، اگر توصیف‌کننده فایل قابل نوشتن باشد (POLLOUT)، با دریافت تاییدیه از سوی کلاینت، یک بایت (0x01) در توصیف‌کننده فایل نوشته می‌شود.
.sp
نکته: توافق بر سر MTU تنها یک بار امکان‌پذیر است و متقارن می‌باشد، بنابراین این متد ممکن است برای تکمیل فرایند تبادل MTU با تاخیر مواجه شود؛ به همین دلیل، در صورت اتصال مجدد، توصیف‌کننده فایل بسته می‌شود چرا که MTU باید دوباره توافق شود.
.sp
گزینه‌های ممکن:
.INDENT 0.0
.TP
.B object device
شیء دستگاه (فقط سرور).
.TP
.B uint16 mtu
مقدار MTU مبادله‌شده (فقط سرور).
.TP
.B string link
نوع پیوند (فقط سرور).
.sp
مقادیر ممکن:
.INDENT 7.0
.TP
.B \(dqBR/EDR\(dq
.TP
.B \(dqLE\(dq
.UNINDENT
.UNINDENT
.sp
خطاهای ممکن:
.INDENT 0.0
.TP
.B org.bluez.Error.Failed
.TP
.B org.bluez.Error.NotSupported
.TP
.B org.bluez.Error.NotPermitted
.UNINDENT
.sp
مثال‌ها:
.INDENT 0.0
.TP
.B bluetoothctl
> gatt.acquire\-notify
.UNINDENT
.SS void StartNotify()
.sp
در صورتی که مشخصه از اعلان‌ها یا نشانه‌های مقدار (value notifications or indications) پشتیبانی کند، یک نشست اعلان از این مشخصه را آغاز می‌کند.
.sp
خطاهای ممکن:
.INDENT 0.0
.TP
.B org.bluez.Error.Failed
.TP
.B org.bluez.Error.NotPermitted
.TP
.B org.bluez.Error.InProgress
.TP
.B org.bluez.Error.NotConnected
.TP
.B org.bluez.Error.NotSupported
.UNINDENT
.sp
مثال‌ها:
.INDENT 0.0
.TP
.B bluetoothctl
> gatt.notify <on/off>
.UNINDENT
.SS void StopNotify()
.sp
نشستی را که قبلاً توسط \fBStartNotify()\fP ایجاد شده بود، متوقف یا لغو می‌کند.
.sp
توجه داشته باشید که اعلان‌های یک مشخصه میان نشست‌ها به اشتراک گذاشته می‌شوند، بنابراین فراخوانی StopNotify تنها یک نشست را آزاد خواهد کرد.
.sp
خطاهای ممکن:
.INDENT 0.0
.TP
.B org.bluez.Error.Failed
.UNINDENT
.SS void Confirm() [noreply, optional] (فقط سرور)
.sp
دریافت مقدار را تایید می‌کند.
.sp
خطاهای ممکن:
.sp
org.bluez.Error.Failed
.SS "ویژگی‌ها (Properties)"
.SS string UUID [read\-only]
.sp
شناسه یکتای ۱۲۸ بیتی مشخصه (UUID).
.SS object Service [read\-only]
.sp
مسیر شیء سرویس GATT که این مشخصه به آن تعلق دارد.
.SS array{byte} Value [read\-only, optional]
.sp
مقدار کش‌شده مشخصه. این ویژگی فقط پس از یک درخواست موفق خواندن و هنگام دریافت اعلان یا نشانه (notification or indication) به‌روزرسانی می‌شود که پس از آن سیگنال PropertiesChanged منتشر خواهد شد.
.SS boolean WriteAcquired [read\-only, optional]
.sp
در صورتی که این مشخصه توسط کلاینتی با استفاده از AcquireWrite تصاحب شده باشد، مقدار True است.
.sp
برای کلاینت، در صورتی که فلگ \(aqwrite\-without\-response\(aq تنظیم نشده باشد، این ویژگی حذف می‌شود.
.sp
برای سرور، وجود این ویژگی نشان‌دهنده پشتیبانی از AcquireWrite است.
.SS boolean NotifyAcquired [read\-only, optional]
.sp
در صورتی که این مشخصه توسط کلاینتی با استفاده از AcquireNotify تصاحب شده باشد، مقدار True است.
.sp
برای کلاینت، در صورتی که فلگ \(aqnotify\(aq تنظیم نشده باشد، این ویژگی حذف می‌شود.
.sp
برای سرور، وجود این ویژگی نشان‌دهنده پشتیبانی از AcquireNotify است.
.SS boolean Notifying [read\-only, optional]
.sp
در صورتی که اعلان‌ها یا نشانه‌ها (notifications or indications) روی این مشخصه در حال حاضر فعال باشند، مقدار True است.
.SS array{string} Flags [read\-only]
.sp
نحوه استفاده از مقدار مشخصه را تعیین می‌کند. جدول ۳.۵ (میدان بیتی ویژگی‌های مشخصه) و جدول ۳.۸ (میدان بیتی ویژگی‌های گسترش‌یافته مشخصه) در مشخصات اصلی (Core spec) را ببینید.
.sp
فلگ‌های \(dqx\-notify\(dq و \(dqx\-indicate\(dq با اعمال محدودیت‌های نوشتن بر روی توصیف‌گر پیکربندی مشخصه کلاینت (client characteristic configuration descriptor)، دسترسی به اعلان‌ها و نشانه‌ها را محدود می‌کنند.
.sp
مقادیر ممکن:
.INDENT 0.0
.TP
.B \(dqbroadcast\(dq
.TP
.B \(dqread\(dq
.TP
.B \(dqwrite\-without\-response\(dq
.TP
.B \(dqwrite\(dq
.TP
.B \(dqnotify\(dq
.TP
.B \(dqindicate\(dq
.TP
.B \(dqauthenticated\-signed\-writes\(dq
.TP
.B \(dqextended\-properties\(dq
.TP
.B \(dqreliable\-write\(dq
.TP
.B \(dqwritable\-auxiliaries\(dq
.TP
.B \(dqencrypt\-read\(dq
.TP
.B \(dqencrypt\-write\(dq
.TP
.B \(dqencrypt\-notify\(dq (فقط سرور)
.TP
.B \(dqencrypt\-indicate\(dq (فقط سرور)
.TP
.B \(dqencrypt\-authenticated\-read\(dq
.TP
.B \(dqencrypt\-authenticated\-write\(dq
.TP
.B \(dqencrypt\-authenticated\-notify\(dq (فقط سرور)
.TP
.B \(dqencrypt\-authenticated\-indicate\(dq (فقط سرور)
.TP
.B \(dqsecure\-read\(dq (فقط سرور)
.TP
.B \(dqsecure\-write\(dq (فقط سرور)
.TP
.B \(dqsecure\-notify\(dq (فقط سرور)
.TP
.B \(dqsecure\-indicate\(dq (فقط سرور)
.TP
.B \(dqauthorize\(dq
.UNINDENT
.SS uint16 Handle [read\-only] (فقط کلاینت)
.sp
هندل مشخصه (Characteristic handle).
.SS uint16 Handle [read\-write, optional] (فقط سرور)
.sp
هندل مشخصه. در صورت وجود در سرور، تلاش می‌شود تا از آن برای تخصیص در پایگاه‌داده استفاده شود که ممکن است ناموفق باشد؛ برای تخصیص خودکار باید از مقدار 0x0000 استفاده شود که باعث می‌شود پس از ثبت، هندلِ تخصیص‌یافته تنظیم گردد.
.SS uint16 MTU [read\-only]
.sp
مقدار MTU مشخصه؛ این مقدار هم برای \fBReadValue()\fP و هم برای \fBWriteValue()\fP معتبر است، اما هر یک از متدها می‌توانند در صورت پشتیبانی از رویه‌های طولانی (long procedures) استفاده کنند.
.\" End of generated man page.