1/* Copyright (c) 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/** 7 * This file defines the Pepper equivalent of the <code>chrome.socket</code> 8 * extension API. 9 */ 10 11label Chrome { 12 M28 = 0.1, 13 M29 = 0.2 14}; 15 16/** 17 * A string <code>PP_Var</code> which has one of the following values: 18 * - "tcp" 19 * - "udp" 20 */ 21typedef PP_Var PP_Ext_Socket_SocketType_Dev; 22 23/** 24 * A dictionary <code>PP_Var</code>. 25 */ 26typedef PP_Var PP_Ext_Socket_CreateOptions_Dev; 27 28/** 29 * A dictionary <code>PP_Var</code> which contains 30 * - "socketId" : integer <code>PP_Var</code> 31 * The id of the newly created socket. 32 */ 33typedef PP_Var PP_Ext_Socket_CreateInfo_Dev; 34 35/** 36 * A dictionary <code>PP_Var</code> which contains 37 * - "resultCode" : integer <code>PP_Var</code> 38 * - "socketId" : integer or undefined <code>PP_Var</code> 39 * The id of the accepted socket. 40 */ 41typedef PP_Var PP_Ext_Socket_AcceptInfo_Dev; 42 43/** 44 * A dictionary <code>PP_Var</code> which contains 45 * - "resultCode" : integer <code>PP_Var</code> 46 * The resultCode returned from the underlying read() call. 47 * - "data" : array buffer <code>PP_Var</code> 48 */ 49typedef PP_Var PP_Ext_Socket_ReadInfo_Dev; 50 51/** 52 * A dictionary <code>PP_Var</code> which contains 53 * - "bytesWritten" : integer <code>PP_Var</code> 54 * The number of bytes sent, or a negative error code. 55 */ 56typedef PP_Var PP_Ext_Socket_WriteInfo_Dev; 57 58/** 59 * A dictionary <code>PP_Var</code> which contains 60 * - "resultCode" : integer <code>PP_Var</code> 61 * The resultCode returned from the underlying recvfrom() call. 62 * - "data": array buffer <code>PP_Var</code> 63 * - "address": string <code>PP_Var</code> 64 * The address of the remote machine. 65 * - "port": integer <code>PP_Var</code> 66 */ 67typedef PP_Var PP_Ext_Socket_RecvFromInfo_Dev; 68 69/** 70 * A dictionary <code>PP_Var</code> which contains 71 * - "socketType" : string <code>PP_Var</code> which matches the description of 72 * <code>PP_Ext_Socket_SocketType_Dev</code> 73 * The type of the passed socket. This will be <code>tcp</code> or 74 * <code>udp</code>. 75 * - "connected" : boolean <code>PP_Var</code> 76 * Whether or not the underlying socket is connected. 77 * 78 * For <code>tcp</code> sockets, this will remain true even if the remote peer 79 * has disconnected. Reading or writing to the socket may then result in an 80 * error, hinting that this socket should be disconnected via 81 * <code>Disconnect()</code>. 82 * 83 * For <code>udp</code> sockets, this just represents whether a default remote 84 * address has been specified for reading and writing packets. 85 * - "peerAddress" : string or undefined <code>PP_Var</code> 86 * If the underlying socket is connected, contains the IPv4/6 address of the 87 * peer. 88 * - "peerPort" : integer or undefined <code>PP_Var</code> 89 * If the underlying socket is connected, contains the port of the connected 90 * peer. 91 * - "localAddress" : string or undefined <code>PP_Var</code> 92 * If the underlying socket is bound or connected, contains its local IPv4/6 93 * address. 94 * - "localPort" : integer or undefined <code>PP_Var</code> 95 * If the underlying socket is bound or connected, contains its local port. 96 */ 97typedef PP_Var PP_Ext_Socket_SocketInfo_Dev; 98 99/** 100 * A dictionary <code>PP_Var</code> which contains 101 * - "name" : string <code>PP_Var</code> 102 * The underlying name of the adapter. On *nix, this will typically be "eth0", 103 * "lo", etc. 104 * - "address": string <code>PP_Var</code> 105 * The available IPv4/6 address. 106 */ 107typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev; 108 109/** 110 * An array <code>PP_Var</code> which contains elements of 111 * <code>PP_Ext_Socket_NetworkInterface_Dev</code>. 112 */ 113typedef PP_Var PP_Ext_Socket_NetworkInterface_Dev_Array; 114 115interface PPB_Ext_Socket_Dev { 116 /** 117 * Creates a socket of the specified type that will connect to the specified 118 * remote machine. 119 * 120 * @param[in] instance A <code>PP_Instance</code>. 121 * @param[in] type A <code>PP_Ext_Socket_SocketType_Dev</code>. The type of 122 * socket to create. Must be <code>tcp</code> or <code>udp</code>. 123 * @param[in] options An undefined <code>PP_Var</code> or 124 * <code>PP_Ext_Socket_CreateOptions_Dev</code>. The socket options. 125 * @param[out] create_info A <code>PP_Ext_Socket_CreateInfo_Dev</code>. 126 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 127 * upon completion. 128 * 129 * @return An error code from <code>pp_errors.h</code>. 130 */ 131 int32_t Create( 132 [in] PP_Instance instance, 133 [in] PP_Ext_Socket_SocketType_Dev type, 134 [in] PP_Ext_Socket_CreateOptions_Dev options, 135 [out] PP_Ext_Socket_CreateInfo_Dev create_info, 136 [in] PP_CompletionCallback callback); 137 138 /** 139 * Destroys the socket. Each socket created should be destroyed after use. 140 * 141 * @param[in] instance A <code>PP_Instance</code>. 142 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 143 */ 144 void Destroy( 145 [in] PP_Instance instance, 146 [in] PP_Var socket_id); 147 148 /** 149 * Connects the socket to the remote machine (for a <code>tcp</code> socket). 150 * For a <code>udp</code> socket, this sets the default address which packets 151 * are sent to and read from for <code>Read()</code> and <code>Write()</code> 152 * calls. 153 * 154 * @param[in] instance A <code>PP_Instance</code>. 155 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 156 * @param[in] hostname A string <code>PP_Var</code>. The hostname or IP 157 * address of the remote machine. 158 * @param[in] port An integer <code>PP_Var</code>. The port of the remote 159 * machine. 160 * @param[out] result An integer <code>PP_Var</code>. 161 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 162 * upon completion. 163 * 164 * @return An error code from <code>pp_errors.h</code>. 165 */ 166 int32_t Connect( 167 [in] PP_Instance instance, 168 [in] PP_Var socket_id, 169 [in] PP_Var hostname, 170 [in] PP_Var port, 171 [out] PP_Var result, 172 [in] PP_CompletionCallback callback); 173 174 /** 175 * Binds the local address for socket. Currently, it does not support TCP 176 * socket. 177 * 178 * @param[in] instance A <code>PP_Instance</code>. 179 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 180 * @param[in] address A string <code>PP_Var</code>. The address of the local 181 * machine. 182 * @param[in] port An integer <code>PP_Var</code>. The port of the local 183 * machine. 184 * @param[out] result An integer <code>PP_Var</code>. 185 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 186 * upon completion. 187 * 188 * @return An error code from <code>pp_errors.h</code>. 189 */ 190 int32_t Bind( 191 [in] PP_Instance instance, 192 [in] PP_Var socket_id, 193 [in] PP_Var address, 194 [in] PP_Var port, 195 [out] PP_Var result, 196 [in] PP_CompletionCallback callback); 197 198 /** 199 * Disconnects the socket. For UDP sockets, <code>Disconnect</code> is a 200 * non-operation but is safe to call. 201 * 202 * @param[in] instance A <code>PP_Instance</code>. 203 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 204 */ 205 void Disconnect( 206 [in] PP_Instance instance, 207 [in] PP_Var socket_id); 208 209 /** 210 * Reads data from the given connected socket. 211 * 212 * @param[in] instance A <code>PP_Instance</code>. 213 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 214 * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The 215 * read buffer size. 216 * @param[out] read_info A <code>PP_Ext_Socket_ReadInfo_Dev</code>. 217 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 218 * upon completion. 219 * 220 * @return An error code from <code>pp_errors.h</code>. 221 */ 222 int32_t Read( 223 [in] PP_Instance instance, 224 [in] PP_Var socket_id, 225 [in] PP_Var buffer_size, 226 [out] PP_Ext_Socket_ReadInfo_Dev read_info, 227 [in] PP_CompletionCallback callback); 228 229 /** 230 * Writes data on the given connected socket. 231 * 232 * @param[in] instance A <code>PP_Instance</code>. 233 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 234 * @param[in] data An array buffer <code>PP_Var</code>. The data to write. 235 * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>. 236 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 237 * upon completion. 238 * 239 * @return An error code from <code>pp_errors.h</code>. 240 */ 241 int32_t Write( 242 [in] PP_Instance instance, 243 [in] PP_Var socket_id, 244 [in] PP_Var data, 245 [out] PP_Ext_Socket_WriteInfo_Dev write_info, 246 [in] PP_CompletionCallback callback); 247 248 /** 249 * Receives data from the given UDP socket. 250 * 251 * @param[in] instance A <code>PP_Instance</code>. 252 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 253 * @param[in] buffer_size An undefined or integer <code>PP_Var</code>. The 254 * receive buffer size. 255 * @param[out] recv_from_info A <code>PP_Ext_Socket_RecvFromInfo_Dev</code>. 256 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 257 * upon completion. 258 * 259 * @return An error code from <code>pp_errors.h</code>. 260 */ 261 int32_t RecvFrom( 262 [in] PP_Instance instance, 263 [in] PP_Var socket_id, 264 [in] PP_Var buffer_size, 265 [out] PP_Ext_Socket_RecvFromInfo_Dev recv_from_info, 266 [in] PP_CompletionCallback callback); 267 268 /** 269 * Sends data on the given UDP socket to the given address and port. 270 * 271 * @param[in] instance A <code>PP_Instance</code>. 272 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 273 * @param[in] data An array buffer <code>PP_Var</code>. 274 * @param[in] address A string <code>PP_Var</code>. The address of the remote 275 * machine. 276 * @param[in] port An integer <code>PP_Var</code>. The port of the remote 277 * machine. 278 * @param[out] write_info A <code>PP_Ext_Socket_WriteInfo_Dev</code>. 279 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 280 * upon completion. 281 * 282 * @return An error code from <code>pp_errors.h</code>. 283 */ 284 int32_t SendTo( 285 [in] PP_Instance instance, 286 [in] PP_Var socket_id, 287 [in] PP_Var data, 288 [in] PP_Var address, 289 [in] PP_Var port, 290 [out] PP_Ext_Socket_WriteInfo_Dev write_info, 291 [in] PP_CompletionCallback callback); 292 293 /** 294 * This method applies to TCP sockets only. 295 * Listens for connections on the specified port and address. This effectively 296 * makes this a server socket, and client socket functions (Connect, Read, 297 * Write) can no longer be used on this socket. 298 * 299 * @param[in] instance A <code>PP_Instance</code>. 300 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 301 * @param[in] address A string <code>PP_Var</code>. The address of the local 302 * machine. 303 * @param[in] port An integer <code>PP_Var</code>. The port of the local 304 * machine. 305 * @param[in] backlog An undefined or integer <code>PP_Var</code>. Length of 306 * the socket's listen queue. 307 * @param[out] result An integer <code>PP_Var</code>. 308 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 309 * upon completion. 310 * 311 * @return An error code from <code>pp_errors.h</code>. 312 */ 313 int32_t Listen( 314 [in] PP_Instance instance, 315 [in] PP_Var socket_id, 316 [in] PP_Var address, 317 [in] PP_Var port, 318 [in] PP_Var backlog, 319 [out] PP_Var result, 320 [in] PP_CompletionCallback callback); 321 322 /** 323 * This method applies to TCP sockets only. 324 * Registers a callback function to be called when a connection is accepted on 325 * this listening server socket. Listen must be called first. 326 * If there is already an active accept callback, this callback will be 327 * invoked immediately with an error as the resultCode. 328 * 329 * @param[in] instance A <code>PP_Instance</code>. 330 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 331 * @param[out] accept_info A <code>PP_Ext_Socket_AcceptInfo_Dev</code>. 332 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 333 * upon completion. 334 * 335 * @return An error code from <code>pp_errors.h</code>. 336 */ 337 int32_t Accept( 338 [in] PP_Instance instance, 339 [in] PP_Var socket_id, 340 [out] PP_Ext_Socket_AcceptInfo_Dev accept_info, 341 [in] PP_CompletionCallback callback); 342 343 /** 344 * Enables or disables the keep-alive functionality for a TCP connection. 345 * 346 * @param[in] instance A <code>PP_Instance</code>. 347 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 348 * @param[in] enable A boolean <code>PP_Var</code>. If true, enable keep-alive 349 * functionality. 350 * @param[in] delay An undefined or integer <code>PP_Var</code>. Set the delay 351 * seconds between the last data packet received and the first keepalive 352 * probe. Default is 0. 353 * @param[out] result A boolean <code>PP_Var</code>. 354 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 355 * upon completion. 356 * 357 * @return An error code from <code>pp_errors.h</code>. 358 */ 359 int32_t SetKeepAlive( 360 [in] PP_Instance instance, 361 [in] PP_Var socket_id, 362 [in] PP_Var enable, 363 [in] PP_Var delay, 364 [out] PP_Var result, 365 [in] PP_CompletionCallback callback); 366 367 /** 368 * Sets or clears <code>TCP_NODELAY</code> for a TCP connection. Nagle's 369 * algorithm will be disabled when <code>TCP_NODELAY</code> is set. 370 * 371 * @param[in] instance A <code>PP_Instance</code>. 372 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 373 * @param[in] no_delay A boolean <code>PP_Var</code>. 374 * @param[out] result A boolean <code>PP_Var</code>. 375 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 376 * upon completion. 377 * 378 * @return An error code from <code>pp_errors.h</code>. 379 */ 380 int32_t SetNoDelay( 381 [in] PP_Instance instance, 382 [in] PP_Var socket_id, 383 [in] PP_Var no_delay, 384 [out] PP_Var result, 385 [in] PP_CompletionCallback callback); 386 387 /** 388 * Retrieves the state of the given socket. 389 * 390 * @param[in] instance A <code>PP_Instance</code>. 391 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 392 * @param[out] result A <code>PP_Ext_Socket_SocketInfo_Dev</code>. 393 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 394 * upon completion. 395 * 396 * @return An error code from <code>pp_errors.h</code>. 397 */ 398 int32_t GetInfo( 399 [in] PP_Instance instance, 400 [in] PP_Var socket_id, 401 [out] PP_Ext_Socket_SocketInfo_Dev result, 402 [in] PP_CompletionCallback callback); 403 404 /** 405 * Retrieves information about local adapters on this system. 406 * 407 * @param[in] instance A <code>PP_Instance</code>. 408 * @param[out] result A <code>PP_Ext_Socket_NetworkInterface_Dev_Array</code>. 409 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 410 * upon completion. 411 * 412 * @return An error code from <code>pp_errors.h</code>. 413 */ 414 int32_t GetNetworkList( 415 [in] PP_Instance instance, 416 [out] PP_Ext_Socket_NetworkInterface_Dev_Array result, 417 [in] PP_CompletionCallback callback); 418 419 /** 420 * Joins the multicast group and starts to receive packets from that group. 421 * The socket must be of UDP type and must be bound to a local port before 422 * calling this method. 423 * 424 * @param[in] instance A <code>PP_Instance</code>. 425 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 426 * @param[in] address A string <code>PP_Var</code>. The group address to join. 427 * Domain names are not supported. 428 * @param[out] result An integer <code>PP_Var</code>. 429 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 430 * upon completion. 431 * 432 * @return An error code from <code>pp_errors.h</code>. 433 */ 434 [version=0.2] 435 int32_t JoinGroup( 436 [in] PP_Instance instance, 437 [in] PP_Var socket_id, 438 [in] PP_Var address, 439 [out] PP_Var result, 440 [in] PP_CompletionCallback callback); 441 442 /** 443 * Leaves the multicast group previously joined using <code>JoinGroup</code>. 444 * It's not necessary to leave the multicast group before destroying the 445 * socket or exiting. This is automatically called by the OS. 446 * 447 * Leaving the group will prevent the router from sending multicast datagrams 448 * to the local host, presuming no other process on the host is still joined 449 * to the group. 450 * 451 * @param[in] instance A <code>PP_Instance</code>. 452 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 453 * @param[in] address A string <code>PP_Var</code>. The group address to 454 * leave. Domain names are not supported. 455 * @param[out] result An integer <code>PP_Var</code>. 456 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 457 * upon completion. 458 * 459 * @return An error code from <code>pp_errors.h</code>. 460 */ 461 [version=0.2] 462 int32_t LeaveGroup( 463 [in] PP_Instance instance, 464 [in] PP_Var socket_id, 465 [in] PP_Var address, 466 [out] PP_Var result, 467 [in] PP_CompletionCallback callback); 468 469 /** 470 * Sets the time-to-live of multicast packets sent to the multicast group. 471 * 472 * Calling this method does not require multicast permissions. 473 * 474 * @param[in] instance A <code>PP_Instance</code>. 475 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 476 * @param[in] ttl An integer <code>PP_Var</code>. The time-to-live value. 477 * @param[out] result An integer <code>PP_Var</code>. 478 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 479 * upon completion. 480 * 481 * @return An error code from <code>pp_errors.h</code>. 482 */ 483 [version=0.2] 484 int32_t SetMulticastTimeToLive( 485 [in] PP_Instance instance, 486 [in] PP_Var socket_id, 487 [in] PP_Var ttl, 488 [out] PP_Var result, 489 [in] PP_CompletionCallback callback); 490 491 /** 492 * Sets whether multicast packets sent from the host to the multicast group 493 * will be looped back to the host. 494 * 495 * Note: the behavior of <code>SetMulticastLoopbackMode</code> is slightly 496 * different between Windows and Unix-like systems. The inconsistency 497 * happens only when there is more than one application on the same host 498 * joined to the same multicast group while having different settings on 499 * multicast loopback mode. On Windows, the applications with loopback off 500 * will not RECEIVE the loopback packets; while on Unix-like systems, the 501 * applications with loopback off will not SEND the loopback packets to 502 * other applications on the same host. See MSDN: http://goo.gl/6vqbj 503 * 504 * Calling this method does not require multicast permissions. 505 * 506 * @param[in] instance A <code>PP_Instance</code>. 507 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 508 * @param[in] enabled A boolean <code>PP_Var</code>. Indicates whether to 509 * enable loopback mode. 510 * @param[out] result An integer <code>PP_Var</code>. 511 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 512 * upon completion. 513 * 514 * @return An error code from <code>pp_errors.h</code>. 515 */ 516 [version=0.2] 517 int32_t SetMulticastLoopbackMode( 518 [in] PP_Instance instance, 519 [in] PP_Var socket_id, 520 [in] PP_Var enabled, 521 [out] PP_Var result, 522 [in] PP_CompletionCallback callback); 523 524 /** 525 * Gets the multicast group addresses the socket is currently joined to. 526 * 527 * @param[in] instance A <code>PP_Instance</code>. 528 * @param[in] socket_id An integer <code>PP_Var</code>. The socket ID. 529 * @param[out] groups An array <code>PP_Var</code> of string 530 * <code>PP_Var</code>s. 531 * @param[in] callback A <code>PP_CompletionCallback</code> to be called 532 * upon completion. 533 * 534 * @return An error code from <code>pp_errors.h</code>. 535 */ 536 [version=0.2] 537 int32_t GetJoinedGroups( 538 [in] PP_Instance instance, 539 [in] PP_Var socket_id, 540 [out] PP_Var groups, 541 [in] PP_CompletionCallback callback); 542}; 543