[This is preliminary documentation and is subject to change.]

Publishes a file in "phone ready" downloadable format at a public URL.
**This function incurs a 1 credit usage charge.

Namespace:  PhoneSherpa.Services
Assembly:  App_Code.fxrph_yi (in App_Code.fxrph_yi)
Version: 0.0.0.0

Syntax

C#
public WS..::.PublishContentResult PublishContent(
	string AccessKey,
	WS..::.UserPhoneInformation UserPhoneInfo,
	string SourceFile,
	string FriendlyFileName
)
Visual Basic (Declaration)
Public Function PublishContent ( _
	AccessKey As String, _
	UserPhoneInfo As WS..::.UserPhoneInformation, _
	SourceFile As String, _
	FriendlyFileName As String _
) As WS..::.PublishContentResult
JScript
public function PublishContent(
	AccessKey : String, 
	UserPhoneInfo : WS..::.UserPhoneInformation, 
	SourceFile : String, 
	FriendlyFileName : String
) : WS..::.PublishContentResult

Parameters

AccessKey
Type: System..::.String
Security key allocated to a developer enabling access to the web service API.
UserPhoneInfo
Type: PhoneSherpa.Services..::.WS..::.UserPhoneInformation
UserPhoneInformation structure containing the user's phone delivery information
SourceFile
Type: System..::.String
Internal source file name within Phone Sherpa system. Expressed as a random and unique file name without a path. Typically the output of an API editor function, but can be any internal SourceFile handle.
FriendlyFileName
Type: System..::.String
A user friendly representation of the SourceFile name. This name will become the file name seen on the user's phone.

Passed in names are truncated to 16 characters before the file extension, to ensure name portability across all phone models. Non alpha-numeric characters are converted to underscores "_". Files generated for the same user using the same friendly file name are given unique version numbers to ensure name collision and overwritting will not occur on the handset after delivery (this feature only present if files are created within the same 24 hour block).

Ex: "A Song From My Band.mp3" becomes "A_Song_From_My_B.mp3" on the user's phone. Making another ringtone with the same name within 24 hours will yield "A_Song_From_My_1.mp3".

Return Value

URLs to both the non-DRM and DRM published files. Depending on the carrier and phone model types targeted, these URL's may point at GCD or similar metadata wrapper files (as required by some carriers).

Remarks

PublishContent takes any internal source file and publishes the file for download by the end user in both its original and DRM OMA 2.0 forward locked version. Internal source files are not accessible outside of the Phone Sherpa system. They are used as the source for editing, content delivery, and are the result of editing. Typcially this function is called after an editing API call, such as EditAudioContentForPhone(...). The file published for pickup should already be in a format supported by the phone natively. PublishContent(...) does not convert or transcode files; it makes the files availble for download by the end user.

Developers should use PublishContent if they want to sideload "phone download ready" files into thier own system. This function should also be called if the developer has its own method of connectivity (such as its own SMS/MMS solution) and just needs the content to put over thier connection. If the developer needs access to the raw SourceFile un-prepared for download (such as the output of the EditAudioContentForPhone(...)), use the ResolveContentHandle(...) method to get a sideloadable version of the file.

Phone download ready means that any wrapper files (such as GCDs) are generated, DRM is applied, friendly file names are generated, and carrier specific secured URLs are used (where applicable).

Files are available for pickup by the end user for a period of 24 hours. After this time, the pubished files are removed from the public pickup location. This location is not indended to be a mechanism to host files indefinately.

The DRM protection is using OMA 2.0 forward locking, if the phone model supports this feature. GCD and similar content wrappers are automatically generated for carriers that require them.

It is not recommended to use the PublishContent(...) and SendContentToPhone(...) methods on the same files during the same transaction. This will pubish the content files twice, displaying duplicate files for pickup by the end user after the SendContentToPhone(...) call. No error will result, however; this is purely a cosmetic issue

This function incurs a 1 credit usage charge. Prepay customers must have credits in thier account to successfully call this function. Postpay customers will be metered 1 credit on thier monthly billing statement for each call to this function.

Below is an example of how to use this function:

CopyVB.NET
Public Sub PublishContent(ByVal UserPhoneInfo As PhoneSherpa.Services.UserPhoneInformation, ByVal SourceFile As String, ByVal FriendlyFileName As String)
    Dim SherpaService As New PhoneSherpa.Services.WS

    'Publish the source file for download using the specified friendly file name 
    Dim Publish_Response As New PhoneSherpa.Services.PublishContentResult

    Publish_Response = SherpaService.PublishContent("My_WSAccessKey", UserPhoneInfo, SourceFile, FriendlyFileName)

    'Check the response to ensure the call worked
    If Publish_Response.Result.ErrorCode = 0 Then
        'The call worked and the files are now published ready to be downloaded to a users phone
        'Here the developer can call thier own SMS/MMS/WAP Push solution to deliver the content
        'Or the developer can sideload the content into thier own system for use later in thier application code

        Dim PublishedURL As String = Publish_Response.PublishedFileURL
        Dim PublishedURL_DRM As String = Publish_Response.PublishedFileURLDRM

        '...
    Else
        'error - the publish call failed, redirect to an error handler
    End If
End Sub

See Also