1 /* Copyright 2013 The Chromium Authors. All rights reserved. 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 */ 5 6 /* From ppb_host_resolver.idl modified Sat Jun 22 11:11:38 2013. */ 7 8 #ifndef PPAPI_C_PPB_HOST_RESOLVER_H_ 9 #define PPAPI_C_PPB_HOST_RESOLVER_H_ 10 11 #include "ppapi/c/pp_bool.h" 12 #include "ppapi/c/pp_completion_callback.h" 13 #include "ppapi/c/pp_instance.h" 14 #include "ppapi/c/pp_macros.h" 15 #include "ppapi/c/pp_resource.h" 16 #include "ppapi/c/pp_stdint.h" 17 #include "ppapi/c/pp_var.h" 18 #include "ppapi/c/ppb_net_address.h" 19 20 #define PPB_HOSTRESOLVER_INTERFACE_1_0 "PPB_HostResolver;1.0" 21 #define PPB_HOSTRESOLVER_INTERFACE PPB_HOSTRESOLVER_INTERFACE_1_0 22 23 /** 24 * @file 25 * This file defines the <code>PPB_HostResolver</code> interface. 26 */ 27 28 29 /** 30 * @addtogroup Enums 31 * @{ 32 */ 33 /** 34 * <code>PP_HostResolver_Flag</code> is an enumeration of flags which can be 35 * OR-ed and passed to the host resolver. Currently there is only one flag 36 * defined. 37 */ 38 typedef enum { 39 /** 40 * Hint to request the canonical name of the host, which can be retrieved by 41 * <code>GetCanonicalName()</code>. 42 */ 43 PP_HOSTRESOLVER_FLAG_CANONNAME = 1 << 0 44 } PP_HostResolver_Flag; 45 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_HostResolver_Flag, 4); 46 /** 47 * @} 48 */ 49 50 /** 51 * @addtogroup Structs 52 * @{ 53 */ 54 /** 55 * <code>PP_HostResolver_Hint</code> represents hints for host resolution. 56 */ 57 struct PP_HostResolver_Hint { 58 /** 59 * Network address family. 60 */ 61 PP_NetAddress_Family family; 62 /** 63 * Combination of flags from <code>PP_HostResolver_Flag</code>. 64 */ 65 int32_t flags; 66 }; 67 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_HostResolver_Hint, 8); 68 /** 69 * @} 70 */ 71 72 /** 73 * @addtogroup Interfaces 74 * @{ 75 */ 76 /** 77 * The <code>PPB_HostResolver</code> interface supports host name 78 * resolution. 79 * 80 * Permissions: In order to run <code>Resolve()</code>, apps permission 81 * <code>socket</code> with subrule <code>resolve-host</code> is required. 82 * For more details about network communication permissions, please see: 83 * http://developer.chrome.com/apps/app_network.html 84 */ 85 struct PPB_HostResolver_1_0 { 86 /** 87 * Creates a host resolver resource. 88 * 89 * @param[in] instance A <code>PP_Instance</code> identifying one instance of 90 * a module. 91 * 92 * @return A <code>PP_Resource</code> corresponding to a host reslover or 0 93 * on failure. 94 */ 95 PP_Resource (*Create)(PP_Instance instance); 96 /** 97 * Determines if a given resource is a host resolver. 98 * 99 * @param[in] resource A <code>PP_Resource</code> to check. 100 * 101 * @return <code>PP_TRUE</code> if the input is a 102 * <code>PPB_HostResolver</code> resource; <code>PP_FALSE</code> otherwise. 103 */ 104 PP_Bool (*IsHostResolver)(PP_Resource resource); 105 /** 106 * Requests resolution of a host name. If the call completes successfully, the 107 * results can be retrieved by <code>GetCanonicalName()</code>, 108 * <code>GetNetAddressCount()</code> and <code>GetNetAddress()</code>. 109 * 110 * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host 111 * resolver. 112 * @param[in] host The host name (or IP address literal) to resolve. 113 * @param[in] port The port number to be set in the resulting network 114 * addresses. 115 * @param[in] hint A <code>PP_HostResolver_Hint</code> structure providing 116 * hints for host resolution. 117 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 118 * completion. 119 * 120 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 121 * <code>PP_ERROR_NOACCESS</code> will be returned if the caller doesn't have 122 * required permissions. <code>PP_ERROR_NAME_NOT_RESOLVED</code> will be 123 * returned if the host name couldn't be resolved. 124 */ 125 int32_t (*Resolve)(PP_Resource host_resolver, 126 const char* host, 127 uint16_t port, 128 const struct PP_HostResolver_Hint* hint, 129 struct PP_CompletionCallback callback); 130 /** 131 * Gets the canonical name of the host. 132 * 133 * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host 134 * resolver. 135 * 136 * @return A string <code>PP_Var</code> on success, which is an empty string 137 * if <code>PP_HOSTRESOLVER_FLAG_CANONNAME</code> is not set in the hint flags 138 * when calling <code>Resolve()</code>; an undefined <code>PP_Var</code> if 139 * there is a pending <code>Resolve()</code> call or the previous 140 * <code>Resolve()</code> call failed. 141 */ 142 struct PP_Var (*GetCanonicalName)(PP_Resource host_resolver); 143 /** 144 * Gets the number of network addresses. 145 * 146 * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host 147 * resolver. 148 * 149 * @return The number of available network addresses on success; 0 if there is 150 * a pending <code>Resolve()</code> call or the previous 151 * <code>Resolve()</code> call failed. 152 */ 153 uint32_t (*GetNetAddressCount)(PP_Resource host_resolver); 154 /** 155 * Gets a network address. 156 * 157 * @param[in] host_resolver A <code>PP_Resource</code> corresponding to a host 158 * resolver. 159 * @param[in] index An index indicating which address to return. 160 * 161 * @return A <code>PPB_NetAddress</code> resource on success; 0 if there is a 162 * pending <code>Resolve()</code> call or the previous <code>Resolve()</code> 163 * call failed, or the specified index is out of range. 164 */ 165 PP_Resource (*GetNetAddress)(PP_Resource host_resolver, uint32_t index); 166 }; 167 168 typedef struct PPB_HostResolver_1_0 PPB_HostResolver; 169 /** 170 * @} 171 */ 172 173 #endif /* PPAPI_C_PPB_HOST_RESOLVER_H_ */ 174 175
