.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.TH mqttui-read-one 1  "read-one " 
.SH "نام (NAME)"
mqttui\-read\-one \- انتظار برای نخستین پیام در تاپیک(های) مشخص‌شده و بازگرداندن دادهٔ آن به stdout
.SH "خلاصه دستور (SYNOPSIS)"
\fBmqttui read\-one\fR [\fB\-r\fR|\fB\-\-ignore\-retained\fR] [\fB\-\-only\fR] [\fB\-p\fR|\fB\-\-pretty\fR] [\fB\-\-qos\fR] [\fB\-b\fR|\fB\-\-broker\fR] [\fB\-u\fR|\fB\-\-username\fR] [\fB\-\-password\fR] [\fB\-i\fR|\fB\-\-client\-id\fR] [\fB\-\-ca\-cert\fR] [\fB\-\-client\-cert\fR] [\fB\-\-client\-private\-key\fR] [\fB\-\-insecure\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fITOPIC\fR] 
.SH "توضیحات (DESCRIPTION)"
منتظر نخستین پیام در تاپیک(های) ارائه‌شده می‌ماند و بار داده (payload) آن را به stdout بازمی‌گرداند.
.PP
دقیقاً یک بار داده از نخستین پیام دریافت‌شده در تاپیک(های) داده‌شده را بازمی‌گرداند. تاپیک پیام دریافت‌شده در stderr چاپ می‌شود؛ این بدان معناست که می‌توانید stdout و stderr را به‌طور جداگانه مدیریت کنید.
.PP
این قابلیت می‌تواند برای اسکریپت‌نویسی جهت دریافت دمای خوانده‌شدهٔ فعلی و ارسال آن با لوله (pipe) به جایی دیگر مفید باشد:
.PP
`echo "The temperature is $(mqttui read\-one room/temp)"`
.PP
خروجی دقیقاً همان بار داده در قالب باینری است. این داده ممکن است یک ASCII / Unicode معتبر باشد، اما می‌تواند چیزی باشد که برای نمایش در ترمینال طراحی نشده است. برای قالبی خوانا برای انسان، از `\-\-pretty` یا `mqttui log` استفاده کنید.
.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-r\fR, \fB\-\-ignore\-retained\fR
هنگام برقراری اتصال، پیام نگه‌داشته‌شده (retained) را بازنمی‌گرداند و منتظر رسیدن پیام دیگری می‌ماند.

در آینده به نفع `\-\-only=live` حذف خواهد شد.
.TP
\fB\-\-only\fR \fI<ONLY>\fR
فقط نوع خاصی از پیام را بازمی‌گرداند؛ یا صراحتاً یک پیام نگه‌داشته‌شده (retained) یا پیامی زنده و جاری که روی کارگزار ذخیره نشده است.

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

.br
\fIمقادیر ممکن:\fR
.RS 14
.IP \(bu 2
retained
.IP \(bu 2
live
.RE
.TP
\fB\-p\fR, \fB\-\-pretty\fR
بار داده را تجزیه کرده و آن را در قالبی آراسته و خوانا برای انسان چاپ می‌کند.

این حالت ممکن است برای پایپ کردن داده‌ها مناسب نباشد.
.TP
\fB\-\-qos\fR \fI<LEVEL>\fR [پیش‌فرض: 2]
حداکثر کیفیت خدمات (`QoS`) برای اشتراک‌ها و انتشارها.

سطح کیفیت خدمات پایین‌تر میان ناشر و مشترک، از سوی کارگزار به مشترک تحویل داده می‌شود. بنابراین، اشتراک با سطح 0 هرگز پیامی با سطح 1 یا 2 دریافت نخواهد کرد. انتشار با سطح 2، در صورت اشتراک با سطح 1، به‌صورت 1 دریافت خواهد شد.

\- 0: حداکثر یک‌بار (fire and forget / ارسال و فراموش)

\- 1: حداقل یک‌بار (تحویل تاییدشده با احتمال دریافت تکراری)

\- 2: دقیقاً یک‌بار (تحویل تضمین‌شده بدون دریافت تکراری)
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_QOS\fR مشخص شود. 
.RE
.TP
\fB\-h\fR, \fB\-\-help\fR
چاپ راهنما (مشاهدهٔ خلاصه‌ای با \*(Aq\-h\*(Aq)
.TP
[\fITOPIC\fR] [پیش‌فرض: #]
تاپیک‌ها برای پایش
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_TOPIC\fR مشخص شود. 
.RE
.SH "اتصال MQTT (MQTT CONNECTION)"
.TP
\fB\-b\fR, \fB\-\-broker\fR \fI<URL>\fR [پیش‌فرض: mqtt://localhost]
نشانی اینترنتی (URL) که نحوهٔ اتصال به کارگزار MQTT را مشخص می‌کند.

مثال‌ها: `mqtt://localhost` `mqtt://localhost:1883` `mqtts://localhost` `mqtts://localhost:8883` `ws://localhost/path` `ws://localhost:9001/path` `wss://localhost/path` `wss://localhost:9001/path`
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_BROKER\fR مشخص شود. 
.RE
.TP
\fB\-u\fR, \fB\-\-username\fR \fI<STRING>\fR
نام کاربری برای دسترسی به کارگزار mqtt.

در صورت ارائه نشدن، دسترسی ناشناس اعمال می‌شود.
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_USERNAME\fR مشخص شود. 
.RE
.TP
\fB\-\-password\fR \fI<STRING>\fR
گذرواژه برای دسترسی به کارگزار mqtt.

استفاده از اتصالی مجهز به TLS به کارگزار را مد نظر داشته باشید؛ در غیر این صورت گذرواژه به‌صورت متن ساده (plaintext) منتقل خواهد شد.

ارسال گذرواژه از طریق خط فرمان ناامن است زیرا گذرواژه می‌تواند از تاریخچه خوانده شود! بهتر است آن را از طریق متغیر محیطی ارسال کنید.
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_PASSWORD\fR مشخص شود. 
.RE
.TP
\fB\-i\fR, \fB\-\-client\-id\fR \fI<STRING>\fR
مشخص کردن شناسهٔ کلاینت (client id) برای برقراری اتصال
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_CLIENTID\fR مشخص شود. 
.RE
.TP
\fB\-\-ca\-cert\fR \fI<FILEPATH>\fR
مسیر به فایل PEM گواهی CA معتبر جهت اعتبارسنجی کارگزار.

گواهی CA باید یک گواهی X.509 v3 باشد زیرا rustls از گواهی‌های ناامن‌تر v1 پشتیبانی نمی‌کند. ببینید: <https://github.com/rustls/rustls/issues/2364>
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_CA_CERTIFICATE\fR مشخص شود. 
.RE
.TP
\fB\-\-client\-cert\fR \fI<FILEPATH>\fR
مسیر به فایل گواهی کلاینت TLS.

همراه با \-\-client\-private\-key برای فعال‌سازی احراز هویت کلاینت TLS استفاده می‌شود. این فایل باید یک گواهی X.509 با کدگذاری DER باشد که به PEM تبدیل شده است.
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_CLIENT_CERTIFICATE\fR مشخص شود. 
.RE
.TP
\fB\-\-client\-private\-key\fR \fI<FILEPATH>\fR
مسیر به فایل کلید خصوصی کلاینت TLS.

همراه با \-\-client\-cert برای فعال‌سازی احراز هویت کلاینت TLS استفاده می‌شود. این فایل باید یک فایل ASN.1 با کدگذاری DER در قالب PKCS#8 باشد که به PEM تبدیل شده است.
.RS
همچنین می‌تواند از طریق متغیر محیطی \fBMQTTUI_CLIENT_PRIVATE_KEY\fR مشخص شود. 
.RE
.TP
\fB\-\-insecure\fR
مجاز دانستن اتصالات ناامن TLS