'\" t
.\"     Title: gupnp-binding-tool-1.6
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 05/24/2026
.\"    Manual: GUPnP
.\"    Source: GUPnP 1.6.10
.\"  Language: Persian
.\"
.TH "GUPNP\-BINDING\-TOOL" "1" "" "GUPnP 1\&.6\&.10" "GUPnP"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
gupnp-binding-tool-1.6 \- ایجاد توابع واسط تسهیل‌کننده C برای سرویس‌های UPnP
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBgupnp\-binding\-tool\-1\&.6\fR\ 'u
\fBgupnp\-binding\-tool\-1\&.6\fR [\-\-prefix\ {PREFIX}] [\-\-mode\ {client|server}] {SCPD\ file}
.SH "توضیحات (DESCRIPTION)"
.PP
\fBgupnp\-binding\-tool\-1\&.6\fR
یک فایل SCPD را دریافت کرده و توابع تسهیل‌کننده C تولید می‌کند که توابع واقعی GUPnP را فراخوانی می‌کنند\&. بایندینگ‌های سمت کلاینت را می‌توان به عنوان نسخه‌ای مختص سرویس از API مربوط به GUPnPServiceProxy در نظر گرفت، و بایندینگ‌های سمت سرور نیز همین نقش را برای GUPnPService ایفا می‌کنند\&.
.PP
این توابعِ تولیدشده پرگویی کمتری دارند و به دلیل نوع‌بندی صحیح پارامترهای فراخوانی تابع، ایمن‌تر نیز هستند\&. با استفاده از این بایندینگ‌ها، نوشتن نام صحیح کنش‌ها (actions)، متغیرها و پرس‌وجوها آسان‌تر است (یا دست‌کم خطاها به جای زمان اجرا، به خطاهای زمان کامپایل تبدیل می‌شوند)، و همچنین در تکمیل خودکار ویرایشگر متن (autocompletion) در دسترس خواهند بود\&.
.SH "بایندینگ‌های سمت کلاینت (CLIENT SIDE BINDINGS)"
.PP
به عنوان مثال، این کنش:
.sp
.if n \{\
.RS 4
.\}
.nf
<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>
.fi
.if n \{\
.RE
.\}
.PP
تابع همگام سمت کلاینت (control point) زیر را تولید خواهد کرد:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
همان‌طور که مشاهده می‌شود، آرگومان‌ها دارای انواع صحیح بوده و جهت آرگومان به عنوان پیشوند به آن‌ها اضافه شده است\&.
.PP
\fBgupnp\-binding\-tool\-1\&.6\fR
هر دو نوع بسته‌بندی همگام و ناهمگام را تولید می‌کند\&. مثال
\fBigd_delete_port_mapping\fR
در بالا حالت همگام است؛ حالت ناهمگام به صورت زیر می‌باشد:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
حالت ناهمگام (که با استفاده از
\fBgupnp_service_proxy_begin_action()\fR
و
\fBgupnp_service_proxy_end_action()\fR
پیاده‌سازی شده است) بدون مسدودسازی (blocking) بازمی‌گردد و بعداً با دریافت پاسخ، تابع بازخوانی (callback) را از حلقه اصلی (main loop) فراخوانی می‌کند\&.
.PP
این ابزار همچنین بایندینگ‌هایی برای اعلان‌های متغیر وضعیت (state variable notifications) ایجاد می‌کند\&. این تعریف متغیر وضعیت:
.sp
.if n \{\
.RS 4
.\}
.nf
<stateVariable sendEvents="yes">
  <name>ExternalIPAddress</name>
  <dataType>string</dataType>
</stateVariable>
.fi
.if n \{\
.RE
.\}
.PP
این بایندینگ کلاینت را تولید می‌کند که می‌توان از آن برای دریافت اعلان‌ها در زمان تغییر "ExternalIPAddress" استفاده کرد:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
همهٔ این مثال‌ها با دستور زیر تولید شده‌اند:
gupnp\-binding\-tool\-1\&.6 \-\-prefix igd \-\-mode client WANIPConnection\&.xml\&.
.SH "بایندینگ‌های سمت سرور (SERVER SIDE BINDINGS)"
.PP
بایندینگ‌های متناظر سمت سرور برای همان کنش UPnP (یعنی DeletePortMapping) به این صورت هستند:
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
از تابع تولیدشدهٔ *_action_connect() می‌توان برای اتصال گردانندهٔ کنش (action handler) استفاده کرد\&. سپس می‌توان از توابع *_action_get() و *_action_set() درون گردانندهٔ کنش برای خواندن یا تنظیم متغیرهای کنش استفاده کرد\&. اگر متغیرهایی که اعلان دارند تغییر کنند، باید از *_variable_notify() برای ارسال اعلان‌ها استفاده شود (به زیر مراجعه کنید)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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);
.fi
.if n \{\
.RE
.\}
.PP
از تابع *_query_connect() می‌توان برای متصل کردن گردانندهٔ پرس‌وجوی مختص سرویس استفاده کرد\&. مقدار بازگشتی این گرداننده، همان مقدار بازگردانده‌شدهٔ متغیر وضعیت است\&.
.PP
همهٔ این مثال‌ها با دستور زیر تولید شده‌اند:
gupnp\-binding\-tool\-1\&.6 \-\-prefix igd \-\-mode server WANIPConnection\&.xml\&.