File: source/peer-privileged.js

  1. /**
  2.  * <blockquote class="info">
  3.  *   Note that this feature requires <code>"isPrivileged"</code> flag to be enabled for the App Key
  4.  *   provided in the <a href="#method_init"><code>init()</code> method</a>, as only Users connecting using
  5.  *   the App Key with this flag enabled (which we call privileged Users / Peers) can retrieve the list of
  6.  *   Peer IDs from Rooms within the same App space.
  7.  *   <a href="http://support.temasys.com.sg/support/solutions/articles/12000012342-what-is-a-privileged-key-">
  8.  *   Read more about privileged App Key feature here</a>.
  9.  * </blockquote>
  10.  * The list of <a href="#method_getPeers"><code>getPeers()</code> method</a> retrieval states.
  11.  * @attribute GET_PEERS_STATE
  12.  * @param {String} ENQUIRED <small>Value <code>"enquired"</code></small>
  13.  *   The value of the state when <code>getPeers()</code> is retrieving the list of Peer IDs
  14.  *   from Rooms within the same App space from the Signaling server.
  15.  * @param {String} RECEIVED <small>Value <code>"received"</code></small>
  16.  *   The value of the state when <code>getPeers()</code> has retrieved the list of Peer IDs
  17.  *   from Rooms within the same App space from the Signaling server successfully.
  18.  * @type JSON
  19.  * @readOnly
  20.  * @for Skylink
  21.  * @since 0.6.1
  22.  */
  23. Skylink.prototype.GET_PEERS_STATE = {
  24. 	ENQUIRED: 'enquired',
  25. 	RECEIVED: 'received'
  26. };
  27.  
  28. /**
  29.  * <blockquote class="info">
  30.  *   Note that this feature requires <code>"isPrivileged"</code> flag to be enabled and
  31.  *   <code>"autoIntroduce"</code> flag to be disabled for the App Key provided in the
  32.  *   <a href="#method_init"><code>init()</code> method</a>, as only Users connecting using
  33.  *   the App Key with this flag enabled (which we call privileged Users / Peers) can retrieve the list of
  34.  *   Peer IDs from Rooms within the same App space.
  35.  *   <a href="http://support.temasys.com.sg/support/solutions/articles/12000012342-what-is-a-privileged-key-">
  36.  *   Read more about privileged App Key feature here</a>.
  37.  * </blockquote>
  38.  * The list of <a href="#method_introducePeer"><code>introducePeer</code> method</a> Peer introduction request states.
  39.  * @attribute INTRODUCE_STATE
  40.  * @param {String} INTRODUCING <small>Value <code>"enquired"</code></small>
  41.  *   The value of the state when introduction request for the selected pair of Peers has been made to the Signaling server.
  42.  * @param {String} ERROR       <small>Value <code>"error"</code></small>
  43.  *   The value of the state when introduction request made to the Signaling server
  44.  *   for the selected pair of Peers has failed.
  45.  * @readOnly
  46.  * @for Skylink
  47.  * @since 0.6.1
  48.  */
  49. Skylink.prototype.INTRODUCE_STATE = {
  50. 	INTRODUCING: 'introducing',
  51. 	ERROR: 'error'
  52. };
  53.  
  54. /**
  55.  * Stores the flag that indicates if "autoIntroduce" is enabled.
  56.  * If enabled, the Peers connecting the same Room will receive each others "enter" message ping.
  57.  * @attribute _autoIntroduce
  58.  * @type Boolean
  59.  * @default true
  60.  * @private
  61.  * @for Skylink
  62.  * @since 0.6.1
  63.  */
  64. Skylink.prototype._autoIntroduce = true;
  65.  
  66. /**
  67.  * Stores the flag that indicates if "isPrivileged" is enabled.
  68.  * If enabled, the User has Privileged features which has the ability to retrieve the list of
  69.  *   Peers in the same App space with <code>getPeers()</code> method
  70.  *   and introduce Peers to each other with <code>introducePeer</code> method.
  71.  * @attribute isPrivileged
  72.  * @type Boolean
  73.  * @default false
  74.  * @private
  75.  * @for Skylink
  76.  * @since 0.6.1
  77.  */
  78. Skylink.prototype._isPrivileged = false;
  79.  
  80. /**
  81.  * Stores the list of Peers retrieved from the Signaling from <code>getPeers()</code> method.
  82.  * @attribute _peerList
  83.  * @type JSON
  84.  * @private
  85.  * @for Skylink
  86.  * @since 0.6.1
  87.  */
  88. Skylink.prototype._peerList = null;
  89.  
  90. /**
  91.  * <blockquote class="info">
  92.  *   Note that this feature requires <code>"isPrivileged"</code> flag to be enabled for the App Key
  93.  *   provided in the <a href="#method_init"><code>init()</code> method</a>, as only Users connecting using
  94.  *   the App Key with this flag enabled (which we call privileged Users / Peers) can retrieve the list of
  95.  *   Peer IDs from Rooms within the same App space.
  96.  *   <a href="http://support.temasys.com.sg/support/solutions/articles/12000012342-what-is-a-privileged-key-">
  97.  *   Read more about privileged App Key feature here</a>.
  98.  * </blockquote>
  99.  * Function that retrieves the list of Peer IDs from Rooms within the same App space.
  100.  * @method getPeers
  101.  * @param {Boolean} [showAll=false] The flag if Signaling server should also return the list of privileged Peer IDs.
  102.  * <small>By default, the Signaling server does not include the list of privileged Peer IDs in the return result.</small>
  103.  * @param {Function} [callback] The callback function fired when request has completed.
  104.  *   <small>Function parameters signature is <code>function (error, success)</code></small>
  105.  *   <small>Function request completion is determined by the <a href="#event_getPeersStateChange">
  106.  *   <code>getPeersStateChange</code> event</a> triggering <code>state</code> parameter payload value as
  107.  *   <code>RECEIVED</code> for request success.</small>
  108.  *   [Rel: Skylink.GET_PEERS_STATE]
  109.  * @param {Error|String} callback.error The error result in request.
  110.  *   <small>Defined as <code>null</code> when there are no errors in request</small>
  111.  *   <small>Object signature is the <code>getPeers()</code> error when retrieving list of Peer IDs from Rooms
  112.  *   within the same App space.</small>
  113.  * @param {JSON} callback.success The success result in request.
  114.  *   <small>Defined as <code>null</code> when there are errors in request</small>
  115.  *   <small>Object signature matches the <code>peerList</code> parameter payload received in the
  116.  *   <a href="#event_getPeersStateChange"><code>getPeersStateChange</code> event</a>.</small>
  117.  * @trigger <ol class="desc-seq">
  118.  *   <li>If App Key provided in the <a href="#method_init"><code>init()</code> method</a> is not
  119.  *   a Privileged enabled Key: <ol><li><b>ABORT</b> and return error.</li></ol></li>
  120.  *   <li>Retrieves the list of Peer IDs from Rooms within the same App space. <ol>
  121.  *   <li><a href="#event_getPeersStateChange"><code>getPeersStateChange</code> event</a> triggers parameter
  122.  *   payload <code>state</code> value as <code>ENQUIRED</code>.</li>
  123.  *   <li>If received list from Signaling server successfully: <ol>
  124.  *   <li><a href="#event_getPeersStateChange"><code>getPeersStateChange</code> event</a> triggers parameter
  125.  *   payload <code>state</code> value as <code>RECEIVED</code>.</li></ol></li></ol>
  126.  * @example
  127.  *   // Example 1: Retrieving the un-privileged Peers
  128.  *   skylinkDemo.joinRoom(function (jRError, jRSuccess) {
  129.  *     if (jRError) return;
  130.  *     skylinkDemo.getPeers(function (error, success) {
  131.  *        if (error) return;
  132.  *        console.log("The list of only un-privileged Peers in the same App space ->", success);
  133.  *     });
  134.  *   });
  135.  *
  136.  *   // Example 2: Retrieving the all Peers (privileged or un-privileged)
  137.  *   skylinkDemo.joinRoom(function (jRError, jRSuccess) {
  138.  *     if (jRError) return;
  139.  *     skylinkDemo.getPeers(true, function (error, success) {
  140.  *        if (error) return;
  141.  *        console.log("The list of all Peers in the same App space ->", success);
  142.  *     });
  143.  *   });
  144.  * @for Skylink
  145.  * @since 0.6.1
  146.  */
  147. Skylink.prototype.getPeers = function(showAll, callback){
  148. 	var self = this;
  149. 	if (!self._isPrivileged){
  150. 		log.warn('Please upgrade your key to privileged to use this function');
  151. 		return;
  152. 	}
  153. 	if (!self._appKey){
  154. 		log.warn('App key is not defined. Please authenticate again.');
  155. 		return;
  156. 	}
  157.  
  158. 	// Only callback is provided
  159. 	if (typeof showAll === 'function'){
  160. 		callback = showAll;
  161. 		showAll = false;
  162. 	}
  163.  
  164. 	self._sendChannelMessage({
  165. 		type: self._SIG_MESSAGE_TYPE.GET_PEERS,
  166. 		showAll: showAll || false
  167. 	});
  168.  
  169. 	self._trigger('getPeersStateChange',self.GET_PEERS_STATE.ENQUIRED, self._user.sid, null);
  170.  
  171. 	log.log('Enquired server for peers within the realm');
  172.  
  173. 	if (typeof callback === 'function'){
  174. 		self.once('getPeersStateChange', function(state, privilegedPeerId, peerList){
  175. 			callback(null, peerList);
  176. 		}, function(state, privilegedPeerId, peerList){
  177. 			return state === self.GET_PEERS_STATE.RECEIVED;
  178. 		});
  179. 	}
  180.  
  181. };
  182.  
  183. /**
  184.  * <blockquote class="info">
  185.  *   Note that this feature requires <code>"isPrivileged"</code> flag to be enabled and
  186.  *   <code>"autoIntroduce"</code> flag to be disabled for the App Key provided in the
  187.  *   <a href="#method_init"><code>init()</code> method</a>, as only Users connecting using
  188.  *   the App Key with this flag enabled (which we call privileged Users / Peers) can retrieve the list of
  189.  *   Peer IDs from Rooms within the same App space.
  190.  *   <a href="http://support.temasys.com.sg/support/solutions/articles/12000012342-what-is-a-privileged-key-">
  191.  *   Read more about privileged App Key feature here</a>.
  192.  * </blockquote>
  193.  * Function that selects and introduces a pair of Peers to start connection with each other.
  194.  * @method introducePeer
  195.  * @param {String} sendingPeerId The Peer ID to be connected with <code>receivingPeerId</code>.
  196.  * @param {String} receivingPeerId The Peer ID to be connected with <code>sendingPeerId</code>.
  197.  * @trigger <ol class="desc-seq">
  198.  *   <li>If App Key provided in the <a href="#method_init"><code>init()</code> method</a> is not
  199.  *   a Privileged enabled Key: <ol><li><b>ABORT</b> and return error.</li></ol></li>
  200.  *   <li>Starts sending introduction request for the selected pair of Peers to the Signaling server. <ol>
  201.  *   <li><a href="#event_introduceStateChange"><code>introduceStateChange</code> event</a> triggers parameter
  202.  *   payload <code>state</code> value as <code>INTRODUCING</code>.</li>
  203.  *   <li>If received errors from Signaling server: <ol>
  204.  *   <li><a href="#event_introduceStateChange"><code>introduceStateChange</code> event</a> triggers parameter
  205.  *   payload <code>state</code> value as <code>ERROR</code>.</li></ol></li></ol></li></ol>
  206.  * @example
  207.  *   // Example 1: Introduce a pair of Peers
  208.  *   skylinkDemo.on("introduceStateChange", function (state, privilegedPeerId, sendingPeerId, receivingPeerId) {
  209.  *	   if (state === skylinkDemo.INTRODUCE_STATE.INTRODUCING) {
  210.  *       console.log("Peer '" + sendingPeerId + "' has been introduced to '" + receivingPeerId + "'");
  211.  *     }
  212.  *   });
  213.  *
  214.  *   skylinkDemo.joinRoom(function (jRError, jRSuccess) {
  215.  *     if (jRError) return;
  216.  *     skylinkDemo.getPeers(function (gPError, gPSuccess) {
  217.  *        if (gPError) return;
  218.  *        skylinkDemo.introducePeer(gPSuccess.roomName[0], gPSuccess.roomName[1]);
  219.  *     });
  220.  *   });
  221.  * @for Skylink
  222.  * @since 0.6.1
  223.  */
  224. Skylink.prototype.introducePeer = function(sendingPeerId, receivingPeerId){
  225. 	var self = this;
  226. 	if (!self._isPrivileged){
  227. 		log.warn('Please upgrade your key to privileged to use this function');
  228. 		self._trigger('introduceStateChange', self.INTRODUCE_STATE.ERROR, self._user.sid, sendingPeerId, receivingPeerId, 'notPrivileged');
  229. 		return;
  230. 	}
  231. 	self._sendChannelMessage({
  232. 		type: self._SIG_MESSAGE_TYPE.INTRODUCE,
  233. 		sendingPeerId: sendingPeerId,
  234. 		receivingPeerId: receivingPeerId
  235. 	});
  236. 	self._trigger('introduceStateChange', self.INTRODUCE_STATE.INTRODUCING, self._user.sid, sendingPeerId, receivingPeerId, null);
  237. 	log.log('Introducing',sendingPeerId,'to',receivingPeerId);
  238. };
  239.  
  240.  
  241.