نام (NAME)

gupnp-binding-tool-1.6 - ایجاد توابع واسط تسهیل‌کننده C برای سرویس‌های UPnP

خلاصه دستور (SYNOPSIS)

gupnp-binding-tool-1.6 [--prefix {PREFIX}] [--mode {client|server}] {SCPD file}

توضیحات (DESCRIPTION)

gupnp-binding-tool-1.6 یک فایل SCPD را دریافت کرده و توابع تسهیل‌کننده C تولید می‌کند که توابع واقعی GUPnP را فراخوانی می‌کنند. بایندینگ‌های سمت کلاینت را می‌توان به عنوان نسخه‌ای مختص سرویس از API مربوط به GUPnPServiceProxy در نظر گرفت، و بایندینگ‌های سمت سرور نیز همین نقش را برای GUPnPService ایفا می‌کنند.

این توابعِ تولیدشده پرگویی کمتری دارند و به دلیل نوع‌بندی صحیح پارامترهای فراخوانی تابع، ایمن‌تر نیز هستند. با استفاده از این بایندینگ‌ها، نوشتن نام صحیح کنش‌ها (actions)، متغیرها و پرس‌وجوها آسان‌تر است (یا دست‌کم خطاها به جای زمان اجرا، به خطاهای زمان کامپایل تبدیل می‌شوند)، و همچنین در تکمیل خودکار ویرایشگر متن (autocompletion) در دسترس خواهند بود.

بایندینگ‌های سمت کلاینت (CLIENT SIDE BINDINGS)

به عنوان مثال، این کنش:

<action>
  <name>DeletePortMapping</name>
  <argumentList>
    <argument>
      <name>NewRemoteHost</name>
      <direction>in</direction>
      <relatedStateVariable>RemoteHost</relatedStateVariable>
    </argument>
    <argument>
      <name>NewExternalPort</name>
      <direction>in</direction>
      <relatedStateVariable>ExternalPort</relatedStateVariable>
    </argument>
    <argument>
      <name>NewProtocol</name>
      <direction>in</direction>
      <relatedStateVariable>PortMappingProtocol</relatedStateVariable>
    </argument>
  </argumentList>
</action>

تابع همگام سمت کلاینت (control point) زیر را تولید خواهد کرد:

static inline gboolean
igd_delete_port_mapping (GUPnPServiceProxy *proxy,
                         const gchar *in_new_remote_host,
                         const guint in_new_external_port,
                         const gchar *in_new_protocol,
                         GError **error);

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

gupnp-binding-tool-1.6 هر دو نوع بسته‌بندی همگام و ناهمگام را تولید می‌کند. مثال igd_delete_port_mapping در بالا حالت همگام است؛ حالت ناهمگام به صورت زیر می‌باشد:

typedef void (*igd_delete_port_mapping_reply) (GUPnPServiceProxy *proxy,
                                               GError *error,
                                               gpointer userdata);
static inline GUPnPServiceProxyAction *
igd_delete_port_mapping_async (GUPnPServiceProxy *proxy,
                               const gchar *in_new_remote_host,
                               const guint in_new_external_port,
                               const gchar *in_new_protocol,
                               igd_delete_port_mapping_reply callback,
                               gpointer userdata);

حالت ناهمگام (که با استفاده از gupnp_service_proxy_begin_action() و gupnp_service_proxy_end_action() پیاده‌سازی شده است) بدون مسدودسازی (blocking) بازمی‌گردد و بعداً با دریافت پاسخ، تابع بازخوانی (callback) را از حلقه اصلی (main loop) فراخوانی می‌کند.

این ابزار همچنین بایندینگ‌هایی برای اعلان‌های متغیر وضعیت (state variable notifications) ایجاد می‌کند. این تعریف متغیر وضعیت:

<stateVariable sendEvents="yes">
  <name>ExternalIPAddress</name>
  <dataType>string</dataType>
</stateVariable>

این بایندینگ کلاینت را تولید می‌کند که می‌توان از آن برای دریافت اعلان‌ها در زمان تغییر "ExternalIPAddress" استفاده کرد:

typedef void
(*igd_external_ip_address_changed_callback) (GUPnPServiceProxy *proxy,
                                             const gchar *external_ip_address,
                                             gpointer userdata);
static inline gboolean
igd_external_ip_address_add_notify (GUPnPServiceProxy *proxy,
                                    igd_external_ip_address_changed_callback callback,
                                    gpointer userdata);

همهٔ این مثال‌ها با دستور زیر تولید شده‌اند: gupnp-binding-tool-1.6 --prefix igd --mode client WANIPConnection.xml.

بایندینگ‌های سمت سرور (SERVER SIDE BINDINGS)

بایندینگ‌های متناظر سمت سرور برای همان کنش UPnP (یعنی DeletePortMapping) به این صورت هستند:

void
igd_delete_port_mapping_action_get (GUPnPServiceAction *action,
                                    gchar **in_new_remote_host,
                                    guint *in_new_external_port,
                                    gchar **in_new_protocol);
gulong
igd_delete_port_mapping_action_connect (GUPnPService *service,
                                        GCallback callback,
                                        gpointer userdata);

از تابع تولیدشدهٔ *_action_connect() می‌توان برای اتصال گردانندهٔ کنش (action handler) استفاده کرد. سپس می‌توان از توابع *_action_get() و *_action_set() درون گردانندهٔ کنش برای خواندن یا تنظیم متغیرهای کنش استفاده کرد. اگر متغیرهایی که اعلان دارند تغییر کنند، باید از *_variable_notify() برای ارسال اعلان‌ها استفاده شود (به زیر مراجعه کنید).

typedef gchar *(*igd_external_ip_address_query_callback) (GUPnPService *service,
                                                          gpointer userdata);
gulong
igd_external_ip_address_query_connect (GUPnPService *service,
                                       igd_external_ip_address_query_callback callback,
                                       gpointer userdata);
void
igd_external_ip_address_variable_notify (GUPnPService *service,
                                         const gchar *external_ip_address);

از تابع *_query_connect() می‌توان برای متصل کردن گردانندهٔ پرس‌وجوی مختص سرویس استفاده کرد. مقدار بازگشتی این گرداننده، همان مقدار بازگردانده‌شدهٔ متغیر وضعیت است.

همهٔ این مثال‌ها با دستور زیر تولید شده‌اند: gupnp-binding-tool-1.6 --prefix igd --mode server WANIPConnection.xml.