Class: OpenTok::OpenTok

130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

# File 'lib/opentok/opentok.rb', line 130

def create_session(opts={})

  # normalize opts so all keys are symbols and only include valid_opts
  valid_opts = [ :media_mode, :location ]
  opts = opts.inject({}) do |m,(k,v)|
    if valid_opts.include? k.to_sym
      m[k.to_sym] = v
    end
    m
  end

  # keep opts around for Session constructor, build REST params
  params = opts.clone

  # anything other than :relayed sets the REST param to "disabled", in which case we force
  # opts to be :routed. if we were more strict we could raise an error when the value isn't
  # either :relayed or :routed
  if params.delete(:media_mode) == :routed
    params["p2p.preference"] = "disabled"
  else
    params["p2p.preference"] = "enabled"
    opts[:media_mode] = :relayed
  end
  # location is optional, but it has to be an IP address if specified at all
  unless params[:location].nil?
    raise "location must be an IPv4 address" unless params[:location] =~ Resolv::IPv4::Regex
  end

  response = client.create_session(params)
  Session.new api_key, api_secret, response['sessions']['Session']['session_id'], opts
end

47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173

# File 'lib/opentok/opentok.rb', line 47

class OpenTok

  include TokenGenerator
  generates_tokens({
    :api_key => ->(instance) { instance.api_key },
    :api_secret => ->(instance) { instance.api_secret }
  })

  # @private
  # don't want these to be mutable, may cause bugs related to inconsistency since these values are
  # cached in objects that this can create
  attr_reader :api_key, :api_secret, :api_url

  ##
  # Create a new OpenTok object.
  #
  # @param [String] api_key Your OpenTok API key. See the OpenTok dashboard
  #   (https://dashboard.tokbox.com).
  # @param [String] api_secret Your OpenTok API key.
  # @param [String] api_url Do not set this parameter. It is for internal use by TokBox.
  def initialize(api_key, api_secret , api_url = ::OpenTok::API_URL)
    @api_key = api_key.to_s()
    @api_secret = api_secret
    # TODO: do we really need a copy of this in the instance or should we overwrite the module
    # constant so that other objects can access the same copy?
    @api_url = api_url
  end

  # Creates a new OpenTok session and returns the session ID, which uniquely identifies
  # the session.
  #
  # For example, when using the OpenTok JavaScript library, use the session ID when calling the
  # OT.initSession()</a> method (to initialize an OpenTok session).
  #
  # OpenTok sessions do not expire. However, authentication tokens do expire (see the
  # generateToken() method). Also note that sessions cannot explicitly be destroyed.
  #
  # A session ID string can be up to 255 characters long.
  #
  # Calling this method results in an OpenTokException in the event of an error.
  # Check the error message for details.
  #
  # You can also create a session using the OpenTok REST API (see
  # http://www.tokbox.com/opentok/api/#session_id_production) or the OpenTok dashboard
  # (see https://dashboard.tokbox.com/projects).
  #
  # @param [Hash] opts (Optional) This hash defines options for the session.
  #
  # @option opts [String] :media_mode Determines whether the session will transmit streams the
  #   using OpenTok Media Router (<code>:routed</code>) or not (<code>:relayed</code>).
  #   By default, this property is set to <code>:relayed</code>.
  #
  #   With the <code>mediaMode</code> property set to <code>:relayed</code>, the session
  #   will attempt to transmit streams directly between clients. If clients cannot connect due to
  #   firewall restrictions, the session uses the OpenTok TURN server to relay audio-video
  #   streams.
  #
  #   With the <code>mediaMode</code> property set to <code>:routed</code>, the session
  #   will use the {http://tokbox.com/#multiparty OpenTok Media Router}.
  #   The OpenTok Media Router provides the following benefits:
  #
  #   * The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
  #     (When the <code>mediaMode</code> property is set to <code>:relayed</code>,
  #     each client must send a separate audio-video stream to each client subscribing to
  #     it.)
  #   * The OpenTok Media Router can improve the quality of the user experience through
  #     {http://tokbox.com/#iqc Intelligent Quality Control}. With
  #     Intelligent Quality Control, if a client's connectivity degrades to a degree that
  #     it does not support video for a stream it's subscribing to, the video is dropped on
  #     that client (without affecting other clients), and the client receives audio only.
  #     If the client's connectivity improves, the video returns.
  #   * The OpenTok Media Router supports the {http://tokbox.com/platform/archiving archiving}
  #     feature, which lets you record, save, and retrieve OpenTok sessions.
  #
  # @option opts [String] :location  An IP address that the OpenTok servers will use to
  #     situate the session in its global network. If you do not set a location hint,
  #     the OpenTok servers will be based on the first client connecting to the session.
  #
  # @return [Session] The Session object. The session_id property of the object is the session ID.
  def create_session(opts={})

    # normalize opts so all keys are symbols and only include valid_opts
    valid_opts = [ :media_mode, :location ]
    opts = opts.inject({}) do |m,(k,v)|
      if valid_opts.include? k.to_sym
        m[k.to_sym] = v
      end
      m
    end

    # keep opts around for Session constructor, build REST params
    params = opts.clone

    # anything other than :relayed sets the REST param to "disabled", in which case we force
    # opts to be :routed. if we were more strict we could raise an error when the value isn't
    # either :relayed or :routed
    if params.delete(:media_mode) == :routed
      params["p2p.preference"] = "disabled"
    else
      params["p2p.preference"] = "enabled"
      opts[:media_mode] = :relayed
    end
    # location is optional, but it has to be an IP address if specified at all
    unless params[:location].nil?
      raise "location must be an IPv4 address" unless params[:location] =~ Resolv::IPv4::Regex
    end

    response = client.create_session(params)
    Session.new api_key, api_secret, response['sessions']['Session']['session_id'], opts
  end

  # An Archives object, which lets you work with OpenTok 2.0 archives.
  def archives
    @archives ||= Archives.new client
  end

  protected

  def client
    @client ||= Client.new api_key, api_secret, api_url
  end

end