Class: Interfax::Incoming

Inherits:
Object
  • Object
show all
Defined in:
lib/interfax/incoming.rb

Overview

Interfax::Incoming

Allows interaction with the Interfax Inbound API, documented at: www.interfax.net/en/dev/webservice/reference_in

Retrieving incoming faxes

Set the username and password variables appropriately, and then call one of the query methods, which are described in further detail below.

Interfax::Incoming.username = 'my_interfax_username'
Interfax::Incoming.password = 'my_interfax_password'
faxes = Interfax::Incoming.unread

You can extend Interfax::Incoming, and the query methdos will return instances of your subclass. This is useful for extending functionality, or consolidating your configuration in one place.

class InboundFax < Interfax::Incoming
  self.username = 'my_interfax_username'
  self.password = 'my_interfax_password'

  def write_image_to_file
    File.open("/path/to/file", 'w') { |f| f.write(image)
  end
end

faxes = InboundFax.all # this is an array of InboundFax objects
faxes.map(&:write_image_to_file)

Methods

The methods available for fetching or querying inbound faxes are:

  • #all - Retrieves all inbound faxes, up to limit.

  • #unread - Retrieves any unread faxes, up to limit.

  • #account_all - Retrieves inbound faxes for all users on your account, up to limit. Requires an administrator account.

  • #account_unread - Same as above, but fetches only unread faxes. Also requires an administrator account.

As seen above, these methods return instances of the class they’re called on, which makes it easy to extend your objects for custom functionality.

Configuration

We require that the following two configuration variables be set at the class level, as seen in the examples above.

  • username - [required] Your interfax username.

  • password - [requierd] Your interfax password.

We also support a few other configuration methods, which are explained further in Interfax’s API documentation.

  • limit - [1..100, default 100] The maximum number of faxes to return.

  • mark_as_read - [boolean, default false] Whether or not to mark retrieved faxes as sent.

These options are also accepted as options when requesting faxes:

# Assume username/password already set
Interfax::Incoming.all(:limit => 10, :mark_as_read => true)

Options supplied this way will temporarily override any options set on the class.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(params = nil) ⇒ Incoming

Normally this is instantied for you as a result of calling one of the querying class methods. If you want to instantiate an object yourself, you can pass it the results of the GetList API call, or any object that looks like it. See: www.interfax.net/en/dev/webservice/reference/getlist



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/interfax/incoming.rb', line 171

def initialize(params = nil)
  @username = self.class.username
  @password = self.class.password
  @mark_as_read = self.class.mark_as_read || false
  @chunk_size = 100000

  unless params.nil?
    @message_id = params.messageID
    @message_size = params.messageSize.to_i
    @interfax_number = params.phoneNumber
    @remote_csid = params.remoteCSID
    @message_status = params.messageStatus
    @pages = params.pages
    @message_type = params.messageType
    @receive_time = params.receiveTime
    @caller_id = params.callerID
    @duration = params.messageRecordingDuration
  end
  
  @image = nil
end

Class Attribute Details

.limit ⇒ Object

:nodoc:



78
79
80
 
# File 'lib/interfax/incoming.rb', line 78

def limit
  @limit
end

.mark_as_read ⇒ Object

:nodoc:



78
79
80
 
# File 'lib/interfax/incoming.rb', line 78

def mark_as_read
  @mark_as_read
end

.password ⇒ Object

:nodoc:



78
79
80
 
# File 'lib/interfax/incoming.rb', line 78

def password
  @password
end

.username ⇒ Object

:nodoc:



78
79
80
 
# File 'lib/interfax/incoming.rb', line 78

def username
  @username
end

Instance Attribute Details

#caller_id ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def caller_id
  @caller_id
end

#chunk_size ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def chunk_size
  @chunk_size
end

#duration ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def duration
  @duration
end

#image ⇒ Object

Retrieves the image from the Interfax Inbound API, as a string. Suitable for writing to a file or streaming to a client.



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def image
  @image
end

#interfax_number ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def interfax_number
  @interfax_number
end

#mark_as_read ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def mark_as_read
  @mark_as_read
end

#message_id ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def message_id
  @message_id
end

#message_size ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def message_size
  @message_size
end

#message_status ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def message_status
  @message_status
end

#message_type ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def message_type
  @message_type
end

#pages ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def pages
  @pages
end

#password ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def password
  @password
end

#receive_time ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def receive_time
  @receive_time
end

#remote_csid ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def remote_csid
  @remote_csid
end

#username ⇒ Object

class methods



162
163
164
 
# File 'lib/interfax/incoming.rb', line 162

def username
  @username
end

Class Method Details

.account_all(opts = {}) ⇒ Object

Returns all messages for all users on your account, up to the limit option. Optionally marks the faxes as read. Requires your user be an administrator for your account.

Options (as hash)

Both of these will default to whatever values you’ve set for the class, or 100 (limit) or false (mark_as_read) if you haven’t.

  • :limit - Maximum number of faxes to return.

  • :mark_as_read: Mark fetched faxes as read.



139
140
141
 
# File 'lib/interfax/incoming.rb', line 139

def (opts = {})
  query('AccountAllMessages', opts)
end

.account_unread(opts = {}) ⇒ Object

Returns any unread messages for all users on your account, up to the limit option. Optionally marks the faxes as read. Requires your user be an administrator for your account.

Options (as hash)

Both of these will default to whatever values you’ve set for the class, or 100 (limit) or false (mark_as_read) if you haven’t.

  • :limit - Maximum number of faxes to return.

  • :mark_as_read: Mark fetched faxes as read.



154
155
156
 
# File 'lib/interfax/incoming.rb', line 154

def (opts = {})
  query('AccountNewMessages', opts)
end

.all(opts = {}) ⇒ Object

Returns all inbound messages for your user up to the limit option. Optionally marks the faxes as read.

Options (as hash)

Both of these will default to whatever values you’ve set for the class, or 100 (limit) or false (mark_as_read) if you haven’t.

  • :limit - Maximum number of faxes to return.

  • :mark_as_read: Mark fetched faxes as read.



110
111
112
 
# File 'lib/interfax/incoming.rb', line 110

def all(opts = {})
  query('AllMessages', opts)
end

.query(type, opts = {}) ⇒ Object

:nodoc:



86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/interfax/incoming.rb', line 86

def query(type, opts = {}) #:nodoc:
  result = self.soap_client.GetList(:Username => self.username,
            :Password => self.password,
            :MaxItems => opts[:limit] || self.limit || 100,
            :MarkAsRead => opts[:mark_as_read] || self.mark_as_read || false,
            :LType => type
            )
  
  return [] if result.nil? || !defined?(result.objMessageItem)
  [*result.objMessageItem.messageItem].map do |fax|
    self.new(fax)
  end
end

.soap_client ⇒ Object

:nodoc:



80
81
82
83
84
 
# File 'lib/interfax/incoming.rb', line 80

def soap_client #:nodoc:
  SOAP::WSDLDriverFactory.
    new("https://ws.interfax.net/inbound.asmx?WSDL").
    create_rpc_driver
end

.unread(opts = {}) ⇒ Object

Returns any unread messages for your user up to the limit option. Optionally marks the faxes as read.

Options (as hash)

Both of these will default to whatever values you’ve set for the class, or 100 (limit) or false (mark_as_read) if you haven’t.

  • :limit - Maximum number of faxes to return.

  • :mark_as_read: Mark fetched faxes as read.



124
125
126
 
# File 'lib/interfax/incoming.rb', line 124

def unread(opts = {})
  query('NewMessages', opts)
end

Instance Method Details

#fetch_image ⇒ Object

:nodoc:



199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/interfax/incoming.rb', line 199

def fetch_image #:nodoc:
  @image = ""
  downloaded_size = 0
  while downloaded_size < @message_size
    result = self.class.soap_client.GetImageChunk(:Username => @username,
                                            :Password => @password,
                                            :MessageID => @message_id,
                                            :MarkAsRead => @mark_as_read,
                                            :ChunkSize => @chunk_size,
                                            :From => downloaded_size)

    # TODO: Make this throw a nicer exception on failure
    if defined?(result.image)
      @image << Base64.decode64(result.image)
    end
    downloaded_size += @chunk_size

  end
  
  @image
end