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