Export (0) Print
Expand All

Communicating with the Windows Live Photo Gallery Publishing Plug-in Platform

The hosting Windows Live application communicates with a publishing plug-in by passing two XmlDocument objects: one that provides details about a particular publishing session, and one that describes any persistent configuration settings that are used by the publishing plug-in.

The session-specific XmlDocument object describes the set of photo and video items to publish for a specific publishing session, and provides details about each item. The session XML document (sessionXml) is passed to each method supported by the IPublishPlugin Interface interface.

Cc967058.note(en-us,WIN.10).gifNote:
There is no guarantee that a plug-in will remain loaded between calls to its IPublishPlugin interface; it is important that plug-ins write any session-specific information to the session XmlDocument object before returning from each method call.

The following example shows a typical session XML document structure.

<?xml version="1.0" ?> 
<PhotoGalleryPublishSession versionMajor="1" versionMinor="0">

    <PublishParameters>
        <MaxWidth>1024</MaxWidth> 
        <MaxHeight>1024</MaxHeight> 
    </PublishParameters>

    <ItemSet>

        <Item id="1">
            <FullFilePath>d:\samples\sample1.jpg</FullFilePath>
            <OriginalFileName>sample1.jpg</OriginalFileName>
            <OriginalFileExtension>.jpg</OriginalFileExtension>
            <PerceivedType>image</PerceivedType>
            <Title>sample1</Title>
            <OriginalWidth>4000</OriginalWidth>
            <OriginalHeight>3000</OriginalHeight>
            <LengthMS>0</LengthMS>
            <FileSize>1024</FileSize>
            <KeywordSet>
                <Keyword>Keyword 1</Keyword>
                <Keyword>Keyword 2</Keyword>
            </KeywordSet>
            <PeopleRegionSet>
                <PersonRegion left="0.2" top="0.2" width="0.5" height="0.5" id="cc9fff2ee0829796" contacted="1234654">John Doe</PersonRegion>
            </PeopleRegionSet>
        </Item>

        <Item id="2">
            <FullFilePath>d:\samples\sample2.jpg</FullFilePath>
            <OriginalFileName>sample2.jpg</OriginalFileName>
            <OriginalFileExtension>.jpg</OriginalFileExtension>
            <PerceivedType>image</PerceivedType>
            <Title>sample2</Title>
            <OriginalWidth>4000</OriginalWidth>
            <OriginalHeight>3000</OriginalHeight>
            <LengthMS>0</LengthMS>
            <FileSize>1024</FileSize>
            <KeywordSet>
                <Keyword>Keyword 1</Keyword>
                <Keyword>Keyword 2</Keyword>
            </KeywordSet>
            <PeopleRegionSet />
            </Item>

    </ItemSet>

</PhotoGalleryPublishSession>

The following table describes the XML elements that are used in a Windows Live Photo Gallery publishing session.

Element Description

PhotoGalleryPublishSession

The top-level element of a publishing session.

PublishParameters

Contains additional parameters that are passed between the publishing plug-in and the client.

MaxWidth

The default resolution width, in pixels, to which to transcode images while preserving aspect ratio. A value of 0 indicates the original size.

The default value comes from the MaxPhotoWidth element in the DefaultParameters section of the plug-in properties. The publishing plug-in may change this value during the call to the ShowConfigurationSettings Method. The client uses this value to encode or transcode the image before calling the PublishItem Method.

MaxHeight

The default resolution height, in pixels, to which to transcode images while preserving aspect ratio. A value of 0 indicates the original size.

The default value comes from the MaxPhotoHeight element in the DefaultParameters section of the plug-in properties. The publishing plug-in may change this value during the call to the ShowConfigurationSettings Method. The client uses this value to encode or transcode the image before calling the PublishItem Method.

MaxVideoWidth

The default resolution width, in pixels, to which to transcode videos while preserving aspect ratio. A value of 0 indicates the original size.

The default value comes from the MaxVideoWidth element in the DefaultParameters section of the plug-in properties. The publishing plug-in may change this value during the call to the ShowConfigurationSettings Method. The client uses this value to encode/transcode the video before calling the PublishItem Method.

MaxVideoHeight

The default resolution height, in pixels, to which to transcode videos while preserving aspect ratio. A value of 0 indicates the original size.

The default value comes from MaxVideoHeight element in the DefaultParameters section of the plug-in properties. The publishing plug-in may change this value during the call to the ShowConfigurationSettings Method. The client uses this value to encode/transcode the video before calling the PublishItem Method.

MaxVideoBitrate

The default bit rate, in kilobits per second, to which to transcode video. A value of 0 indicates the original bit rate.

The default value comes from the MaxVideoBitrate element in the DefaultParameters section of the plug-in properties. The publishing plug-in may change this value during the call to the ShowConfigurationSettings Method. The client uses this value to encode or transcode the image before calling the PublishItem Method.

MaxVideoFramerate

The default frame rate, measured in frames per 100 seconds, to which to transcode video. A value of 0 indicates the original frame rate.

The default value comes from the MaxVideoFramerate element in the DefaultParameters section of the plug-in properties. The publishing plug-in may change this value during the call to the ShowConfigurationSettings Method method. The client uses this value to encode or transcode the image before calling the PublishItem Method.

AlbumId

The ID of the album, if one is used, where the media items in the session were published. The publishing plug-in adds this element during a publishing session to provide the client with additional ways to access the album. Clients can use this value to access the album via a Subscribe Plug-in, which enables client applications to enumerate the media contents of an Internet service, modify properties on those items, and download them. Another possibility is to enable a quick publishing scenario, in which the client uses the AlbumName and AlbumThumbnail values to create a “Quick publish” button in the client user interface (UI). When the user clicks that button, the client places the AlbumId element in this new publishing session and calls the ShowConfigurationSettings Method. This approach enables the publishing plug-in to bypass asking the user to select an album to publish to, and instead to publish to the existing album.

AlbumName

The name of the album where the media items in the session were published. The publishing plug-in adds this element during a publishing session to provide the client with additional ways to access the album. For more information, see the description of the AlbumId element earlier in this topic.

AlbumThumbnail

A URL that specifies the location of the album thumbnail where the media items in the publishing session were published, if an album can be used. The publishing plug-in adds this element during a publishing session to provide the client with additional ways to access the album. For more information, see the description of the AlbumId element earlier in this topic.

AlbumURL

A URL to the web based experience of this album. The publish plug-in adds this element during a publishing session to provide the client with additional ways to access the album.

ItemSet

Contains the Item elements that are part of the current publishing session.

Item

Contains the properties that are associated with an item in this publishing session. The id attribute is the unique ID and will be passed as the pszItemId parameter in subsequent calls to the PublishItem Method.

FullFilePath

The full path to the file that is being published.

OriginalFileName

The name of the file as it appears in the file system.

OriginalFileExtension

The extension of the file name as it appears in the file system, including the period (".")

PerceivedType

The type of the file. Can be either "image" or "video".

Title

The title or caption that is associated with the item.

OriginalWidth

The original width of the item, in pixels.

OriginalHeight

The original height of the item, in pixels.

LengthMS

The duration of the video item, in milliseconds.

FileSize

The size of the file, in bytes.

KeywordSet

Contains the keywords that are associated with the item.

Keyword

A keyword/tag that is associated with the item.

PersonRegionSet

Contains the person regions—regions of an item that are associated with people—for the item.

PersonRegion

A region of the item that is associated with a person. The left, top, width, and height attributes are percentages from 0 to 1 that specify the ratio of the photo's height and width, defining the region that contains the image of the person. The optional id attribute uniquely identifies the person in the photo. The optional contacted attribute specifies the user ID of the person in the service that is being published to.

ItemId

The online service ID of the item, if the PublishItem Method call is successful. The publishing plug-in adds this element during a publishing session to provide the client with additional ways to access the album.

ErrorCode

A hexadecimal representation of an HRESULT value describing the failure, if the PublishItem Method call fails. The publish plug-in adds this element during a publishing session to provide the client with additional ways to access the album.

ErrorText

A text description of the failure, which is displayed if a PublishItem Method call fails. This value will be displayed instead of the ErrorCode value if both are present. The publishing plug-in adds this element during a publishing session to provide the client with additional ways to access the album.

The publishing plug-in platform provides a persistent XmlDocument object that can be used to store general plug-in settings between publishing sessions; the persistent XmlDocument is encrypted and stored on the user's computer. When a publishing plug-in is started, the hosting Windows Live application calls the plug-in's ShowConfigurationSettings Method method and passes in the persistent XmlDocument through the persistXml parameter.

There is no fixed format for the persistent XmlDocument; plug-in developers can define the structure of this document as needed.

Cc967058.security(en-us,WIN.10).gifSecurity Note:
The persistent XML is designed to store general plug-in settings; it is not intended to store sensitive user information, such as sign-in credentials. Do not use the persistent XML to store sensitive user information.
Show:
© 2015 Microsoft