velir_kaltura-ruby 0.4.5 → 0.4.6

data/lib/kaltura/service/category_service.rb

@@ -1,19 +1,74 @@
 module Kaltura
   module Service
+    ##
+    # CategoryService is responsible for adding and managing Categories.  Categories are the main 
+    # means to filter entries within the KMC.
+    #
+    # @example Add a new category to the KMC filter list.
+    #   new_category = Kaltura::Category.new
+    #   new_category.name = "waffles"
+    #   client.category_service.add(new_category)
+    #
+    # @example Get an existing category by ID.
+    #   client.category_service.get(214)
+    #
+    # @example Update an existing category.
+    #   category_update = Kaltura::Category.new
+    #   category_update.description = "waffles are pretty freaking good."
+    #   client.category_service.update(214,category_update)
+    #
+    # @example Delete an existing category.
+    #   client.category_service.delete(214)
+    #
+    # @example List all categories with a parent_id of 2
+    #   category_filter = Kaltura::Filter::CategoryFilter.new
+    #   category_filter.parent_id_equal = 2
+    #   client.category_service.list(category_filter)
+    ##
     class CategoryService < BaseService
-
+      
+      ##
+      # Adds a new Category.
+      #
+      # @param [Kaltura::Category] category The category that will be created.  The crucial field to fill out is name.
+      # 
+      # @return [Kaltura::Category] Returns the category as it now appears on the server.  It would be beneficial to 
+      #   save the ID of the category for later reference.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def add(category)
   			kparams = {}
   			client.add_param(kparams, 'category', category)
   			perform_request('category','add',kparams,false)
   		end
 
+      ##
+      # Retrieves a category by it's ID.
+      #
+      # @param [Integer] id The Kaltura::Category object's id.
+      #
+      # @return [Kaltura::Category] The requested category.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def get(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('category','get',kparams,false)
   		end
 
+      ##
+      # Updates a category.
+      # The best practice as with all updates would be to insantiate a new Kaltura::Category and update specific fields.
+      #
+      # @param [Integer] id The Kaltura::Category id of the category to be updated.
+      # @param [Kaltura::Category] A newly insantiated Category object with the fields updated that you'd like to update.
+      # 
+      # @return [Kaltura::Category] The new and improved Category object.
+      # 
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def update(id, category)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
@@ -21,12 +76,32 @@ module Kaltura
   			perform_request('category','update',kparams,false)
   		end
 
+      ##
+      # Deletes the requested Category.
+      # I am fairly confident that this will not actually clear the category from each entry, but it is no longer
+      # a filter on the KMC.
+      #
+      # @param [Integer] id The category ID to remove.
+      #
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def delete(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('category','delete',kparams,false)
   		end
 
+      ##
+      # Lists all Categories given the specified filter.
+      #
+      # @param [Kaltura::Filter::CategoryFilter] filter The filter to apply.
+      #
+      # @return [Kaltura::Response::CategoryListResponse] Wrapper for Kaltura::Response::BaseResponse.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.      
+      ##
   		def list(filter=nil)
   			kparams = {}
   			client.add_param(kparams, 'filter', filter)

data/lib/kaltura/service/conversion_profile_service.rb

@@ -1,19 +1,78 @@
 module Kaltura
   module Service
+    
+    ##
+    # The Conversion Profile Service is responsible for adding and managing conversion profiles.
+    #
+    # @example Create a new conversion profile:
+    #   conversion_profile = Kaltura::ConversionProfile.new
+    #   conversion_profile.name = "waffles"
+    #   conversion_profile.is_default = "true"
+    #   conversion_profile.clip_duration = 15
+    #   client.conversion_profile_service.add(conversion_profile)
+    #
+    # @example Retrieve a conversion profile:
+    #   client.conversion_profile_service.get(224)
+    #
+    # @example Update a conversion profile:
+    #   update_profile = Kaltura::ConversionProfile.new
+    #   update_profile.description = "why does the documentor love waffles so much?"
+    #   update_profile.clip_start = 3
+    #   client.conversion_profile_service.update(224,update_profile)
+    #
+    # @example Delete a conversion profile:
+    #   client.conversion_profile_service.delete(224)
+    #
+    # @example Retrieve all conversion profiles with an ID of 224
+    #   filter = Kaltura::Filter::ConversionProfileFilter.new
+    #   filter.id_equal = 224
+    #   client.conversion_profile_service.list(filter)
+    ##
     class ConversionProfileService < BaseService
 
+      ##
+      # Adds a new conversion profile.
+      #
+      # @param [Kaltura::ConversionProfile] conversion_profile The new conversion profile.
+      #
+      # @return [Kaltura::ConversionProfile] The conversion profile as it is stored on the Kaltura server.
+      #   It might be important to store the ID returned.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def add(conversion_profile)
   			kparams = {}
   			client.add_param(kparams, 'conversionProfile', conversion_profile)
   			perform_request('conversionProfile','add',kparams,false)
   		end
-
+      
+      ##
+      # Retrieves a conversion profile by ID.
+      #
+      # @param [Integer] id The conversion profile ID.
+      #
+      # @return [Kaltura::ConversionProfile] The requested conversion profile.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##      
   		def get(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('conversionProfile','get',kparams,false)
   		end
 
+      ##
+      # Updates a conversion profile given an ID and a newly instantiated ConversionProfile.
+      # It will update any populated fields on the provided profile.
+      #
+      # @param [Integer] id The conversion profile ID.
+      # @param [Kaltura::ConversionProfile] conversion_profile Newly instantiated conversion profile with 
+      #   the fields to update.
+      # 
+      # @return [Kaltura::ConversionProfile] Returns an updated conversion profile.
+      # 
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def update(id, conversion_profile)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
@@ -21,12 +80,31 @@ module Kaltura
   			perform_request('conversionProfile','update',kparams,false)
   		end
 
+      ##
+      # Deletes a conversion profile by ID.
+      #
+      # @param [Integer] id The conversion profile ID.
+      #
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def delete(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('conversionProfile','delete',kparams,false)
   		end
 
+      ##
+      # Lists conversion profiles given a filter with paging support for larger result sets.
+      #
+      # @param [Kaltura::Filter::ConversionProfileFilter] filter The filter to apply to the list.
+      # @param [Kaltura::FilterPager] pager Default Kaltura Pager.
+      #
+      # @return [Kaltura::Response::ConversionProfileListResponse] Wrapper for Kaltura::Response::BaseResponse.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def list(filter=nil, pager=nil)
   			kparams = {}
   			client.add_param(kparams, 'filter', filter)

data/lib/kaltura/service/data_service.rb

@@ -1,13 +1,58 @@
 module Kaltura
   module Service
+    ##
+    # The Data Service allows you to add and manage texual content.
+    #
+    # @example Creating a new DataEntry:
+    #   new_data_entry = Kaltura::DataEntry.new
+    #   new_data_entry.name = "pancake"
+    #   new_data_entry.data_content = "We all know  that waffles are better.  But the documentation author is tired."
+    #   client.data_entry_service.add(new_data_entry)
+    #
+    # @example Retrieve a DataEntry:
+    #   client.data_entry_service.get('1_ad342xk')
+    # 
+    # @example Update a DataEntry:
+    #   update_entry = Kaltura::DataEntry.new
+    #   update_entry.data_content = 'Ninjas <3 waffles.  Pirates love the pancakes.'
+    #   client.data_entry_service.update('1_ad342xk',update_entry)
+    #
+    # @example Delete a DataEntry:
+    #   client.data_entry_service.delete('1_ad342xk')
+    #
+    # @example Filter DataEntries by group ID 2:
+    #   filter = Kaltura::Filter::DataEntryFilter.new
+    #   filter.group_id_equal = '2'
+    #   client.data_entry_service.list(filter)
+    ##
     class DataService < BaseService
 
+      ##
+      # Adds a new data entry.
+      #
+      # @param [Kaltura::DataEntry] data_entry This is essentially a BaseEntry except there
+      #   is a field called data_content.  Presumably you shove text into this field.
+      #
+      # @return [Kaltura::DataEntry] Returns the data entry as it is stored in the DB.
+      #
+      # @raise [Kaltura::APIError] Raises the default Kaltura errors.
+      ##
   		def add(data_entry)
   			kparams = {}
   			client.add_param(kparams, 'dataEntry', data_entry)
   			perform_request('data','add',kparams,false)
   		end
 
+      ##
+      # Gets a data entry by ID.
+      #
+      # @param [String] entry_id the DataEntry id.
+      # @param [Integer] version Version of the DataEntry.
+      #
+      # @return [Kaltura::DataEntry] Returns the desired DataEntry object.
+      # 
+      # @raise [Kaltura::APIError] Raises the default Kaltura errors in addition to 'ENTRY_ID_NOT_FOUND'.
+      ##
   		def get(entry_id, version=-1)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)
@@ -15,6 +60,19 @@ module Kaltura
   			perform_request('data','get',kparams,false)
   		end
 
+      ##
+      # Updates a data entry.
+      # As with other update actions, the best practice is to instantiate a new Kaltura::DataEntry object
+      # and set the fields of that object that you wish to change.
+      #
+      # @param [String] entry_id The DataEntry you wish to update.
+      # @param [Kaltura::DataEntry] document_entry A newly instantiated DataEntry object with only 
+      #   the fields that you wish to update filled in.
+      #
+      # @return [Kaltura::DataEntry] Returns the updated DataEntry object complete with a version bump.
+      # 
+      # @raise [Kaltura::APIError] Raises the default Kaltura errors in addition to 'ENTRY_ID_NOT_FOUND'.
+      ##
   		def update(entry_id, document_entry)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)
@@ -22,12 +80,31 @@ module Kaltura
   			perform_request('data','update',kparams,false)
   		end
 
+      ##
+      # Removes a DataEntry object.
+      #
+      # @param [String] entry_id the DataEntry to delete.
+      #
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises the default Kaltura errors in addition to 'ENTRY_ID_NOT_FOUND'.      
+      ##
   		def delete(entry_id)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)
   			perform_request('data','delete',kparams,false)
   		end
 
+      ##
+      # Lists DataEntry objects with the given filter and paging support for larger sets of data.
+      #
+      # @param [Kaltura::Filter::DataEntryFilter] filter The filter to apply to the list.
+      # @param [Kaltura::FilterPager] pager The default Kaltura pager.
+      #
+      # @return [Kaltura::Response::DataListResponse] Wrapper for Kaltura::Response::BaseResponse.
+      #
+      # @raise [Kaltura::APIError] Raises the default Kaltura errrors.
+      ##
   		def list(filter=nil, pager=nil)
   			kparams = {}
   			client.add_param(kparams, 'filter', filter)

data/lib/kaltura/service/email_ingestion_profile_service.rb

@@ -1,25 +1,73 @@
 module Kaltura
   module Service
+    ##
+    # The Email Ingestion Profile Service allows you to manage email ingestion profile records.
+    ##
     class EmailIngestionProfileService < BaseService
-
+      
+      ##
+      # Adds an email ingestion profile to the Kaltura Database.
+      #
+      # @param [Kaltura::EmailIngestionProfile] email_ip The email ingestion profile to add.
+      #
+      # @return [Kaltura::EmailIngestionProfile] Returns the email ingestion profile as stored on the DB.
+      #   It might be important to store either the email_address or ID fields for later.
+      #
+      # @raise [Kaltura::APIError] Raises 'EMAIL INGESTION PROFILE EMAIL EXISTS' if there is another profile using
+      #   the email address provided.
+      ##
   		def add(email_ip)
   			kparams = {}
   			client.add_param(kparams, 'EmailIP', email_ip)
   			perform_request('EmailIngestionProfile','add',kparams,false)
   		end
-
+      
+      ##
+      # Retrieves an email ingestion profile by the email_address field.
+      #
+      # @param [String] email_address The email address to find the profile with.
+      #
+      # @return [Kaltura::EmailIngestionProfile] The requested email ingestion profile.
+      #
+      # @raise [Kaltura::APIError] Raises 'EMAIL INGESTION PROFILE NOT FOUND' if there isnt a profile with the
+      #   email address provided.
+      ##
   		def get_by_email_address(email_address)
   			kparams = {}
   			client.add_param(kparams, 'emailAddress', email_address)
   			perform_request('EmailIngestionProfile','getByEmailAddress',kparams,false)
   		end
 
+      ##
+      # Retrieves an email ingestion profile by ID.
+      #
+      # @param [Integer] id The ID of the email ingestion profile to find.
+      #
+      # @return [Kaltura::EmailIngestionProfile] The requested email ingestion profile.
+      #
+      # @raise [Kaltura::APIError] Raises 'EMAIL INGESTION PROFILE NOT FOUND' if there isnt a profile with the
+      #   email address provided.
+      ##
   		def get(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('EmailIngestionProfile','get',kparams,false)
   		end
 
+      ##
+      # Updates an existing email ingestion profile.
+      # As with other update API actions it is a best practice to instantiate a new EmailIngestionProfile object
+      # and populate the fields with the fields you wish to change of the existing object.
+      #
+      # @param [Integer] id The ID of the email ingestion profile you wish to update.
+      # @param [Kaltura::EmailIngestionProfile] email_ip The newly instantiated email ingestion profile object
+      #  with the fields you wish to update.
+      #
+      # @return [Kaltura::EmailIngestionProfile] Returns the updated object with a new version.
+      #
+      # @raise [Kaltura::APIError] Raises 'EMAIL INGESTION PROFILE NOT FOUND' if there isnt a profile with the
+      #   email address provided.      
+      ##
   		def update(id, email_ip)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
@@ -27,12 +75,39 @@ module Kaltura
   			perform_request('EmailIngestionProfile','update',kparams,false)
   		end
 
+      ##
+      # Deletes an email ingestion profile by ID.
+      #
+      # @param [Integer] id The ID of the email ingestion profile to delete.
+      # 
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises 'EMAIL INGESTION PROFILE NOT FOUND' if there isnt a profile with the
+      #   email address provided.
+      ##
   		def delete(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('EmailIngestionProfile','delete',kparams,false)
   		end
 
+      ##
+      # Adds a Kaltura::MediaEntry from a email ingestion profile.
+      # I'm not entirely sure what the aim of this upload action is, rather than 
+      # using the media service itself.
+      #
+      # @param [Kaltura::MediaEntry] media_entry A newly instantiated media entry object that will be created
+      #   in the database.
+      # @param [String] upload_token_id The upload token provided by the media service's upload action.
+      # @param [Integer] email_profile_id The email ingestion profile ID.
+      # @param [String] from_address The email address the action is coming from?
+      # @param [String] email_msg_id The ID of the email message?
+      # 
+      # @return [Kaltura::MediaEntry] The newly created media entry as stored in the kaltura database.
+      #   It would be beneficial to store the entry_id of this object for later.
+      #
+      # @raise [Kaltura::APIError] Raises 'UPLOADED_FILE_NOT_FOUND_BY_TOKEN' when the upload token cannot be found.
+      ##
   		def add_media_entry(media_entry, upload_token_id, email_prof_id, from_address, email_msg_id)
   			kparams = {}
   			client.add_param(kparams, 'mediaEntry', media_entry)

data/lib/kaltura/service/flavor_asset_service.rb

@@ -1,25 +1,89 @@
 module Kaltura
   module Service
+    
+    ##
+    # The Flavor Asset Service allows you to retrieve information and invoke actions on flavor assets.
+    #
+    # @example Add a new flavor to a media entry:
+    #   client.flavor_asset_service.convert('1_qa32a3ax',22)
+    #
+    # @example Retrieve a flavor by flavor_id:
+    #   client.flavor_asset_service.get('0_as35a2r3a')
+    #
+    # @example Retrieve all flavors for a media entry:
+    #   client.flavor_asset_service.get_by_entry_id('1_qa32a3ax')
+    #      
+    # @example Retrieve all the web playable flavors for a media entry:
+    #   client.flavor_asset_service.get_web_playable_by_entry_id('1_qa32a3ax')
+    #
+    # @example Reconvert a specific Flavor:
+    #   client.flavor_asset_service.get('0_as35a2r3a')
+    #
+    # @example Delete a Flavor:
+    #   client.flavor_asset_service.delete('0_as35a2r3a')
+    #
+    # @example Retrieve a URL to download a specific flavor:
+    #   client.flavor_asset_service.get_download_url('0_as35a2r3a')
+    #
+    ##
     class FlavorAssetService < BaseService
 
+      ##
+      # Retrieves an individual flavor asset by ID.
+      #
+      # @param [String] id A flavor asset ID closely resembles an entry_id as Kaltura flavors are 
+      #   very close in nature to entries.
+      #
+      # @return [Kaltura::FlavorAsset] Returns the requested flavor asset.
+      #
+      # @raise [Kaltura::APIError] Raises the default Kaltura errors.
+      ##
   		def get(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('flavorAsset','get',kparams,false)
   		end
 
+      ##
+      # Retrieves an enumerable collection of flavor assets given a media entry id.
+      #
+      # @param [String] entry_id The media entry ID to seek flavors for.
+      #
+      # @return [Array] Returns an array of the flavor assets for a given media entry.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def get_by_entry_id(entry_id)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)
   			perform_request('flavorAsset','getByEntryId',kparams,false)
   		end
-
+  		
+      ##
+      # Retrieves an enumerable collection of flavor assets that are playable within the KDP for a given media entry ID.
+      #
+      # @param [String] entry_id The media entry ID to seek flavors for.
+      #
+      # @return [Array] Returns an array of the flavor assets for a given media entry.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.      
+      ##
   		def get_web_playable_by_entry_id(entry_id)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)
   			perform_request('flavorAsset','getWebPlayableByEntryId',kparams,false)
   		end
 
+      ##
+      # Add and convert a new flavor asset for a specified entry given a flavor param.
+      #
+      # @param [String] entry_id The media entry ID to add a new flavor asset to.
+      # @param [Integer] flavor_params_id The flavor params ID for conversion type.
+      #
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def convert(entry_id, flavor_params_id)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)
@@ -27,24 +91,60 @@ module Kaltura
   			perform_request('flavorAsset','convert',kparams,false)
   		end
 
+      ##
+      # Reconvert a specific flavor asset.
+      #
+      # @param [String] id The flavor asset id.
+      # 
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def reconvert(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('flavorAsset','reconvert',kparams,false)
   		end
 
+      ##
+      # Removes a flavor asset.
+      #
+      # @param [String] id Flavor asset to remove.
+      #
+      # @return [nil] Returns nothing.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def delete(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('flavorAsset','delete',kparams,false)
   		end
 
+      ##
+      # Gets a downloadable URL for a flavor asset.
+      #
+      # @param [String] id The flavor asset id.
+      #
+      # @return [String] a URL that can be used to download the requested flavor.
+      #
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def get_download_url(id)
   			kparams = {}
   			client.add_param(kparams, 'id', id)
   			perform_request('flavorAsset','getDownloadUrl',kparams,false)
   		end
-
+  		
+      ##
+      # Retrieves an enumerable collection of Flavor Assets + Flavor Params given a media entry.
+      #
+      # @param [String] entry_id The media entry to retrieve flavors from.
+      #
+      # @return [Array] Returns a collection of Flavor Assets + Flavor Params.
+      # 
+      # @raise [Kaltura::APIError] Raises default Kaltura errors.
+      ##
   		def get_flavor_assets_with_params(entry_id)
   			kparams = {}
   			client.add_param(kparams, 'entryId', entry_id)