usr/src/man/man3dns_sd/DNSServiceResolve.3dns_sd

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DNSSERVICERESOLVE 3DNS_SD "Aug 20, 2007"
   7 .SH NAME
   8 DNSServiceResolve \- resolve service instances with DNS
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ldns_sd\fR [ \fIlibrary\fR ... ]
  13 #include <dns_sd.h>
  14
  15 \fBDNSServiceErrorType\fR \fIDNSServiceResolve\fR(\fBDNSServiceRef\fR *\fIsdRef\fR,
  16      \fBDNSServiceFlags\fR \fIflags\fR, \fBuint32_t\fR \fIinterfaceIndex\fR, \fBconst char\fR *\fIname\fR,
  17      \fBconst char\fR *\fIregtype\fR, \fBconst char\fR *\fIdomain\fR,
  18      \fBDNSServiceServiceResolveReply\fR \fIcallBack\fR, \fBvoid\fR *\fIcontext\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBtypedef\fR \fIvoid\fR(*\fBDNSServiceResolveReply\fR)(\fBDNSServiceRef\fR \fIsdRef\fR,
  24      \fBDNSServiceFlags\fR \fIflags\fR, \fBuint32_t\fR \fIinterfaceIndex\fR,
  25      \fBDNSServiceErrorType\fR \fIerrorCode\fR, \fBconst char\fR *\fIfullname\fR,
  26      \fBconst char\fR *\fIhosttarget\fR, \fBuint16_t\fR \fIport\fR, \fBuint16_t\fR \fItxtLen\fR,
  27      \fBconst char\fR *\fItxtRecord\fR, \fBvoid\fR *\fIcontext\fR);
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .sp
  32 .LP
  33 The \fBDNSServiceResolve()\fR function is used to resolve a service name
  34 returned by \fBDNSServiceBrowse()\fR to host IP address, port number, and
  35 \fBTXT\fR record. The \fBDNSServiceResolve()\fR function returns results
  36 asynchronously. A \fBDNSServiceResolve()\fR call to resolve service name can be
  37 ended by calling \fBDNSServiceRefDeallocate()\fR. The \fIcallback\fR argument
  38 points to a function of type \fIDNSServiceResolveReply\fR as listed above. The
  39 callback function is invoked on finding a result or when the asynch resolve
  40 call fails. The \fIsdRef\fR argument to \fBDNSServiceResolve()\fR points to an
  41 uninitialized \fIDNSServiceRef\fR. If the call to \fBDNSServiceResolve()\fR
  42 succeeds, \fIsdRef\fR is initialized and \fBkDNSServiceErr_NoError\fR is
  43 returned.
  44 .sp
  45 .LP
  46 The \fIflags\fR argument to \fBDNSServiceResolve()\fR is currently unused and
  47 reserved for future use. The \fIinterfaceIndex\fR argument indicates the
  48 interface on which to resolve the service. If the \fBDNSServiceResolve()\fR
  49 call is the result of an earlier \fBDNSServiceBrowse()\fR operation, pass the
  50 \fIinterfaceIndex\fR to perform a resolve on all interfaces. See the section
  51 "Constants for specifying an interface index" in \fB<dns_sd.h>\fR for more
  52 details. The \fIname\fR parameter is the service instance name to be resolved,
  53 as returned from a \fBDNSServiceBrowse()\fR call. The \fIregtype\fR holds the
  54 service type and the \fIdomain\fR parameter indicates the domain in which the
  55 service instance was found. The \fIcontext\fR parameter points to a value that
  56 is passed to the callback function.
  57 .sp
  58 .LP
  59 The \fIsdRef\fR argument passed to the callback function is initialized by
  60 \fBDNSServiceResolve()\fR call. The \fIflags\fR parameter in the callback
  61 function is currently unused and reserved for future use. The \fIerrorCode\fR
  62 parameter is \fBkDNSServiceErr_NoError\fR on success. Otherwise, it will hold
  63 the error defined in \fB<dns_sd.h>\fR and other parameters are undefined when
  64 \fIerrorCode\fR is nonzero. The \fIfullname\fR parameter in the callback holds
  65 the full service domain name in the format
  66 <\fIservicename\fR>.<\fIprotocol\fR>.<\fIdomain\fR>. The full service domain
  67 name is escaped to follow standard \fBDNS\fR rules. The \fIhosttarget\fR
  68 parameter holds the target hostname of the machine providing the service. The
  69 \fIport\fR parameter indicates the port in network byte order on which the
  70 service accepts connections. The \fItxtLen\fR and \fItxtRecord\fR parameters
  71 hold the length and the \fBTXT\fR record of the service's primary \fBTXT\fR
  72 record. The \fIcontext\fR parameter points to the value that was passed as
  73 \fBcontext\fR to the \fBDNSServiceResolve()\fR call.
  74 .SH RETURN VALUES
  75 .sp
  76 .LP
  77 The \fBDNSServiceResolve\fR function returns \fBkDNSServiceErr_NoError\fR on
  78 success. Otherwise, an error code defined in \fB<dns_sd.h>\fR is returned to
  79 indicate an error has occurred. When an error is returned by
  80 \fBDNSServiceResolve\fR, the callback function is not invoked and the
  81 \fIDNSServiceRef\fR argument is not initialized.
  82 .SH ATTRIBUTES
  83 .sp
  84 .LP
  85 See \fBattributes\fR(5) for description of the following attributes:
  86 .sp
  87
  88 .sp
  89 .TS
  90 box;
  91 c | c
  92 l | l .
  93 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  94 _
  95 Interface Stability     Committed
  96 _
  97 MT-Level        Safe
  98 .TE
  99
 100 .SH SEE ALSO
 101 .sp
 102 .LP
 103 \fBDNSServiceBrowse\fR(3DNS_SD), \fBDNSServiceRefDeallocate\fR(3DNS_SD),
 104 \fBattributes\fR(5)