chrome.sockets.udp

شرح

از chrome.sockets.udp API برای ارسال و دریافت داده ازطریق شبکه بااستفاده از اتصال‌های UDP استفاده کنید. این API جایگزین عملکرد UDP می‌شود که قبلاً در API «سوکت» وجود داشت.

مانیفست

برای استفاده از این میانای برنامه‌سازی کاربردی، کلیدهای زیر باید در مانیفست اعلام شوند.

"sockets"

انواع

CreateInfo

مشخصات

  • socketId

    شماره

    شناسه سوکت تازه ایجادشده. توجه داشته باشید که شناسه‌های سوکت ایجادشده از این میانای برنامه‌سازی کاربردی با شناسه‌های سوکت ایجادشده از دیگر میاناهای برنامه‌سازی کاربردی، مانند میانای برنامه‌سازی کاربردی منسوخ‌شده [سوکت](../socket/)، سازگار نیستند.

DnsQueryType

Chrome نسخه ۱۰۳ و بالاتر

اولویت‌های تفکیک ساناد. پیش‌فرض any است و از پیکربندی سیستم‌عامل فعلی استفاده می‌کند که ممکن است IPv4 یا IPv6 را برگرداند. ipv4 پروتکل اینترنتی نسخه ۴ را اجباری می‌کند و ipv6 پروتکل اینترنتی نسخه ۶ را اجباری می‌کند.

شمارشی

«any»

"ipv4"

"ipv6"

ReceiveErrorInfo

مشخصات

  • resultCode

    شماره

    کد نتیجه برگشتی از فراخوانی recvfrom()‎ زیربنایی.

  • socketId

    شماره

    شناسه سوکت.

ReceiveInfo

مشخصات

  • داده

    ArrayBuffer

    محتوای بسته UDP (به اندازه میان‌گیر فعلی کوتاه شده است).

  • remoteAddress

    رشته

    نشانی میزبانی که بسته از آن می‌آید.

  • remotePort

    شماره

    درگاه میزبانی که بسته از آن می‌آید.

  • socketId

    شماره

    شناسه سوکت.

SendInfo

مشخصات

  • bytesSent

    شماره اختیاری

    تعداد بایت‌های ارسال‌شده (اگر نتیجه == 0)

  • resultCode

    شماره

    کد نتیجه از تماس شبکه زیربنایی برگردانده شد. مقدار منفی نشان‌دهنده خطا است.

SocketInfo

مشخصات

  • bufferSize

    شماره اختیاری

    اندازه میان‌گیری که برای دریافت داده استفاده می‌شود. اگر اندازه میان‌گیر به‌طور صریح مشخص نشده باشد، مقدار ارائه نمی‌شود.

  • localAddress

    رشته اختیاری

    اگر سوکت زیرین محدود شده باشد، حاوی نشانی IPv4/6 محلی آن است.

  • localPort

    شماره اختیاری

    اگر سوکت زیرین مقید باشد، حاوی درگاه محلی آن است.

  • نام

    رشته اختیاری

    رشته تعریف‌شده توسط برنامه مرتبط با سوکت.

  • موقتاً متوقف‌شده

    بولی

    پرچمی که نشان می‌دهد آیا سوکت از راه‌اندازی رویدادهای onReceive مسدود شده است یا نه.

  • دائمی

    بولی

    پرچمی که نشان می‌دهد آیا سوکت هنگام تعلیق برنامه باز می‌ماند یا نه (به SocketProperties.persistent مراجعه کنید).

  • socketId

    شماره

    شناسه سوکت.

SocketProperties

مشخصات

  • bufferSize

    شماره اختیاری

    اندازه میان‌گیری که برای دریافت داده استفاده می‌شود. اگر میان‌گیر برای دریافت بسته UDP خیلی کوچک باشد، داده‌ها ازدست می‌رود. مقدار پیش‌فرض ۴۰۹۶ است.

  • نام

    رشته اختیاری

    رشته تعریف‌شده توسط برنامه که با سوکت مرتبط است.

  • دائمی

    بولی اختیاری

    پرچمی که نشان می‌دهد آیا سوکت هنگام بارگیری نشدن صفحه رویداد برنامه باز می‌ماند (به مدیریت چرخه حیات برنامه مراجعه کنید). مقدار پیش‌فرض «false» است. وقتی برنامه بار می‌شود، هر سوکتی که قبلاً با persistent=true باز شده باشد می‌تواند با getSockets واکشی شود.

روش‌ها

bind()

chrome.sockets.udp.bind(
  socketId: number,
  address: string,
  port: number,
  callback: function,
): void

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

وقتی عملیات bind با موفقیت تکمیل شد، وقتی بسته‌های UDP به نشانی/درگاه مشخص‌شده می‌رسند، رویدادهای onReceive ایجاد می‌شوند -- مگراینکه سوکت موقتاً متوقف شده باشد.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • نشانی

    رشته

    نشانی ماشین محلی. از نام ساناد، قالب‌های IPv4 و IPv6 پشتیبانی می‌شود. از «0.0.0.0» برای پذیرش بسته‌ها از همه میاناهای شبکه محلی دردسترس استفاده کنید.

  • درگاه

    شماره

    درگاه ماشین محلی. از «۰» برای اتصال به درگاه آزاد استفاده کنید.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (result: number) => void

    • نتیجه

      شماره

      کد نتیجه از تماس شبکه زیربنایی برگردانده شد. مقدار منفی نشان‌دهنده خطا است.

close()

قول 
chrome.sockets.udp.close(
  socketId: number,
  callback?: function,
): Promise<void>

سوکت را می‌بندد و نشانی/درگاهی را که سوکت به آن متصل است آزاد می‌کند. هر سوکت ایجادشده باید پس‌از استفاده بسته شود. شناسه سوکت به‌محض فراخوانی تابع دیگر معتبر نیست. بااین‌حال، تضمین می‌شود که سوکت فقط زمانی بسته شود که فراخوانی برگشتی فراخوانده شود.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

create()

قول 
chrome.sockets.udp.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<CreateInfo>

سوکت UDP با ویژگی‌های ارائه‌شده ایجاد می‌کند.

پارامترها

  • اقامتگاه‌ها

    SocketProperties اختیاری

    ویژگی‌های سوکت (اختیاری).

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      نتیجه ایجاد سوکت.

بازگشتی‌ها

  • Promise<CreateInfo>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getInfo()

قول 
chrome.sockets.udp.getInfo(
  socketId: number,
  callback?: function,
): Promise<SocketInfo>

وضعیت سوکت داده‌شده را بازیابی می‌کند.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      شیء حاوی اطلاعات سوکت.

بازگشتی‌ها

  • Promise<SocketInfo>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getJoinedGroups()

قول 
chrome.sockets.udp.getJoinedGroups(
  socketId: number,
  callback?: function,
): Promise<string[]>

نشانی‌های گروه چندفرستی را که سوکت درحال‌حاضر به آن پیوسته است دریافت می‌کند.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (groups: string[]) => void

    • گروه‌ها

      string[]

      آرایه گروه‌هایی که سوکت به آن‌ها پیوسته است.

بازگشتی‌ها

  • Promise<string[]>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getSockets()

قول 
chrome.sockets.udp.getSockets(
  callback?: function,
): Promise<SocketInfo[]>

فهرست سوکت‌های باز فعلی متعلق به برنامه را بازیابی می‌کند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (socketInfos: SocketInfo[]) => void

    • socketInfos

      SocketInfo[]

      آرایه شیء حاوی اطلاعات سوکت.

بازگشتی‌ها

  • Promise<SocketInfo[]>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

joinGroup()

chrome.sockets.udp.joinGroup(
  socketId: number,
  address: string,
  callback: function,
): void

به گروه چندپخشی می‌پیوندد و شروع به دریافت بسته‌ها از آن گروه می‌کند. سوکت باید قبل‌از فراخوانی این روش به درگاه محلی متصل شود.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • نشانی

    رشته

    نشانی گروه برای پیوستن. از نام‌های دامنه پشتیبانی نمی‌شود.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (result: number) => void

    • نتیجه

      شماره

      کد نتیجه از تماس شبکه زیربنایی برگردانده شد. مقدار منفی نشان‌دهنده خطا است.

leaveGroup()

chrome.sockets.udp.leaveGroup(
  socketId: number,
  address: string,
  callback: function,
): void

گروه چندپخشی را که قبلاً بااستفاده از joinGroup به آن پیوسته بود ترک می‌کند. این کار فقط درصورتی لازم است که قصد داشته باشید بعداز آن به استفاده از سوکت ادامه دهید، زیرا وقتی سوکت بسته شود، این کار به‌طور خودکار توسط سیستم‌عامل انجام خواهد شد.

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

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • نشانی

    رشته

    نشانی گروه برای ترک کردن. از نام‌های دامنه پشتیبانی نمی‌شود.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (result: number) => void

    • نتیجه

      شماره

      کد نتیجه از تماس شبکه زیربنایی برگردانده شد. مقدار منفی نشان‌دهنده خطا است.

send()

chrome.sockets.udp.send(
  socketId: number,
  data: ArrayBuffer,
  address: string,
  port: number,
  dnsQueryType?: DnsQueryType,
  callback: function,
): void

داده‌های سوکت ارائه‌شده را به نشانی و درگاه ارائه‌شده ارسال می‌کند. سوکت باید قبل‌از فراخوانی این روش به درگاه محلی متصل شود.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • داده

    ArrayBuffer

    داده‌هایی که باید ارسال شود.

  • نشانی

    رشته

    نشانی دستگاه ازراه‌دور.

  • درگاه

    شماره

    درگاه ماشین راه‌دور.

  • dnsQueryType

    DnsQueryType اختیاری

    Chrome نسخه ۱۰۳ و بالاتر

    اولویت تفکیک آدرس.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (sendInfo: SendInfo) => void

    • sendInfo

      SendInfo

      نتیجه روش send.

setBroadcast()

Chrome نسخه ۴۴ به بالا 
chrome.sockets.udp.setBroadcast(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

بسته‌های همه‌فرستی را در این سوکت فعال یا غیرفعال می‌کند.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • فعال شد

    بولی

    true برای فعال کردن بسته‌های همه‌فرستی، false برای غیرفعال کردن آن‌ها.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (result: number) => void

    • نتیجه

      شماره

      کد نتیجه از تماس شبکه زیربنایی برگردانده شد.

setMulticastLoopbackMode()

chrome.sockets.udp.setMulticastLoopbackMode(
  socketId: number,
  enabled: boolean,
  callback: function,
): void

تنظیم می‌کند که آیا بسته‌های چندپخشی ارسال‌شده از میزبان به گروه چندپخشی به میزبان برگردانده شوند یا نه.

توجه: رفتار setMulticastLoopbackMode در سیستم‌های Windows و سیستم‌های شبه Unix کمی متفاوت است. این ناسازگاری فقط زمانی اتفاق می‌افتد که بیش‌از یک برنامه در یک میزبان به یک گروه چندفرستی پیوسته باشند و تنظیمات متفاوتی در حالت بازگشت چندفرستی داشته باشند. در Windows، برنامه‌هایی که حلقه بازگشتی آن‌ها خاموش است بسته‌های حلقه بازگشتی را دریافت نخواهند کرد؛ درحالی‌که در سیستم‌های شبه Unix، برنامه‌هایی که حلقه بازگشتی آن‌ها خاموش است بسته‌های حلقه بازگشتی را به برنامه‌های دیگر در همان میزبان ارسال نخواهند کرد. MSDN را ببینید: https://learn.microsoft.com/en-us/windows/win32/winsock/ip-multicast-2

فراخوانی این روش به اجازه‌های چندپخشی نیاز ندارد.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • فعال شد

    بولی

    مشخص کنید که آیا حالت برگشت فعال شود یا نه.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (result: number) => void

    • نتیجه

      شماره

      کد نتیجه از تماس شبکه زیربنایی برگردانده شد. مقدار منفی نشان‌دهنده خطا است.

setMulticastTimeToLive()

chrome.sockets.udp.setMulticastTimeToLive(
  socketId: number,
  ttl: number,
  callback: function,
): void

زمان بقای بسته‌های چندفرستی ارسال‌شده به گروه چندفرستی را تنظیم می‌کند.

فراخوانی این روش به اجازه‌های چندپخشی نیاز ندارد.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • ttl

    شماره

    مقدار طول عمر.

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (result: number) => void

    • نتیجه

      شماره

      کد نتیجه از تماس شبکه زیربنایی برگردانده شد. مقدار منفی نشان‌دهنده خطا است.

setPaused()

قول 
chrome.sockets.udp.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
): Promise<void>

سوکت را موقتاً متوقف می‌کند یا از توقف موقت خارج می‌کند. سوکت موقتاً متوقف‌شده از راه‌اندازی رویدادهای onReceive مسدود شده است.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • موقتاً متوقف‌شده

    بولی

    پرچم نشان‌دهنده اینکه آیا باید موقتاً متوقف شود یا از توقف موقت خارج شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

update()

قول 
chrome.sockets.udp.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>

ویژگی‌های سوکت را به‌روز می‌کند.

پارامترها

  • socketId

    شماره

    شناسه سوکت.

  • اقامتگاه‌ها

    SocketProperties

    ویژگی‌هایی که باید به‌روز شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۲۱ و بالاتر

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onReceive

chrome.sockets.udp.onReceive.addListener(
  callback: function,
)

رویداد زمانی ایجاد می‌شود که بسته UDP برای سوکت داده‌شده دریافت شده باشد.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (info: ReceiveInfo) => void

onReceiveError

chrome.sockets.udp.onReceiveError.addListener(
  callback: function,
)

رویدادی که هنگام وقوع خطای شبکه درحالی‌که زمان اجرا منتظر داده در نشانی و درگاه سوکت بود، ایجاد شد. وقتی این رویداد مطرح می‌شود، سوکت موقتاً متوقف می‌شود و تا زمانی که سوکت ازسر گرفته نشود، هیچ رویداد onReceive دیگری برای این سوکت مطرح نخواهد شد.

پارامترها