
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.
Objects
Interfaces
Methods
Structures
Enumerated Types
Return Values
This section describes the objects included in the Information Delivery API.
CLSID_ChannelMgr
Manages channels.
- Interface
- IChannelMgr
CLSID_SubscriptionMgr
Handles subscriptions.
- Interface
- ISubscriptionMgr
This section describes the interfaces included in the Information Delivery API.
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.
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.
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.
This section describes the methods in the Information Delivery API.
HRESULT AddCategory(
[in] CHANNELCATEGORYINFO *pCategoryInfo
);
Adds a channel category to the desktop channel bar.
- Returns E_INVALIDARG if any of the required fields in the CHANNELCATEGORYINFO structure are not provided.
- pCategoryInfo
- Address of the CHANNELCATEGORYINFO structure associated with the category to be added to the desktop channel bar.
HRESULT AddChannelShortcut(
[in] CHANNELSHORTCUTINFO *pChannelInfo
);
Adds an Active Channel to the desktop channel bar.
- Returns E_INVALIDARG if any of the required fields in the CHANNELSHORTCUTINFO structure are not provided.
- 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.
HRESULT DeleteCategory(
[in] LPWSTR pszTitle
);
Deletes a channel category from the desktop channel bar.
- Returns S_FALSE if the specified channel category does not exist.
- pszTitle
- String value that contains the title of the channel category to be deleted from the desktop channel bar.
HRESULT DeleteChannelShortcut(
[in] LPWSTR pszTitle
);
Deletes an Active Channel from the desktop channel bar.
- Returns S_FALSE if the specified Active Channel does not exist.
- 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.
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:
- pszURL
- Optional. String value that contains the URL of the CDF file.
- pIEnumChannels
- Address of the pointer to the IEnumChannels interface of the enumerator.
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.
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.
HRESULT Reset();
Resets the enumeration sequence.
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.
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.
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.
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.
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.
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.
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.
HRESULT UpdateAll()
Updates all subscriptions immediately.
HRESULT UpdateSubscription(
[in] LPCWSTR pwszURL
);
Updates the specified subscription immediately.
- pwszURL
- String containing the URL of the subscription to update.
This section describes the structures used with the Information Delivery API.
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.
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.
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.
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.
This section defines the enumerated types in the Information Delivery API.
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".
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.
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.
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.
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.
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.
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.
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.
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.