@types/chrome 0.0.36 → 0.0.40

chrome/README.md

@@ -5,13 +5,12 @@
 This package contains type definitions for Chrome extension development (http://developer.chrome.com/extensions/).
 
 # Details
-Files were exported from https://www.github.com/DefinitelyTyped/DefinitelyTyped/tree/types-2.0/chrome
+Files were exported from https://www.github.com/DefinitelyTyped/DefinitelyTyped/tree/master/chrome
 
 Additional Details
- * Last updated: Mon, 12 Dec 2016 22:50:15 GMT
- * Library Dependencies: filesystem
- * Module Dependencies: none
+ * Last updated: Fri, 10 Feb 2017 23:02:30 GMT
+ * Dependencies: filesystem
  * Global values: chrome
 
 # Credits
-These definitions were written by Matthew Kimber <https://github.com/matthewkimber>, otiai10 <https://github.com/otiai10>, couven92 <https://github.com/couven92>, RReverser <https://github.com/rreverser>.
+These definitions were written by Matthew Kimber <https://github.com/matthewkimber>, otiai10 <https://github.com/otiai10>, couven92 <https://github.com/couven92>, RReverser <https://github.com/rreverser>, sreimer15 <https://github.com/sreimer15>.

chrome/chrome-app.d.ts

@@ -355,6 +355,14 @@ declare namespace chrome.sockets.tcp {
     var onReceiveError: chrome.events.Event<(args: ReceiveErrorEventArgs) => void>;
 }
 
+/**
+ * Use the chrome.sockets.udp API to send and receive data over the network
+ * using UDP connections. This API supersedes the UDP functionality previously
+ * found in the "socket" API.
+ *
+ * @since Chrome 33
+ * @see https://developer.chrome.com/apps/sockets_udp
+ */
 declare namespace chrome.sockets.udp {
     interface CreateInfo {
         socketId: number;
@@ -377,43 +385,278 @@ declare namespace chrome.sockets.udp {
         resultCode: number;
     }
 
+    /**
+     * @see https://developer.chrome.com/apps/sockets_udp#type-SocketProperties
+     */
     interface SocketProperties {
+        /**
+         * Flag indicating if the socket is left open when the event page of the
+         * application is unloaded. The default value is "false." When the
+         * application is loaded, any sockets previously opened with
+         * persistent=true can be fetched with getSockets.
+         * @see http://developer.chrome.com/apps/app_lifecycle.html
+         */
         persistent?: boolean;
+
+        /** An application-defined string associated with the socket. */
         name?: string;
+
+        /**
+         * The size of the buffer used to receive data. If the buffer is too
+         * small to receive the UDP packet, data is lost. The default value is
+         * 4096.
+         */
         bufferSize?: number;
     }
 
+    /**
+     * @see https://developer.chrome.com/apps/sockets_udp#type-SocketInfo
+     */
     interface SocketInfo {
+        /** The socket identifier. */
         socketId: number;
+
+        /**
+         * Flag indicating whether the socket is left open when the application
+         * is suspended (see SocketProperties.persistent).
+         */
         persistent: boolean;
+
+        /** Application-defined string associated with the socket. */
         name?: string;
+
+        /**
+         * The size of the buffer used to receive data. If no buffer size ha
+         * been specified explictly, the value is not provided.
+         */
         bufferSize?: number;
+
+        /**
+         * Flag indicating whether the socket is blocked from firing onReceive
+         * events.
+         */
         paused: boolean;
+
+        /**
+         * If the underlying socket is bound, contains its local IPv4/6 address.
+         */
         localAddress?: string;
+
+        /**
+         * If the underlying socket is bound, contains its local port.
+         */
         localPort?: number;
     }
 
+    /**
+     * Creates a UDP socket with default properties.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-create
+     * @param createInfo.socketId The ID of the newly created socket.
+     */
     export function create(callback: (createInfo: CreateInfo) => void): void;
-    export function create(properties: SocketProperties,
-        callback: (createInfo: CreateInfo) => void): void;
 
+    /**
+     * Creates a UDP socket with the given properties.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-create
+     * @param properties          The socket properties.
+     * @param createInfo.socketId The ID of the newly created socket.
+     */
+    export function create(properties: SocketProperties, callback: (createInfo: CreateInfo) => void): void;
+
+    /**
+     * Updates the socket properties.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-update
+     * @param socketId   The socket ID.
+     * @param properties The properties to update.
+     * @param callback   Called when the properties are updated.
+     */
     export function update(socketId: number, properties: SocketProperties, callback?: () => void): void;
+
+    /**
+     * Pauses or unpauses a socket. A paused socket is blocked from firing
+     * onReceive events.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-setPaused
+     * @param socketId The socket ID.
+     * @param paused   Flag to indicate whether to pause or unpause.
+     * @param callback Called when the socket has been successfully paused or
+     *                 unpaused.
+     */
     export function setPaused(socketId: number, paused: boolean, callback?: () => void): void;
+
+    /**
+     * Binds the local address and port for the socket. For a client socket, it
+     * is recommended to use port 0 to let the platform pick a free port.
+     *
+     * Once the bind operation completes successfully, onReceive events are
+     * raised when UDP packets arrive on the address/port specified -- unless
+     * the socket is paused.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-bind
+     * @param socketId The socket ID.
+     * @param address  The address of the local machine. DNS name, IPv4 and IPv6
+     *                 formats are supported. Use "0.0.0.0" to accept packets
+     *                 from all local available network interfaces.
+     * @param port     The port of the local machine. Use "0" to bind to a free
+     *                 port.
+     * @param callback Called when the bind operation completes.
+     */
     export function bind(socketId: number, address: string, port: number, callback: (result: number) => void): void;
+
+    /**
+     * Sends data on the given socket to the given address and port. The socket
+     * must be bound to a local port before calling this method.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-send
+     * @param socketId The socket ID.
+     * @param data     The data to send.
+     * @param address  The address of the remote machine.
+     * @param port     The port of the remote machine.
+     * @param callback Called when the send operation completes.
+     */
     export function send(socketId: number, data: ArrayBuffer, address: string, port: number, callback: (sendInfo: SendInfo) => void): void;
+
+    /**
+     * Closes the socket and releases the address/port the socket is bound to.
+     * Each socket created should be closed after use. The socket id is no
+     * longer valid as soon at the function is called. However, the socket is
+     * guaranteed to be closed only when the callback is invoked.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-close
+     * @param socketId The socket ID.
+     * @param callback Called when the close operation completes.
+     */
     export function close(socketId: number, callback?: () => void): void;
+
+    /**
+     * Retrieves the state of the given socket.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-getInfo
+     * @param socketId The socket ID.
+     * @param callback Called when the socket state is available.
+     */
     export function getInfo(socketId: number, callback: (socketInfo: SocketInfo) => void): void;
+
+    /**
+     * Retrieves the list of currently opened sockets owned by the application.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-getSockets
+     * @param callback Called when the list of sockets is available.
+     */
     export function getSockets(callback: (socketInfos: SocketInfo[]) => void): void;
+
+    /**
+     * Joins the multicast group and starts to receive packets from that group.
+     * The socket must be bound to a local port before calling this method.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-joinGroup
+     * @param socketId The socket ID.
+     * @param address  The group address to join. Domain names are not supported.
+     * @param callback Called when the joinGroup operation completes.
+     */
     export function joinGroup(socketId: number, address: string, callback: (result: number) => void): void;
+
+    /**
+     * Leaves the multicast group previously joined using joinGroup. This is
+     * only necessary to call if you plan to keep using the socket afterwards,
+     * since it will be done automatically by the OS when the socket is closed.
+     *
+     * Leaving the group will prevent the router from sending multicast
+     * datagrams to the local host, presuming no other process on the host is
+     * still joined to the group.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-leaveGroup
+     * @param socketId The socket ID.
+     * @param address  The group address to leave. Domain names are not
+     *                 supported.
+     * @param callback Called when the leaveGroup operation completes.
+     */
     export function leaveGroup(socketId: number, address: string, callback: (result: number) => void): void;
+
+    /**
+     * Sets the time-to-live of multicast packets sent to the multicast group.
+     *
+     * Calling this method does not require multicast permissions.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-setMulticastTimeToLive
+     * @param socketId The socket ID.
+     * @param ttl      The time-to-live value.
+     * @param callback Called when the configuration operation completes.
+     */
     export function setMulticastTimeToLive(socketId: number, ttl: number, callback: (result: number) => void): void;
+
+    /**
+     * Sets whether multicast packets sent from the host to the multicast group
+     * will be looped back to the host.
+     *
+     * Note: the behavior of setMulticastLoopbackMode is slightly different
+     * between Windows and Unix-like systems. The inconsistency happens only
+     * when there is more than one application on the same host joined to the
+     * same multicast group while having different settings on multicast
+     * loopback mode. On Windows, the applications with loopback off will not
+     * RECEIVE the loopback packets; while on Unix-like systems, the
+     * applications with loopback off will not SEND the loopback packets to
+     * other applications on the same host.
+     * @see MSDN: http://goo.gl/6vqbj
+     *
+     * Calling this method does not require multicast permissions.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-setMulticastLoopbackMode
+     * @param socketId The socket ID.
+     * @param enabled  Indicate whether to enable loopback mode.
+     * @param callback Called when the configuration operation completes.
+     */
     export function setMulticastLoopbackMode(socketId: number, enabled: boolean, callback: (result: number) => void): void;
+
+    /**
+     * Gets the multicast group addresses the socket is currently joined to.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#method-getJoinedGroups
+     * @param socketId The socket ID.
+     * @param callback Called with an array of strings of the result.
+     */
     export function getJoinedGroups(socketId: number, callback: (groups: string[]) => void): void;
 
+    /**
+     * Enables or disables broadcast packets on this socket.
+     *
+     * @since Chrome 44
+     * @see https://developer.chrome.com/apps/sockets_udp#method-setBroadcast
+     * @param socketId The socket ID.
+     * @param enabled  true to enable broadcast packets, false to disable them.
+     * @param callback Callback from the setBroadcast method.
+     */
+    export function setBroadcast(socketId: number, enabled: boolean, callback?: (result: number) => void): void;
+
+    /**
+     * Event raised when a UDP packet has been received for the given socket.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#event-onReceive
+     */
     var onReceive: chrome.events.Event<(args: ReceiveEventArgs) => void>;
+
+    /**
+     * Event raised when a network error occured while the runtime was waiting
+     * for data on the socket address and port. Once this event is raised, the
+     * socket is paused and no more onReceive events will be raised for this
+     * socket until the socket is resumed.
+     *
+     * @see https://developer.chrome.com/apps/sockets_udp#event-onReceiveError
+     */
     var onReceiveError: chrome.events.Event<(args: ReceiveErrorEventArgs) => void>;
 }
 
+/**
+ * Use the chrome.sockets.tcpServer API to create server applications using TCP
+ * connections. This API supersedes the TCP functionality previously found in
+ * the chrome.socket API.
+ *
+ * @since Chrome 33
+ * @see https://developer.chrome.com/apps/sockets_tcpServer
+ */
 declare namespace chrome.sockets.tcpServer {
     interface CreateInfo {
         socketId: number;
@@ -429,36 +672,180 @@ declare namespace chrome.sockets.tcpServer {
         resultCode: number;
     }
 
+    /**
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#type-SocketProperties
+     */
     interface SocketProperties {
+        /**
+         * Flag indicating if the socket remains open when the event page of the
+         * application is unloaded. The default value is "false." When the
+         * application is loaded, any sockets previously opened with
+         * persistent=true can be fetched with getSockets.
+         *
+         * @see http://developer.chrome.com/apps/app_lifecycle.html
+         */
         persistent?: boolean;
+
+        /** An application-defined string associated with the socket. */
         name?: string;
     }
 
+    /**
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#type-SocketInfo
+     */
     interface SocketInfo {
+        /** The socket identifier. */
         socketId: number;
+
+        /**
+         * Flag indicating if the socket remains open when the event page of the
+         * application is unloaded (see SocketProperties.persistent). The
+         * default value is "false".
+         */
         persistent: boolean;
+
+        /** Application-defined string associated with the socket. */
         name?: string;
+
+        /**
+         * Flag indicating whether connection requests on a listening socket are
+         * dispatched through the onAccept event or queued up in the listen
+         * queue backlog. See setPaused. The default value is "false"
+         */
         paused: boolean;
+
+        /** If the socket is listening, contains its local IPv4/6 address. */
         localAddress?: string;
+
+        /** If the socket is listening, contains its local port. */
         localPort?: number;
     }
 
+    /**
+     * Creates a TCP server socket.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-create
+     * @param callback Called when the socket has been created.
+     */
     export function create(callback: (createInfo: CreateInfo) => void): void;
+
+    /**
+     * Creates a TCP server socket.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-create
+     * @param properties The socket properties.
+     * @param callback   Called when the socket has been created.
+     */
     export function create(properties: SocketProperties, callback: (createInfo: CreateInfo) => void): void;
 
+    /**
+     * Updates the socket properties.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-update
+     * @param socketId   The socket identifier.
+     * @param properties The properties to update.
+     * @param callback   Called when the properties are updated.
+     */
     export function update(socketId: number, properties: SocketProperties, callback?: () => void): void;
-    export function setPaused(socketId: number, paused: boolean, callback?: () => void): void;
 
-    export function listen(socketId: number, address: string,
-        port: number, backlog: number, callback: (result: number) => void): void;
-    export function listen(socketId: number, address: string,
-        port: number, callback: (result: number) => void): void;
+    /**
+     * Enables or disables a listening socket from accepting new connections.
+     * When paused, a listening socket accepts new connections until its backlog
+     * (see listen function) is full then refuses additional connection
+     * requests. onAccept events are raised only when the socket is un-paused.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-setPaused
+     * @param callback Callback from the setPaused method.
+     */
+    export function setPaused(socketId: number, paused: boolean, callback?: () => void): void;
 
+    /**
+     * Listens for connections on the specified port and address. If the
+     * port/address is in use, the callback indicates a failure.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-listen
+     * @param socketId The socket identifier.
+     * @param address  The address of the local machine.
+     * @param port     The port of the local machine. When set to 0, a free port
+     *                 is chosen dynamically. The dynamically allocated port can
+     *                 be found by calling getInfo.
+     * @param backlog  Length of the socket's listen queue. The default value
+     *                 depends on the Operating System (SOMAXCONN), which
+     *                 ensures a reasonable queue length for most applications.
+     * @param callback Called when listen operation completes.
+     */
+    export function listen(socketId: number, address: string, port: number, backlog: number, callback: (result: number) => void): void;
+
+    /**
+     * Listens for connections on the specified port and address. If the
+     * port/address is in use, the callback indicates a failure.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-listen
+     * @param socketId The socket identifier.
+     * @param address  The address of the local machine.
+     * @param port     The port of the local machine. When set to 0, a free port
+     *                 is chosen dynamically. The dynamically allocated port can
+     *                 be found by calling getInfo.
+     * @param callback Called when listen operation completes.
+     */
+    export function listen(socketId: number, address: string, port: number, callback: (result: number) => void): void;
+
+    /**
+     * Disconnects the listening socket, i.e. stops accepting new connections
+     * and releases the address/port the socket is bound to. The socket
+     * identifier remains valid, e.g. it can be used with listen to accept
+     * connections on a new port and address.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-disconnect
+     * @param socketId The socket identifier.
+     * @param callback Called when the disconnect attempt is complete.
+     */
     export function disconnect(socketId: number, callback?: () => void): void;
+
+    /**
+     * Disconnects and destroys the socket. Each socket created should be closed
+     * after use. The socket id is no longer valid as soon at the function is
+     * called. However, the socket is guaranteed to be closed only when the
+     * callback is invoked.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-close
+     * @param socketId The socket identifier.
+     * @param callback Called when the close operation completes.
+     */
     export function close(socketId: number, callback?: () => void): void;
-    export function getInfo(socketId: number, callback: (socketInfos: SocketInfo[]) => void): void;
 
+    /**
+     * Retrieves the state of the given socket.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-getInfo
+     * @param socketId The socket identifier.
+     * @param callback Called when the socket state is available.
+     */
+    export function getInfo(socketId: number, callback: (socketInfo: SocketInfo) => void): void;
+
+    /**
+     * Retrieves the list of currently opened sockets owned by the application.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#method-getSockets
+     * @param callback Called when the list of sockets is available.
+     */
+    export function getSockets(callback: (socketInfos: SocketInfo[]) => void): void;
+
+    /**
+     * Event raised when a connection has been made to the server socket.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#event-onAccept
+     */
     var onAccept: chrome.events.Event<(args: AcceptEventArgs) => void>;
+
+    /**
+     * Event raised when a network error occured while the runtime was waiting
+     * for new connections on the socket address and port. Once this event is
+     * raised, the socket is set to paused and no more onAccept events are
+     * raised for this socket until the socket is resumed.
+     *
+     * @see https://developer.chrome.com/apps/sockets_tcpServer#event-onAcceptError
+     */
     var onAcceptError: chrome.events.Event<(args: AcceptErrorEventArgs) => void>;
 }