mms2r 1.0.0

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2007-03-06
+
+* Birthday!
+

data/Manifest.txt

@@ -0,0 +1,54 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+conf/mms2r_cingularmedia_transform.yml
+conf/mms2r_sprintmedia_ignore.yml
+conf/mms2r_tmobilemedia_ignore.yml
+conf/mms2r_verizonmedia_ignore.yml
+lib/mms2r.rb
+lib/mms2r/cingular_media.rb
+lib/mms2r/media.rb
+lib/mms2r/mmode_media.rb
+lib/mms2r/sprint_media.rb
+lib/mms2r/tmobile_media.rb
+lib/mms2r/verizon_media.rb
+lib/mms2r/version.rb
+lib/vendor/text/format.rb
+lib/vendor/tmail.rb
+lib/vendor/tmail/address.rb
+lib/vendor/tmail/attachments.rb
+lib/vendor/tmail/base64.rb
+lib/vendor/tmail/config.rb
+lib/vendor/tmail/encode.rb
+lib/vendor/tmail/facade.rb
+lib/vendor/tmail/header.rb
+lib/vendor/tmail/info.rb
+lib/vendor/tmail/loader.rb
+lib/vendor/tmail/mail.rb
+lib/vendor/tmail/mailbox.rb
+lib/vendor/tmail/mbox.rb
+lib/vendor/tmail/net.rb
+lib/vendor/tmail/obsolete.rb
+lib/vendor/tmail/parser.rb
+lib/vendor/tmail/port.rb
+lib/vendor/tmail/quoting.rb
+lib/vendor/tmail/scanner.rb
+lib/vendor/tmail/scanner_r.rb
+lib/vendor/tmail/stringio.rb
+lib/vendor/tmail/tmail.rb
+lib/vendor/tmail/utils.rb
+test/files/dot.jpg
+test/files/sprint-image-01.mail
+test/files/sprint-text-01.mail
+test/files/sprint-video-01.mail
+test/files/sprint.mov
+test/files/verizon-image-01.mail
+test/files/verizon-text-01.mail
+test/files/verizon-video-01.mail
+test/test_mms2r_cingular.rb
+test/test_mms2r_media.rb
+test/test_mms2r_mmode.rb
+test/test_mms2r_sprint.rb
+test/test_mms2r_tmobile.rb
+test/test_mms2r_verizon.rb

data/README.txt

@@ -0,0 +1,81 @@
+mms2r
+
+by Mike Mondragon
+
+http://mms2r.rubyforge.org/    
+
+== DESCRIPTION:
+  
+MMS2R is a library that decodes the parts of an MMS message to disk while 
+stripping out advertising injected by the cellphone carriers.  MMS messages are 
+multipart email and the carriers often inject branding into these messages. 
+
+If MMS2R is not aware of a particular carrier no extra processing is done 
+to the MMS other than decoding and consolidating its media.
+
+Contact the author to add additional carriers to be processed by the library.
+
+== FEATURES/PROBLEMS:
+
+Corpus of carriers currently processed by MMS2R:
+
+* AT&T/Cingular => mmode.com
+* Cingular => mms.mycingular.com
+* Sprint => pm.sprint.com
+* Sprint => messaging.sprintpcs.com
+* T-Mobile => tmomail.net
+* Verizon => vzwpix.com
+  
+== SYNOPSIS:
+
+  require 'rubygems'
+  require 'mms2r'
+  require 'tmail'
+  media = TMail::Media.parse(IO.readlines("mymail.file").join)
+  mms = MMS2R::Media.create(mail,Logger.new(STDOUT))
+  mms.process
+  # mms.media is a hash that is indexed by mime-type
+  # the mime-type key returns an array of filepaths
+  # to media in the MMS that was of that type
+  mms.media['image/jpeg'].each {|f| puts "${f}"}
+  mms.media['text/plain'].each {|f| puts "${f}"}
+  text = File.open(mms.media['text/plain'][0], 'rb') { |file|
+       file.read
+  }
+  puts text
+  #remove the media that was put to temporary disk
+  #mms.purge
+
+== REQUIREMENTS:
+
+* TMail
+* Hpricot
+
+== INSTALL:
+
+* sudo gem install mms2r
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2007 Mike Mondragon.  All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,30 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require 'rcov/rcovtask'
+
+$LOAD_PATH.unshift 'lib'
+require 'mms2r'
+require 'mms2r/media'
+
+Hoe.new('mms2r', MMS2R::Media::VERSION) do |p|
+  p.rubyforge_name = 'mms2r'
+  p.author = 'Mike Mondragon'
+  p.email = 'mike@mondragon.cc'
+  p.summary = 'Extract media from MMS '
+  p.description = p.paragraphs_of('README.txt', 2..5).join("\n\n")
+  p.url = p.paragraphs_of('README.txt', 0).first.split(/\n/)[1..-1]
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.extra_deps << ['hpricot']
+  p.extra_deps << ['rcov']
+  p.clean_globs << 'coverage'
+end
+
+Rcov::RcovTask.new do |t|
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+  t.rcov_opts << "--exclude rcov.rb,hpricot.rb,hpricot/.*\.rb"
+end
+
+# vim: syntax=Ruby

data/conf/mms2r_cingularmedia_transform.yml

@@ -0,0 +1,6 @@
+--- 
+text/plain: 
+  "--\n\
+    ===============================================\n\
+    Brought to you by, Cingular Wireless Messaging\n\
+    http://www.CingularMe.COM/\n ": ""

data/conf/mms2r_sprintmedia_ignore.yml

@@ -0,0 +1,10 @@
+--- 
+text/plain: 
+- |-
+  You have new Picture Mail!
+
+  Click Go/View to see now.
+- |-
+  You have new Video Mail!
+
+  Click Go/View to see now.

data/conf/mms2r_tmobilemedia_ignore.yml

@@ -0,0 +1,17 @@
+--- 
+text/html: 
+- |
+  <html>
+    <head>
+  		<title>T-Mobile</title> 
+image/gif: 
+- dottedline350.gif
+- dottedline600.gif
+- dottedLine_350.gif
+- dottedLine_600.gif
+- masthead.jpg
+- spacer.gif
+- video.gif
+- audio.gif
+- tmobilelogo.gif
+- tmobilespace.gif

data/conf/mms2r_verizonmedia_ignore.yml

@@ -0,0 +1,3 @@
+--- 
+text/plain: 
+- This message was sent using PIX-FLIX Messaging service from Verizon Wireless!

data/lib/mms2r.rb

@@ -0,0 +1,3 @@
+$:.unshift(File.dirname(__FILE__) + "/vendor/")
+module MMS2R # :nodoc:
+end

data/lib/mms2r/cingular_media.rb

@@ -0,0 +1,11 @@
+require 'mms2r'
+require 'mms2r/media'
+
+module MMS2R
+
+  ##
+  # Cingular version of MMS2R::Media
+
+  class MMS2R::CingularMedia < MMS2R::Media
+  end
+end

data/lib/mms2r/media.rb

@@ -0,0 +1,345 @@
+# Copyright (c) 2007 by Mike Mondragon ()
+#
+# Please see the LICENSE file for licensing.
+
+require 'fileutils'
+require 'pathname'
+require 'tmpdir'
+require 'yaml'
+require 'mms2r'
+require 'mms2r/version'
+require 'mms2r/cingular_media'
+require 'mms2r/mmode_media'
+require 'mms2r/sprint_media'
+require 'mms2r/tmobile_media'
+require 'mms2r/verizon_media'
+
+##
+# MMS2R is a library to collect media files from MMS messages. MMS messages 
+# are multipart emails and cellphone carriers often inject branding into these 
+# messages. MMS2R strips the advertising from an MMS leaving the actual user 
+# generated media.
+#
+# If you encounter MMS from a carrier that contains advertising other non-
+# standard media features submit a sample to the author for inclusion in this
+# project.
+#
+# The create method is a factory method to create MMS2R::Media
+# Custom media producers can be pushed into the factory via the
+# MMS2R::CARRIER_CLASSES Hash, e.g.
+#
+# class MMS2R::FakeCarrier < MMS2R::Media; end
+# MMS2R::CARRIER_CLASSES['mms.fakecarrier.com'] = MMS2R::FakeCarrier
+# ...
+# media = MMS2R::Media.create(some_tmail) #media will be a MMS2R::FakeCarrier
+
+module MMS2R
+
+  ##
+  # A hash of file extentions for common mimetypes
+  EXT = {
+    'text/plain' => 'txt',
+    'text/html' => 'html',
+    'image/png' => 'png',
+    'image/gif' => 'gif',
+    'image/jpeg' => 'jpg',
+    'video/quicktime' => 'mov',
+    'video/3gpp2' => '3g2'
+  }
+
+  ##
+  # A hash of carriers that MMS2r is currently aware of.
+  # The factory create method uses the hostname portion 
+  # of an MMS's from to select the correct type of MMS2R::Media
+  # product.  If a specific media product is not available
+  # MMS2R::Media should be used.
+
+  CARRIER_CLASSES = {
+    'mms.mycingular.com' => MMS2R::CingularMedia,
+    'mmode.com' => MMS2R::MModeMedia,
+    'pm.sprint.com' => MMS2R::SprintMedia,
+    'messaging.sprintpcs.com' => MMS2R::SprintMedia,
+    'tmomail.net' => MMS2R::TMobileMedia,
+    'vzwpix.com' => MMS2R::VerizonMedia
+  }
+
+  class MMS2R::Media
+
+    ##
+    # TMail object that the media files were derived from.
+    attr_reader :mail
+
+    ##
+    # media returns the hash of media.  The media hash
+    # is keyed by mimetype such as 'text/plain' and the
+    # value mapped to the key is an array of media that
+    # are of that type.
+    attr_reader :media
+
+    ##
+    # Creates a new Media comprised of a mail
+    # a logger.  Logger is an instance attribute allowing
+    # for a logging strategy per carrier type
+
+    def initialize(mail, logger=nil)
+      @mail = mail
+      @logger = logger
+      @logger.info("#{self.class} created") unless @logger.nil?
+      @media = Hash.new
+      @dir_count = 0
+      @media_dir = File.join(self.class.tmp_dir(), 
+                     self.class.safe_message_id(@mail.message_id))
+    end
+
+    ##
+    # Helper for process template method to decode the part based 
+    # on its type and write its content to a temporary file.  Returns 
+    # path to temporary file that holds the content.  Parts with a main
+    # type of text will have their contents transformed with a call to
+    # transform_text
+    #
+    # Producers should only override this method if the parts of
+    # the MMS need special treatment besides what is expected for
+    # a normal mime part.
+    #
+    # Returns a tupple of content type, file path
+
+    def process_media(part)
+      # TMail body auto-magically decodes quoted
+      # printable for text/html type.
+      # base64_decode is safe in TMail facade, no work is performed
+      # if the part is not base64 encoded.
+      part.base64_decode
+      file = temp_file(part)
+      content = part.body
+      content = transform_text(self.class.part_type?(part),content) if self.class.main_type?(part).eql?('text')
+      @logger.info("#{self.class} writing file #{file}") unless @logger.nil?
+      File.open(file,'w'){ |f|
+        f.write(content)
+      }
+      type = self.class.part_type?(part)
+      return type, file
+    end
+
+    ##
+    # Helper for process_media template method to transform text.
+
+    def transform_text(type,text)
+      f = "#{self.class.name.downcase.gsub(/::/,'_')}_transform.yml"
+      yf = File.join(self.class.conf_dir(), "#{f}")
+      return text unless File::exist?(yf)
+      h = YAML::load_file(yf)
+      a = h[type]
+      return text if a.nil?
+      a.each do |from,to|
+        text.gsub!(/#{from}/m,to)
+      end
+      text
+    end
+
+    ##
+    # Helper for process template method to determine if 
+    # media contained in a part should be ignored.  Producers 
+    # should override this method to return true for media such 
+    # as images that are advertising, carrier logos, etc.
+
+    def ignore_media?(type,part)
+      f = "#{self.class.name.downcase.gsub(/::/,'_')}_ignore.yml"
+      yf = File.join(self.class.conf_dir(), "#{f}")
+      return false unless File::exist?(yf)
+      h = YAML::load_file(yf)
+      a = h[type]
+      return false if a.nil?
+      m = /^([^\/]+)\//.match(type)[1]
+      a.each do |i|
+        if m.eql?('text')
+          return true if part.body =~ /#{Regexp.escape("#{i}")}/m
+        else
+          return true if filename?(part).eql?(i)
+        end
+      end
+      false
+    end
+
+    ##
+    # Helper for process template method to name a temporary
+    # filepath based on information in the part.  This version
+    # attempts to honor the name of the media as labeled in the part
+    # header and creates a unique temporary directory for writing
+    # the file so filename collision does not occur.
+    # Consumers of this method expect the directory
+    # structure to the file exists, if the method is overriden it
+    # is mandatory that this behavior is retained.
+
+    def temp_file(part)
+      file_name = filename?(part)
+      File.join(msg_tmp_dir(),File.basename(file_name))
+    end
+
+    ##
+    # Purges the unique directory created for this producer and
+    # all of the media that it contains.  This implementation is
+    # based on an instance variable called @media_dir
+
+    def purge()
+      @logger.info("#{self.class} purging #{@media_dir} and all its contents") unless @logger.nil?
+      FileUtils.rm_rf(@media_dir)
+    end
+
+    ##
+    # process is a template method and collects all the media in a MMS.
+    # Override helper methods to this template to clean out advertising 
+    # and/or ignore media that are advertising. This method should not be 
+    # overridden unless there is an extreme special case in processing the 
+    # media of a MMS.
+    #
+    # Helpers methods for the process template:
+    # ignore_media? true if the media contained a is part should
+    # be ignored.
+    # process_media retrieves media to temporary file, returns path
+    # to file.
+    # transform_text called by process_media, strips out advertising.
+    # temp_file creates a temporary filepath based on information from
+    # the part.
+
+    def process()
+      @logger.info("#{self.class} processing") unless @logger.nil?
+
+      parts = @mail.parts
+      if !@mail.multipart?
+        parts = Array.new()
+        parts << @mail
+      end
+      parts.each do |p|
+        t = self.class.part_type?(p)
+        unless ignore_media?(t,p)
+          t,f = process_media(p)
+          add_file(t,f) unless f.nil?
+        end
+      end
+    end
+
+    ##
+    # Helper to add a file to the media hash.
+
+    def add_file(type, file)
+      if @media[type].nil?
+        @media[type] = Array.new
+      end
+      @media[type] << file
+    end
+
+    ##
+    # Helper to temp_file to create a unique temporary directory that is
+    # a child of tmp_dir  This version is based on the message_id of the
+    # mail.
+
+    def msg_tmp_dir()
+      @dir_count += 1
+      dir = File.join(@media_dir, "#{@dir_count}")
+      FileUtils.mkdir_p(dir)
+      dir
+    end
+
+    ##
+    # Factory method that creates MMS2R::Media products.
+    #
+    # Returns a MMS2R::Media product based on the characteristics
+    # of the carrier from which the the MMS originated.  
+    # mail is a TMail object, logger is a Logger and may be
+    # nil.
+
+    def self.create(mail, logger=nil)
+      d = lambda{['',MMS2R::Media]}
+      cc = MMS2R::CARRIER_CLASSES.detect(d) do |n, c| 
+              /[^@]+@(.+)/.match(mail.from[0])[1] =~ /#{Regexp.escape("#{n}")}/
+      end
+      cls = cc[1]
+      cls.new(mail, logger)
+    end
+
+    ##
+    # returns a filename declared for a part, or a default if its not defined
+
+    def filename?(part)
+      part.sub_header("content-type", "name") ||
+        part.sub_header("content-disposition", "filename") ||
+        (part['content-location'] && part['content-location'].body) ||
+        "#{Time.now.to_i}.#{self.class.default_ext(self.class.part_type?(part))}"
+    end
+
+    @@tmp_dir = File.join(Dir.tmpdir, ENV['USER'],'mms2r')
+
+    ##
+    # Get the temporary directory where media files are written to.
+
+    def self.tmp_dir
+      @@tmp_dir
+    end
+
+    ##
+    # Set the temporary directory where media files are written to.
+    def self.tmp_dir=(d)
+      @@tmp_dir=d
+    end
+
+    @@conf_dir = File.join(File.dirname(__FILE__), '..', '..', 'conf')
+
+    ##
+    # Set the directory where conf files are stored.
+
+    def self.conf_dir
+      @@conf_dir
+    end
+
+    ##
+    # Set the directory where conf files are stored.
+    def self.conf_dir=(d)
+      @@conf_dir=d
+    end
+
+    ##
+    # Helper to created a safe directory path element based on the
+    # mail message id.
+
+    def self.safe_message_id(mid)
+      return "#{Time.now.to_i}" if mid.nil?
+      mid.gsub(/<|>|@|\./, "")
+    end
+
+    ##
+    # Returns a default file extension based on a content_type
+
+    def self.default_ext(content_type)
+      ext = MMS2R::EXT[content_type]
+      return /[^\/]+\/(.+)/.match(content_type)[1] if ext.nil?
+      ext
+    end
+
+    ##
+    # Determines the mimetype of a part.  Gauruntees a type is returned.
+
+    def self.part_type?(part)
+      if part.content_type.nil?
+        return 'text/plain'
+      end
+      part.content_type
+    end
+
+    ##
+    # Determines the main type of the part's mimetype
+
+    def self.main_type?(part)
+      /^([^\/]+)\//.match(self.part_type?(part))[1]
+    end
+
+    ##
+    # Determines the sub type of the part's mimetype
+
+    def self.sub_type?(part)
+      /\/([^\/]+)$/.match(self.part_type?(part))[1]
+    end
+
+  end
+
+end