Microsoft Information Delivery API Reference

Microsoft Information Delivery API Reference


This reference describes the objects, interfaces, agents, methods, structures, types, flags, and properties included in the Information Delivery API.

The Microsoft Information Delivery API Reference no longer includes information on the notification manager and the interfaces and methods related to it. The implementation of the underlying architecture for the Information Delivery API will be changed after Microsoft Internet Explorer 4.0 is released, so the sections that will be affected (such as the notification manager) have been removed for this release.

arrowy.gifObjects

arrowy.gifInterfaces

arrowy.gifMethods

arrowy.gifStructures

arrowy.gifEnumerated Types

arrowy.gifReturn Values

Objects

This section describes the objects included in the Information Delivery API.

Channel Manager Object

CLSID_ChannelMgr

Manages channels.

Interface
IChannelMgr

Subscription Manager Object

CLSID_SubscriptionMgr

Handles subscriptions.

Interface
ISubscriptionMgr

Interfaces

This section describes the interfaces included in the Information Delivery API.

IChannelMgr

Provides the ability to add and delete Active Channels and channel categories in the desktop channel bar.

Methods
AddCategory
Adds a channel category to the desktop channel bar.
AddChannelShortcut
Installs an Active Channel into the desktop channel bar.
DeleteCategory
Deletes a channel category from the desktop channel bar.
DeleteChannelShortcut
Deletes an existing Active Channel.
EnumChannels
Creates a channel enumerator.

IEnumChannels

Enumerates channels.

Methods
Clone
Creates another enumeration that contains the same enumeration state as the current enumeration.
Next
Retrieves a specified number of items in the enumeration sequence.
Reset
Resets the enumeration sequence.
Skip
Skips over a specified number of items in the enumeration sequence.

ISubscriptionMgr

Allows a client program to control the subscription manager.

Methods
CreateSubscription
Creates a subscription.
DeleteSubscription
Deletes a subscription.
GetDefaultInfo
Retrieves the default information associated with a subscription type.
GetSubscriptionInfo
Retrieves the information associated with a specific subscription.
IsSubscribed
Checks if the user is subscribed to a particular site.
ShowSubscriptionProperties
Displays the subscription properties.
UpdateAll
Updates all the subscriptions.
UpdateSubscription
Updates the specified subscription.

Methods

This section describes the methods in the Information Delivery API.

IChannelMgr::AddCategory

HRESULT AddCategory(
    [in] CHANNELCATEGORYINFO *pCategoryInfo
);

Adds a channel category to the desktop channel bar.

pCategoryInfo
Address of the CHANNELCATEGORYINFO structure associated with the category to be added to the desktop channel bar.

IChannelMgr::AddChannelShortcut

HRESULT AddChannelShortcut(
    [in] CHANNELSHORTCUTINFO *pChannelInfo
);

Adds an Active Channel to the desktop channel bar.

pChannelInfo
Address of a CHANNELSHORTCUTINFO structure that contains the information associated with the Active Channel to be added.

This method only adds an entry into the desktop channel bar. To subscribe to the Active Channel, the client application must use the subscription manager.

IChannelMgr::DeleteCategory

HRESULT DeleteCategory(
    [in] LPWSTR pszTitle
);

Deletes a channel category from the desktop channel bar.

pszTitle
String value that contains the title of the channel category to be deleted from the desktop channel bar.

IChannelMgr::DeleteChannelShortcut

HRESULT DeleteChannelShortcut(
    [in] LPWSTR pszTitle
);

Deletes an Active Channel from the desktop channel bar.

pszTitle
String value that contains the title of the Active Channel to be deleted from the desktop channel bar.

This method does not delete the subscription, if one was created, for this Active Channel. The ISubscriptionMgr::DeleteSubscription method must be used to remove the subscription.

IChannelMgr::EnumChannels

HRESULT EnumChannels(
    [in] DWORD dwEnumFlags,
    [in] LPCWSTR pszURL,
    [out] IEnumChannels **pIEnumChannels
);

Creates a channel enumerator.

dwEnumFlags
Unsigned integer value that contains the flags that control the enumeration. Can be one of the CHANNELENUMFLAGS values or one of the following aggregate values:
CHANENUM_ALL Aggregate of all the CHANNELENUMFLAGS values.
CHANENUM_ALLDATA Aggregate of the CHANENUM_TITLE, CHANENUM_PATH, CHANENUM_URL, and the CHANENUM_SUBSCRIBESTATE values.
CHANENUM_ALLFOLDERS Aggregate of the CHANENUM_CHANNELFOLDER, CHANENUM_SOFTUPDATEFOLDER, and CHANENUM_DESKTOPFOLDER values.
pszURL
Optional. String value that contains the URL of the CDF file.
pIEnumChannels
Address of the pointer to the IEnumChannels interface of the enumerator.

IEnumChannels::Clone

HRESULT Clone(
    [in] IEnumChannels **ppenum
);

Creates another enumerator that contains the same enumeration state as the current enumeration.

ppenum
Address of a pointer to the IEnumChannels interface of the clone.

IEnumChannels::Next

HRESULT Next(
    [in] ULONG celt,
    [out] CHANNELENUMINFO *rgChanInf,
    [out] ULONG *pceltFetched
);

Retrieves a specified number of items in the enumeration sequence.

celt
Unsigned long integer value that contains the number of CHANNELENUMINFO structures being requested.
rgChanInf
Address of a buffer containing the CHANNELENUMINFO structures.
pceltFetched
Unsigned long integer value that indicates the actual number of structures received.

IEnumChannels::Reset

HRESULT Reset();

Resets the enumeration sequence.

IEnumChannels::Skip

HRESULT Skip(
    [in] ULONG celt;
);

Skips over a specified number of items in the enumeration sequence.

celt
Unsigned long integer value containing the number of CHANNELENUMINFO structures to skip.

ISubscriptionMgr::CreateSubscription

HRESULT CreateSubscription(
    [in] HWND hwnd;    
    [in] LPCWSTR pwszURL,
    [in] LPCWSTR pwszFriendlyName,
    [in] DWORD dwFlags,
    [in] SUBSCRIPTIONTYPE subsType,
    [in,out] SUBSCRIPTIONINFO *pInfo
);

Creates a subscription.

hwnd
Handle to the parent window.
pwszURL
String value that contains the URL of the site to subscribe to.
pwszFriendlyName
String value that contains a friendly name for the site.
dwFlags
Unsigned long integer value that contains the flags that control the creation of the subscription. Can be a combination of the CREATESUBSCRIPTIONFLAGS values.
subType
SUBSCRIPTIONTYPE value that determines how the subscription will be handled.
pInfo
Address of a SUBSCRIPTIONINFO structure containing the subscription information.

ISubscriptionMgr::DeleteSubscription

HRESULT DeleteSubscription(
    [in] LPCWSTR pwszURL,
    [in] HWND hwnd
);

Deletes a subscription.

pwszURL
String value containing the URL of the subscription to delete.
hwnd
Handle of the parent window.

ISubscriptionMgr::GetDefaultInfo

HRESULT GetDefaultInfo(
    [in] SUBSCRIPTIONTYPE subType,
    [out] SUBSCRIPTIONINFO *pInfo
);

Retrieves the default information associated with a subscription type.

subType
SUBSCRIPTIONTYPE value that contains the subscription type.
pInfo
Address of a SUBSCRIPTIONINFO structure containing the default information for the specified subscription type.

ISubscriptionMgr::GetSubscriptionInfo

HRESULT GetSubscriptionInfo(
    [in] LPCWSTR pwszURL,
    [out] SUBSCRIPTIONINFO *pInfo
);

Retrieves the information associated with a specific subscription.

pwszURL
String value that contains the URL associated with the subscription.
pInfo
Address of the SUBSCRIPTIONINFO structure containing the information about the specified subscription.

ISubscriptionMgr::IsSubscribed

HRESULT IsSubscribed(
    [in] LPCWSTR pwszURL,
    [out] BOOL *pfSubscribed
);

Checks if the user is subscribed to a particular site.

pwszURL
String value containing the URL to look for.
pfSubscribed
Address of a Boolean value that will be TRUE if a subscription exists, or FALSE otherwise.

ISubscriptionMgr::ShowSubscriptionProperties

HRESULT ShowSubscriptionProperties(
    [in] LPCWSTR pwszURL,
    [in] HWND hwnd
);

Displays the subscription properties.

pwszURL
String value containing the URL of the subscription.
hwnd
Handle to the parent window.

ISubscriptionMgr::UpdateAll

HRESULT UpdateAll()

Updates all subscriptions immediately.

ISubscriptionMgr::UpdateSubscription

HRESULT UpdateSubscription(
    [in] LPCWSTR pwszURL
);

Updates the specified subscription immediately.

pwszURL
String containing the URL of the subscription to update.

Structures

This section describes the structures used with the Information Delivery API.

CHANNELCATEGORYINFO

typedef _tagChannelCategoryInfo {
    DWORD cbSize;
    LPWSTR pszTitle;
    LPWSTR pszURL;
    LPWSTR pszLogo;
    LPWSTR pszIcon;
    LPWSTR pszWideLogo;
} CHANNELSHORTCUTINFO;

Contains the information associated with a category on the channel bar.

cbSize
Required. Double word value that contains the size of the structure. This value must be specified.
pszTitle
Required. String value that contains the title of the category.
pszURL
Optional. String value that contains the URL to an HTML page for the category.
pszLogo
Optional. String value that contains the URL of the logo associated with the category.
pszIcon
Optional. String value that contains the URL of the icon associated with the category.
pszWideLogo
Optional. String value that contains the URL of the wide logo associated with the channel.

CHANNELENUMINFO

typedef struct _tagChannelInfo{
    LPOLESTR pszTitle;
    LPOLESTR pszPath;
    LPOLESTR pszURL;
    SUBSCRIPTIONSTATE stSubscriptionState;
} CHANNELENUMINFO;

Contains the information on a channel in an enumeration.

pszTitle
String value that contains the channel title. Must use CoTaskMemFree to free the allocated memory when the application is finished using the structure.
pszPath
String value that contains the path to the channel shortcut. Must use CoTaskMemFree to free the allocated memory when the application is finished using the structure.
pszURL
String value that contains the URL of the CDF file for the given channel. Must use CoTaskMemFree to free the allocated memory when the application is finished using the structure.
stSubscriptionState
SUBSCRIPTIONSTATE value that indicates the current state of the subscription.

CHANNELSHORTCUTINFO

typedef _tagChannelShortcutInfo {
    DWORD cbSize;
    LPWSTR pszTitle;
    LPWSTR pszURL;
    LPWSTR pszLogo;
    LPWSTR pszIcon;
    LPWSTR pszWideLogo;
    BOOL bIsSoftware;
} CHANNELSHORTCUTINFO;

Contains the information associated with a channel entry in the channel bar.

cbSize
Required. Double word value that contains the size of the structure. This value must be specified.
pszTitle
Required. String value that contains the channel title. To add the channel to an existing category on the channel bar, the category title should be included in the channel title using the following format:

<category title>\\<channel title>

pszURL
Required. String value that contains the URL of the channel's CDF file.
pszLogo
Optional. String value that contains the URL of the logo associated with the channel.
pszIcon
Optional. String value that contains the URL of the icon associated with the channel.
pszWideLogo
Optional. String value that contains the URL of the wide logo associated with the channel.
bIsSoftware
Boolean value that indicates whether or not this shortcut is a software update.

SUBSCRIPTIONINFO

typedef struct _tagSubscriptionInfo {
    DWORD cbSize;
    DWORD fUpdateFlags;
    SUBSCRIPTIONSCHEDULE schedule;
    CLSID customGroupCookie;
    LPVOID pTrigger;
    DWORD dwRecurseLevels;
    DWORD fWebcrawlerFlags;
    BOOL bMailNotification;
    BOOL bGleam;
    BOOL bChangesOnly;
    BOOL bNeedPassword;
    DWORD fChannelFlags;
    BSTR bstrUserName;
    BSTR bstrPassword;
    BSTR bstrFriendlyName;
    DWORD dwMaxSizeKB;
    SUBSCRIPTIONTYPE subType;
    DWORD fTaskFlags;
    DWORD dwReserved;
} SUBSCRIPTIONINFO, *LPSUBSCRIPTIONINFO, *PSUBSCRIPTIONINFO;    

Contains the details of a subscription.

cbSize
Unsigned long integer value that contains the size of the structure.
fUpdateFlags
Unsigned long integer value that contains the update flags. Can be a combination of the SUBSCRIPTIONINFOFLAGS. Can also be set to SUBSINFO_ALLFLAGS to set all of the flags.
schedule
SUBSCRIPTIONSCHEDULE value that indicates how often the subscription is updated.
customGroupCookie
CLSID value that contains the cookie associated with the group.
pTrigger
Addresss of a pointer to the TASK_TRIGGER structure.
dwRecurseLevels
Unsigned long integer value that contains the number of levels to recurse.
fWebcrawlerFlags
Unsigned long integer value that contains the flags to control what resources are downloaded by the link crawler. Can be a combination of the WEBCRAWL_RECURSEFLAGS values.
bMailNotification
Boolean value that indicates whether to notify the user through e-mail when the subscribed site has been updated.
bGleam
Boolean value that indicates whether a gleam is displayed when the subscribed site has been updated.
bChangesOnly
Boolean value that indicates whether to only check for changes, or check for changes and download content.
bNeedPassword
Boolean value that indicates whether authentication is required for the subscribed site.
fChannelFlags
Unsigned long integer value containing the flags that control the channel agent. Can be one of the CHANNEL_AGENT_FLAGS.
bstrUserName
String value containing the user name used for authentication.
bstrPassword
String value containing the password used for authentication.
bstrFriendlyName
String value that contains the friendly name for the subscription.
dwMaxSizeKB
Unsigned long integer value that contains the maximum download size (in kilobytes) for this subscripton.
subType
SUBSCRIPTIONTYPE value that indicates the type of subscription.
fTaskFlags
Unsigned long integer value that contains the task flags. Can be one of the TASK_FLAG_* values defined in the Task Scheduler Reference.
dwReserved
Reserved. Must be set to zero.

Enumerated Types

This section defines the enumerated types in the Information Delivery API.

CHANNEL_AGENT_FLAGS

typedef enum CHANNEL_AGENT_FLAGS {
    CHANNEL_AGENT_DYNAMIC_SCHEDULE = 0x0001,
    CHANNEL_AGENT_PRECACHE_SOME = 0x0002,
    CHANNEL_AGENT_PRECACHE_ALL = 0x0004,
    CHANNEL_AGENT_PRECACHE_SCRNSAVER = 0x0008
} CHANNEL_AGENT_FLAGS;

Contains the flags that control the channel agent.

CHANNEL_AGENT_DYNAMIC_SCHEDULE
Use the information in the CDF file to create a schedule.
CHANNEL_AGENT_PRECACHE_SOME
Store any item that has an ITEM tag with the value PRECACHE=YES in the cache.
CHANNEL_AGENT_PRECACHE_ALL
Store all items in the cache that don't have an ITEM tag with the value PRECACHE=NO.
CHANNEL_AGENT_PRECACHE_SCRNSAVER
Store any item that has a USAGE tag with value equal to "ScreenSaver".

CHANNELENUMFLAGS

typedef enum _tagChannelEnumFlags{
    CHANENUM_CHANNELFOLDER = 0x00000001,
    CHANENUM_SOFTUPDATEFOLDER = 0x00000002,
    CHANENUM_DESKTOPFOLDER = 0x0000004,
    CHANENUM_TITLE = 0x00010000,
    CHANENUM_PATH = 0x00020000,
    CHANENUM_URL = 0x00040000,
    CHANENUM_SUBSCRIBESTATE = 0X00080000
} CHANNELENUMFLAGS;

Enumerated type that contains the channel enumerator flags that define what cahnnels are returned and what information will be returned for each channel enumerated.

CHANENUM_CHANNELFOLDER
Retrieve all channels in the channel folder.
CHANENUM_SOFTUPDATEFOLDER
Retrieve all channels in the software update folder.
CHANENUM_DESKTOPFOLDER
Retrieve all channels on the desktop.
CHANENUM_TITLE
Return the title of each channel enumerated.
CHANENUM_PATH
Return the path to the channel shortcut for each channel enumerated.
CHANENUM_URL
Return the URL of the CDF file for each channel enumerated.
CHANENUM_SUBSCRIBESTATE
Return the subscription state of each channel enumerated.

CREATESUBSCRIPTIONFLAGS

typedef enum CREATESUBSCRIPTIONFLAGS{
    CREATESUBS_ADDTOFAVORITES = 0x0001,
    CREATESUBS_FROMFAVORITES = 0x0002,
    CREATESUBS_NOUI = 0x0004,
    CREATESUBS_NOSAVE = 0x0008,
    CREATESUBS_SOFTWAREUPDATE = 0x0010,
} CREATESUBSCRIPTIONFLAGS;

Contains the flags used when creating a subscription.

CREATESUBS_ADDTOFAVORITES
Add subscription to Favorites menu.
CREATESUBS_FROMFAVORITES
Create the subscription for a site that already has a listing in the Favorites menu. Used in conjunction with the CREATESUBS_ADDTOFAVORITES value. This value will skip the section of the user interface that is used to add a Favorite and display the subscription options only.
CREATESUBS_NOUI
Create the subscription without displaying any user interface.
CREATESUBS_NOSAVE
Creates the subscription in the Subscriptions folder and then copies the information back to the SUBSCRIPTIONINFO structure that was passed in. Normally, the information is saved to the disk and the structure is not updated.
CREATESUBS_SOFTWAREUPDATE
Create a subscription for a software distribution channel. Used in conjunction SUBSTYPE_CHANNEL value. If used with the CREATESUBS_ADDTOFAVORITES value, the method will display a different user inteface and add the listing to the software updates folder.

SUBSCRIPTIONINFOFLAGS

typedef enum SUBSCRIPTIONINFOFLAGS {
    SUBSINFO_SCHEDULE = 0x0001,
    SUBSINFO_RECURSE = 0x0002,
    SUBSINFO_WEBCRAWL = 0x0004,
    SUBSINFO_MAILNOT = 0x0008,
    SUBSINFO_MAXSIZEKB = 0x0010,
    SUBSINFO_USER = 0x0020,
    SUBSINFO_PASSWORD = 0x0040,
    SUBSINFO_GLEAM = 0x0200,
    SUBSINFO_CHANGESONLY = 0x0400,
    SUBSINFO_CHANNELFLAGS = 0x0800,
    SUBSINFO_FRIENDLYNAME = 0x2000,
    SUBSINFO_NEEDPASSWORD = 0x4000,
    SUBSINFO_TYPE = 0x8000
} SUBSCRIPTIONINFOFLAGS;

Contains the type information about subscriptions.

SUBSINFO_SCHEDULE
Update schedule the subscription is on.
SUBSINFO_RECURSE
Number of levels to recurse.
SUBSINFO_WEBCRAWL
Flags for the link crawling agent.
SUBSINFO_MAILNOT
User should be notified through e-mail.
SUBSINFO_MAXSIZEKB
Maximum download size in kilobytes.
SUBSINFO_USER
User name for authentication.
SUBSINFO_PASSWORD
Password for authentication.
SUBSINFO_GLEAM
Add a gleam to notify the user of an update to the site.
SUBSINFO_CHANGESONLY
Notify the user of changes only.
SUBSINFO_CHANNELFLAGS
Channel flags.
SUBSINFO_FRIENDLYNAME
Friendly name for the subscription.
SUBSINFO_NEEDPASSWORD
Subscription requires a password.
SUBSINFO_TYPE
Type of subscription.

SUBSCRIPTIONSCHEDULE

typedef enum SUBSCRIPTIONSCHEDULE {
    SUBSSCHED_AUTO = 0,
    SUBSSCHED_DAILY = 1,
    SUBSSCHED_WEEKLY = 2,
    SUBSSCHED_CUSTOM = 3,
    SUBSSCHED_MANUAL = 4
} SUBSCRIPTIONSCHEDULE;

Contains the values that indicate the update frequency.

SUBSSCHED_AUTO
Automatically schedule updates.
SUBSSCHED_DAILY
Update the subscription daily.
SUBSSCHED_WEEKLY
Update the subscription weekly.
SUBSSCHED_CUSTOM
Update the subscription using a custom schedule.
SUBSSCHED_MANUAL
Update the subscription manually.

SUBSCRIPTIONSTATE

typedef enum _tagSubscriptionState{
    SUBSTATE_NOTSUBSCRIBED,
    SUBSTATE_PARTIAL_SUBSCRIPTION,
    SUBSTATE_FULLSUBSCRIPTION
} SUBSCRIPTIONSTATE;

Contains the different subscription states.

SUBSTATE_NOTSUBSCRIBED
Not subscribed to the channel.
SUBSTATE_PARTIALSUBSCRIPTION
Partially subscribed to the channel.
SUBSTATE_FULLSUBSCRIPTION
Subscribed to the channel.

SUBSCRIPTIONTYPE

typedef enum SUBSCRIPTIONTYPE {
    SUBSTYPE_URL = 0,
    SUBSTYPE_CHANNEL = 1,
    SUBSTYPE_DESKTOPCOMPONENT = 2
} SUBSCRIPTIONTYPE;

Contains the different types of subscriptions.

SUBSTYPE_URL
Subscription is an Internet resource.
SUBSTYPE_CHANNEL
Subscription is a channel.
SUBSTYPE_DESKTOPCOMPONENT
Subscription is a desktop component.

WEBCRAWL_RECURSEFLAGS

typedef enum WEBCRAWL_RECURSEFLAGS {
    WEBCRAWL_DONT_MAKE_STICKY = 0x0001,
    WEBCRAWL_GET_IMAGES = 0x0002,
    WEBCRAWL_GET_VIDEOS = 0x0004,
    WEBCRAWL_GET_BGSOUNDS = 0x0008,
    WEBCRAWL_GET_CONTROLS = 0x0010,
    WEBCRAWL_LINKS_ELSEWHERE = 0x0020,
    WEBCRAWL_IGNORE_ROBOTSTXT = 0x0080
} WEBCRAWL_RECURSEFLAGS;

Contains the flags for the default link crawling agent included with the Information Delivery API.

WEBCRAWL_DONT_MAKE_STICKY
Instructs the agent to cache the downloaded resources normally. If this value is not set, the agent makes the entries sticky, which prevents the entry from being removed during a normal clean-up operation.
WEBCRAWL_GET_IMAGES
Instructs the agent to download any images associated with the resource.
WEBCRAWL_GET_VIDEOS
Instructs the agent to download any videos associated with the resource.
WEBCRAWL_GET_BGSOUNDS
Instructs the agent to download any background sounds associated with the resource.
WEBCRAWL_GET_CONTROLS
Instructs the agent to download any controls associated with the resource.
WEBCRAWL_LINKS_ELSEWHERE
Instructs the agent to follow links that go to sites outside the site that the resource resides on.
WEBCRAWL_IGNORE_ROBOTSTXT
Instructs the agent to ignore any robot scripts.

Return Values

The following list contains possible return values for the Information Delivery API.

INET_E_AGENT_CACHE_SIZE_EXCEEDED
Maximum cache limit has been reached.
INET_E_AGENT_CONNECTION_FAILED
Failed to connect to the Internet.
INET_E_AGENT_MAX_SIZE_EXCEEDED
Subscription size limit has been reached.
INET_S_AGENT_PART_FAIL
Agent has completed the operation after encountering a few errors.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.