Revision as of 02:38, 2 July 2012 by hamishwillee (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Archived:Syndication service in WidSets

From Nokia Developer Wiki
Jump to: navigation, search

Archived.pngArchived: This article is archived because it is not considered relevant for third-party developers creating commercial solutions today. If you think this article is still relevant, let us know by adding the template {{ReviewForRemovalFromArchive|user=~~~~|write your reason here}}.

The article is believed to be still valid for the original topic scope.

Article Metadata
Created: User:Mirsilla (04 Jun 2008)
Last edited: hamishwillee (02 Jul 2012)


The Service

The syndication service gives a common interface to RSS and ATOM type online feed content.

The syndication service supports polling. This means that if a syndication service is marked as pollable, the WidSets server can poll the external feed on behalf of the client and notify the client when new content is available.

A client uses the syndication service actions getItems and getPage to retrieve the actual content.

The feed content is returned to the client as a structured and tagged list format. The feed item description part is represented as a list of text and image url elements. The image url elements represent the images embedded in the feed item description text or in separate enclosures. The order of the text and image url elements represent their order in the original feed.

Service Parameters

The XML configuration file of a syndication service can define several service parameters that define and control the service. Normally only the feedurl and polltype service parameters are defined. Other parameters are optional and are used for specifying poll period limits and token authentication.

Service parameter Type Meaning
feedurl mandatory The URL to the RSS or ATOM feed to be fetched.
polltype optional Marks the service as pollable. The value of this parameter defines how the server will poll the feed defined by the feedurl parameter. Currently the only valid value for this parameter is auto.
minpollperiod optional Defines the lower limit for the poll period value for a pollable service. Default value is "2m".
maxpollperiod optional Defines the upper limit for the poll period value for a pollable service. Default value is "3h".
authtoken optional TOKEN to be used in signing the URL when Token authentication is used. (See Archived:Token authentication in WidSets.)
userid optional UserID to be used when performing Token authentication. (See Archived:Token authentication in WidSets.)
partnerid optional Id of the partner in question when using Token authentication.
useapiurl optional If the value is true, the URL specified in the partner's information is used. Otherwise the URL specified by feedurl service parameter will be used.

Service Actions

The service has four actions the client script can call:

Action Generic Function
getItems No Retrive feed items list.
getPage No Retrieve the value of the content-field page by page. The value of the content field of a feed item can be rather long. Therefore the value is retrieved one page at the time. The default page length is 500 characters.
bookmark No Save the link associated with a feed item into the bookmarks.
senditem No Send the link associated with a feed item to a friend by email.

Below are the specifications of the service actions:


TitleField    = (bind (const title)   (choice (null noData)
                                              (string titleVal)))

LinkField     = (bind (const "link")  (choice (null noData)
                                              (string linkVal)))

CreatedField  = (bind (const created) (choice (null noData)
                                              (int createdTimestamp)))

AuthorField   = (bind (const author)  (choice (null noData)
                                              (string authorVal)))

ContentField  = (bind (const content) (choice (null noData)
                                              (use PagedFieldVal)))

PagedFieldVal = (list (bag (bind (const type) (const page))
                                 (bind (const pg)   (int pageNum))
                                 (bind (const left) (int pagesLeft))
                                 (bind (const val)  (use PageVal))))

PageVal       = (choice (null noData)
                        (use ElemList))

ElemList      = (list (repeat (use Elem)))

Elem          = (choice (string stringElem)
                        (use ImageUrlElem))

ImageUrlElem  = (list (bag (required (bind (const type)   (const image)))
                           (required (bind (const url)    (string imageUrl)))
                           (optional (bind (const width)  (int imageWidth)))
                           (optional (bind (const height) (int imageHeight)))))

Action getItems

Retrive feed items list.

input  = (list (bag (optional (bind (const ts)      (int timestamp)))
                    (optional (bind (const refresh) (boolean refreshVal)))
                    (optional (bind (const max)     (int maxCount)))
                    (optional (bind (const len)     (choice (int pageLength)
                                                            (const all))))))
output = (choice (null noData)
                 (list (repeat (use Item))))

Item   = (list (bag (bind (const iid) (string itemId))
                    (repeat (use Field))))

Field  = (choice (use TitleField)
                 (use LinkField)
                 (use CreatedField)
                 (use AuthorField)
                 (use ContentField))
Name Type Description
ts int Return only items that are newer than the value of this argument. The timestamp value is in milliseconds since the 1st of January, 1970, and interpreted as UTF/GMT timestamp.
refresh boolean If true, return fresh content fetched from the feedurl. Otherwise, return content from server side cache, if available.
max int The maximum number of items to return. Default is 20.
len int | all The [first] page length (in characters) for the content field value. Default is 500. The special constant value all returns all content.

Sample Output
((iid = "961e023e1a7652d59a1e50237325310d"
  title = "California hopes for slowing winds\n(AP)"
  link = "http://us.rd.yahoo.com/dailynews/rss/topstories/*http://news.yahoo.com/s/ap/20071024/
  created = 1193222693000
  author = ""
  content = (type = page
             pg = 1
             left = 0
             val = ((type = image
                  url = "http://d.yimg.com/us.yimg.com/p/ap/20071024/capt.b42703c3b236406dbd6c704f7c78bf89
                     width = 91
                     height = 130)
                    "AP - After three days of a vicious firestorm, exhausted firefighters and weary residents 
                     looked forward Wednesday to a break — an expected slackening of the gale force winds that 
                     have ignited the state\'s largest complex of wildland blazes.")))
 (iid = a971fe9d92d0dd6a5c2032b5bf4e66a9
  title = "Turkey masses more troops, raids in Iraq confirmed\n(Reuters)"
  link = "http://us.rd.yahoo.com/dailynews/rss/topstories/*http://news.yahoo.com/s/nm/20071024/ts_nm/turkey_iraq_dc"
  created = 1193222613000
  author = ""
  content = (type = page
             pg = 1
             left = 0
             val = ((type = image
                     url = "http://d.yimg.com/us.yimg.com/p/nm/20071024/2007_10_23t101515_450x235_us_turkey_
                     width = 130
                     height = 67)
                    "Reuters - Turkish warplanes and troops have\nattacked Kurdish rebels inside Iraq and 
                     forces were being built\nup on the border, but Ankara was holding back from any major\nstrike 
                     for now, military sources said on Wednesday.")))
 (iid = "635886e9387a951b294c6cb4cbe0fe89"
  title = "China aims for moon with patriotic blast\n(Reuters)"
  link = "http://us.rd.yahoo.com/dailynews/rss/topstories/*http://news.yahoo.com/s/nm/20071024/ts_nm/china_space_launch_dc"
  created = 1193222529000
  author = ""
  content = (type = page
             pg = 1
             left = 0
             val = ("Reuters - China launched its first moon\norbiter on Wednesday accompanied by a blaze of 
                     live-to-air\npatriotic propaganda celebrating the country\'s space ambitions\nand 
                     technological prowess.")))


Action getPage

Retrieve the value of the content field page by page.

input  = (list (bag (required (bind (const iid) (string itemId)))
                    (required (bind (const pg)  (int pageNum)))
                    (optional (bind (const len) (choice (int pageLength)
                                                        (const all))))))

output = (list (bag (bind (const iid) (string itemId))
                    (use ContentField)))
Name Type Description
iid string The ID of the item.
pg int The number of the page to return. Page numbers start from 1.
len int | all The page length (in characters). Default is 500. The special constant value all returns all content. (If len is all then pg must be 1.)

Action bookmark

Save the link associated with a feed item into the bookmarks.

input  = (list (bag (required (bind (const type) (choice (const default) 
                                                         (const custom))))
                    (optional (bind (const iid)  (string itemId)))))

output = (const true)
Name Type Description
type default | custom Type of the bookmark, normally default.
iid string The ID of the item to bookmark.

Action senditem

Send the link associated with a feed item to a friend by email.

input  = (list (bag (required (bind (const iid) (string itemId)))
                    (required (bind (const to)  (string to)))))

output = (const true)
Name Type Description
iid string The ID of the item to send.
to string The recipient's email address.

Code Example

Retrieving the newest feed items from server (fetcher)

Archived:Example Syndication Service in WidSets

See also

This page was last modified on 2 July 2012, at 02:38.
41 page views in the last 30 days.

Was this page helpful?

Your feedback about this content is important. Let us know what you think.


Thank you!

We appreciate your feedback.