
HRESULT GetExtension(
LPTSTR pszExtension,
int cchExtension
);
Retrieves the file extension for the shortcut object.
See also INewShortcutHook
HRESULT GetFolder(
LPTSTR pszFolder,
int cchFolder
);
Retrieves the folder name for the shortcut object.
See also INewShortcutHook
HRESULT GetName(
LPTSTR pszName,
int cchName
);
Retrieves the file name of the shortcut object, without the extension.
See also INewShortcutHook
HRESULT GetReferent(
LPTSTR pszReferent,
int cchReferent
);
Retrieves the referent of the shortcut object.
For Internet shortcut objects, this method is the same as IUniformResourceLocator::GetURL.
See also INewShortcutHook
HRESULT SetFolder(
LPTSTR pszFolder
);
Sets the folder name for the shortcut object.
See also INewShortcutHook
HRESULT SetReferent(
LPCTSTR pszReferent,
HWND hWnd
);
Sets the referent of the shortcut object.
For Internet shortcut objects, this method is the same as IUniformResourceLocator::SetURL.
See also INewShortcutHook
The INotifyReplica interface provides the object's creator with the means to notify an object that it may be subject to subsequent reconciliation. The briefcase reconciler is responsible for implementing this interface.
| INotifyReplica Method | Description |
| YouAreAReplica | Notifies an object that it may be subject to reconciliation. |
HRESULT INotifyReplica::YouAreAReplica( ULONG ulcOtherReplicas, IMoniker ** rgpmkOtherReplicas );
Notifies an object that it may be subject to subsequent reconciliation through the IReconcilableObject::Reconcile method.
An object may be notified that it is a replica more than once. Briefcase reconcilers are not required to implement this interface. Initiators are not required to call this interface if it is implemented. However, an object's implementation of IReconcilableObject::Reconcile may fail if that object has not previously been notified through INotifyReplica::YouAreAReplica that it may be subject to reconciliation.
The briefcase calls the INotifyReplica interface when objects are added to it.
The IPersistFolder interface is used to initialize shell folder objects.
When to Implement
When implementing a shell namespace extension, specifically the IShellFolder interface, you need to implement this interface so the folder object can be initialized. Implementation of this interface is how the folder is told where it is in the shell namespace.
When to Use
You do not use this interface directly. It is used by the file system implementation of the IShellFolder::BindToObject interface when it is initializing a shell folder object.
IPersistFolder is derived from IPersist. The following method is specific to IPersistFolder.
| IPersistFolder Method | Description |
| Initialize | Instructs a shell folder object to initialize itself based on the information passed. |
HRESULT Initialize(
LPCITEMIDLIST pidl,
);
Instructs a shell folder object to initialize itself based on the information passed.
Notes to Implementers
All objects that implement the IShellFolder interface for use in the shell's namespace must implement this method. When a folder's location in the namespace is not a relevant consideration, this method can simply return NOERROR. When the location is relevant to the folder, you should store the fully qualified IDLIST passed in for future reference.
For example, if the folder implementation needs to construct a fully qualified PIDL to elements that it contains, the PIDL passed to this method should be used to construct the fully qualified PIDLs.
See also IPersistFolder
The shell uses the IQueryInfo interface to retrieve flags and info tip information for an item that resides in an IShellFolder implementation. Info tips are usually displayed inside of a tooltip control.
When to Implement
You implement IQueryInfo to provide flags and text information that differs from the normal text that is displayed for an item in a folder. For example, if your folder contained file objects, you could use the info tip to provide the entire path and file name for the item rather than just the file name.
This interface is obtained by calling IShellFolder::GetUIObjectOf and passing IID_IQueryInfo for the interface identifier. The item for which info tip information is being requested is contained in the apidl argument of the IShellFolder::GetUIObjectOf call. If IQueryInfo is not supplied by the folder, the shell will use the standard display text in the info tip.
When to Use
In most cases, you do not use this interface directly. The shell will use this interface when it requires additional information to display inside of an info tip. However, you can use IQueryInfo directly if you want to obtain info tip information from another object.
| IQueryInfo Methods | Description |
| GetInfoFlags | Retrieves the information flags for an item. |
| GetInfoTip | Retrieves the info tip text for an item. |
Note This interface is only supported in shell versions 4.71 and later.
HRESULT GetInfoFlags(
DWORD *pdwFlags
);
Retrieves the information flags for an item. This method is not currently used.
Version 4.71
See also IQueryInfo
HRESULT GetInfoTip(
DWORD dwFlags,
LPWSTR *ppwszTip
);
Retrieves the info tip text information for an item.
Version 4.71
See also IQueryInfo
The IReconcilableObject interface carries out the reconciliation of a document. The briefcase reconciler is responsible for implementing this interface.
| IReconcilableObject Methods | Description |
| GetProgressFeedbackMaxEstimate | Receives estimate of work required to complete a reconciliation. |
| Reconcile | Reconciles the state of an object with one or more other objects. |
HRESULT IReconcilableObject::GetProgressFeedbackMaxEstimate(
IMoniker ** pulProgressMax
);
Retrieves an estimated measurement of the amount of work required to complete a reconciliation. Reconcilers typically use this method to estimate the work needed to reconcile an embedded document. This value corresponds to a similar value that is passed with the IReconcileInitiator::SetProgressFeedback method during reconciliation.
| OLE_E_NOTRUNNING | The object is an OLE embedded document that must be run before this operation can be carried out. The object state is unchanged as a result of the call. |
| E_UNEXPECTED | Unspecified error. |
See also IReconcilableObject
HRESULT IReconcilableObject::Reconcile(
IReconcileInitiator *pInitiator,
DWORD dwFlags,
HWND hwndOwner,
HWND hwndProgressFeedback,
ULONG ulcInput,
IMoniker **rgpmkOtherInput,
LONG *plOutIndex,
IStorage *pstgNewResidues,
void *pvReserved
);
Reconciles the state of an object with one or more other objects. The reconciliation updates the internal state of the object by merging the states of all objects to form a combined state.
| S_OK | Reconciliation completed successfully, and the changes must be propagated to the other objects. |
| S_FALSE | No reconciliation actions were performed. The briefcase reconciler wishes to fall back to the initiator's bit copy implementation. This value may only be returned if RECONCILEF_ONLYYOUWERECHANGED is set in dwFlags. |
| REC_S_IDIDTHEUPDATES | Reconciliation was completed successfully, and all the objects involved (the object implementing the Reconcile method and all the other objects described by rgpmkOtherInput) have been updated appropriately. The initiator does not need, therefore, to do anything further to propagate the changes. The variable pointed to by plOutIndex should be set to -1L if Reconcile returns this value. The initiator will not save the source object's storage if Reconcile returns this value. This value may only be returned if RECONCILEF_YOUMAYDOTHEUPDATES was set in dwFlags. |
| REC_S_NOTCOMPLETE | The briefcase reconciler completed some, but not all, of the reconciliation. It may need user interaction. The changes will not be propagated to other objects. |
| REC_S_NOTCOMPLETEBUTPROPAGATE | The briefcase reconciler completed some, but not all, of the reconciliation. It may need user interaction. The changes will be propagated to the other objects. |
Otherwise, this method returns one of the following error values:
| REC_E_NORESIDUES | The briefcase reconciler does not support the generation of residues, so the request for residues is denied. The state of the object is unchanged. |
| REC_E_ABORTED | The briefcase reconciler stopped reconciliation in response to a termination request from the initiator (see IReconcileInitiator::SetAbortCallback for more information). The state of the object is unspecified. |
| REC_E_TOODIFFERENT | Reconciliation cannot be carried out because the provided document versions are too dissimilar. |
| REC_E_INEEDTODOTHEUPDATES | The RECONCILEF_YOUMAYDOTHEUPDATES flag was not set when the object's Reconcile implementation was called; this implementation requires that this value be set in the dwFlags parameter. |
| OLE_E_NOTRUNNING | The object is an OLE embedded object that must be run before this operation can be carried out. The state of the object is unchanged. |
| E_UNEXPECTED | Unspecified error. |
| RECONCILEF_FEEDBACKWINDOWVALID | The hwndProgressFeedback parameter is valid. |
| RECONCILEF_MAYBOTHERUSER | The briefcase reconciler can prompt for user interaction if it is needed. Without this value, user interaction is not permitted. The hwndOwner parameter is valid. |
| RECONCILEF_NORESIDUESOK | The briefcase reconciler can ignore requests for residues and carry out reconciliation. Reconcilers that do not support residues should check for this value whenever an initiator requests residues. Without this value, a reconciler that does not support residues must immediately return REC_E_NORESIDUES. |
| RECONCILEF_OMITSELFRESIDUE | The briefcase reconciler can discard any residue associated with this object. Initiators typically use this value for reconciliations that loop from generation to generation. |
| RECONCILEF_ONLYYOUWERECHANGED | The Reconcile method is being called to propagate changes in the changed object to other unchanged objects. This value will only be set if the following key exists in the registry.
HKEY_CLASSES_ROOT\
CLSID\
<clsid_of_reconciler>\
SingleChangeHook
If this key is not present in the registry, the initiator carries out reconciliation by making the other unchanged objects binary identical copies of the changed object. The rgpmkOtherInput monikers identify the other objects. This value will only be set in dwFlags if RECONCILEF_YOUMAYDOTHEUPDATES is also set. If the briefcase reconciler completes the updates itself successfully, REC_S_IDIDTHEUPDATES should be returned and the variable pointed to by the plOutIndex parameter should be set to -1L. Note that S_OK should not be returned on success if this value is set in dwFlags. The initiator will not save the source object's storage if Reconcile returns REC_S_IDIDTHEUPDATES. If the reconciler wishes to fall back to the initiator's bit copy implementation, it may return S_FALSE. |
| RECONCILEF_RESUMEDRECONCILIATION | The briefcase reconciler should resume reconciliation, using the partial residues provided. Without this value, the reconciler should ignore any "considered but rejected" information in any of the input versions. |
| RECONCILEF_YOUMAYDOTHEUPDATES | The briefcase reconciler can perform the updates. Without this value, the reconciler cannot perform the updates. If reconciliation is completed successfully, the reconciler should return REC_S_IDIDTHEUPDATES if it performed the updates or S_OK if it did not perform the updates. |
See also IReconcilableObject
The IReconcileInitiator interface provides the briefcase reconciler with the means to notify the initiator of its progress, to set a termination object, and to request a given version of a document. The initiator is responsible for implementing this interface.
| IReconcileInitiator Methods | Description |
| SetAbortCallback | Sets the object through which the initiator can terminate a reconciliation. |
| SetProgressFeedback | Indicates the amount of progress in the reconciliation. |
HRESULT IReconcileInitiator::SetAbortCallback(
IUnknown *pUnkForAbort
);
Sets the object through which the initiator can asynchronously terminate a reconciliation. A briefcase reconciler typically sets this object for reconciliations that are lengthy or involve user interaction.
| REC_E_NOCALLBACK | The initiator does not support termination of reconciliation operations and does not hold the specified object. |
| E_UNEXPECTED | Unspecified error. |
The initiator can accept or reject the object. If the initiator accepts the object, the briefcase reconciler must remove the object by calling this method with a NULL parameter when the reconciliation is complete. Because the reconciler removes the object after completing reconciliation, there may be times when the initiator releases the object after reconciliation is complete. In such cases, the reconciler ignores the request to terminate.
If the reconciliation is terminated, the IReconcilableObject::Reconcile method must return either the REC_E_ABORTED or REC_E_NOTCOMPLETE value.
See also IReconcileInitiator
HRESULT IReconcileInitiator::SetProgressFeedback(
ULONG ulProgress,
ULONG ulProgressMax
);
Indicates the amount of progress the briefcase reconciler has made toward completing the reconciliation. The amount is a fraction and is computed as the quotient of the ulProgress and ulProgressMax parameters. Reconcilers should call this method periodically during their reconciliation process.
The initiator typically uses this measure of progress to update a thermometer gauge or some other form of visual feedback for the user. The briefcase reconciler can change the value of ulProgressMax from call to call. This means successive calls to this method do not necessarily indicate steady forward progress. Backward progress is legal, although not desirable. It is the responsibility of the initiator to determine whether backward progress should be revealed to the user.
See also IReconcileInitiator
The IShellBrowser interface provides services for namespace extensions and is the companion to the IShellView interface implemented by namespace extensions. It is similar to the site interfaces that are often found in OLE hosting situations, such as the IOleControl and IOleControlSite interfaces. This allows the extension to communicate with the host of the namespace by providing UI elements like menus, status text, and tool bars. This interface also provides the extension with a way to access storage to save its persistent view state.
IShellBrowser derives from the IOleWindow interface, and it represents the container's top-level window. IShellBrowser allows the contained views to insert their menus into the composite menu, install the composite menu into the appropriate window frame, and remove the container's menu elements from the composite menu. IShellBrowser sets and displays status text relevant to the in-place object. It also enables or disables the frame's modeless dialog boxes and translates accelerator keystrokes intended for the container's frame.
When to Implement
You do not implement this interface directly. IShellBrowser is implemented by Windows Explorer and by the Windows File Open common dialog box.
When to Use
When implementing a namespace extension, notably the IShellView interface, you will use the IShellBrowser implementation that is passed to IShellView::CreateViewWindow to communicate with Windows Explorer.
IShellBrowser is derived from IOleWindow. The following are the methods specific to IShellBrowser.
| IShellBrowser Methods | Description |
| BrowseObject | Tells Windows Explorer to browse in another folder. |
| EnableModelessSB | Enables or disables modeless windows of Windows Explorer, such as a floating toolbar. |
| GetControlWindow | Gets the window handle to a Windows Explorer control. |
| GetViewStateStream | Returns a view-specific stream that can be used to read and write the persistent data for a view. |
| InsertMenusSB | Inserts Windows Explorer's menu items to an empty menu created by the view. |
| OnViewWindowActive | Informs Windows Explorer that the view was activated. |
| QueryActiveShellView | Returns the currently activated (displayed) shell view object. |
| RemoveMenusSB | Instructs the container to remove its items from a composite menu. The tasks it performs are the opposite of InsertMenusSB tasks. |
| SendControlMsg | Sends messages to Windows Explorer controls. |
| SetMenuSB | Installs the composite menu in Windows Explorer. |
| SetStatusTextSB | Sets and displays status text in the Windows Explorer window. |
| SetToolbarItems | Adds toolbar items to Windows Explorer's toolbar. |
| TranslateAcceleratorSB | Reserved for future use. |
HRESULT BrowseObject(
LPCITEMIDLIST pidl,
UINT *wFlags
);
Tells Windows Explorer to browse to another folder.
| SBSP_SAMEBROWSER | Browse to another folder with the same Windows Explorer window. |
| SBSP_NEWBROWSER | Creates another window for the specified folder. |
| SBSP_DEFBROWSER | The default behavior is to respect the view option (the user setting to create new windows or to browse in place). In most cases, callers should use this flag. |
The following flags specify either the open, explore, or default mode. These values are ignored if SBSP_SAMEBROWSER is specified or if SBSP_DEFBROWSER is specified and the user has selected Browse In Place.
| SBSP_OPENMODE | Use a normal folder window. |
| SBSP_EXPLOREMODE | Use a Windows Explorer window. |
| SBSP_DEFMODE | Use the current window. |
The following flags specify the pidl parameter's category:
| SBSP_ABSOLUTE | An absolute pidl (relative from the desktop). |
| SBSP_RELATIVE | A relative pidl (relative from the current folder). |
| SBSP_PARENT | Browse the parent folder (ignores the pidl). |
Views can use this method to force Windows Explorer to browse to a specific place in the namespace. Typically, these are folders contained in the view.
See also IShellBrowser
HRESULT EnableModelessSB(
BOOL fEnable
);
Tells Windows Explorer to enable or disable its modeless dialog boxes.
This method is similar to the IOleInPlaceFrame::EnableModeless method. Although the current version of Windows Explorer does not have any modeless dialog boxes, the view should call this method when it wants to disable or enable modeless dialog boxes associated with the Windows Explorer window.
See also IShellBrowser
HRESULT GetControlWindow(
UINT id,
HWND *lphwnd
);
Retrieves the window handle to a browser control.
| FCW_TOOLBAR | Retrieves the window handle to the browser's toolbar. |
| FCW_STATUS | Retrieves the window handle to the browser's status bar. |
| FCW_TREE | Retrieves the window handle to the browser's tree view. |
| FCW_PROGRESS | Retrieves the window handle to the browser's progress bar. |
GetControlWindow is used so views can directly manipulate the browser's controls. FCW_TREE should be used only to determine if the tree is present.
Notes to Callers
GetControlWindow is used to manipulate and test the state of the control windows. Do not send messages directly to these controls; instead, use IShellBrowser::SendControlMsg. Be prepared for this method to return NULL. Future versions of Windows Explorer may not include a toolbar, status bar, or tree window.
Notes to Implementers
GetControlWindow returns the window handle to these controls if they exist in your implementation.
See also IShellBrowser
HRESULT GetViewStateStream(
DWORD grfMode,
LPSTREAM *ppStrm
);
Retrieves an IStream interface that can be used for storage of view-specific state information.
| STGM_READ | Requests an IStream suitable for reading. |
| STGM_WRITE | Requests an IStream suitable for writing. |
| STGM_READWRITE | Requests an IStream suitable for reading and writing. |
This method is used to save and restore the persistent state for a view (the icon positions, the column widths, and the current scroll position, for example).
Notes to Callers
Use GetViewStateStream when the view is being created to read in the saved view state and also when the view is being closed to save any changes to the view state. Typically, the view calls this method with STGM_READ when creating a view window and with STGM_WRITE when the SaveViewState method of its IShellView interface is called.
Notes to Implementers
Each shell view should have its own view stream. Windows Explorer implements a most recently used (MRU) list of view streams that are stored on a per-user basis in the registry.
See also IShellBrowser
HRESULT InsertMenusSB(
HMENU hmenuShared,
LPOLEMENUGROUPWIDTHS lpMenuWidths
);
Allows the container to insert its menu groups into the composite menu that is displayed when an extended namespace is being viewed or used.
This method is similar to the IOleInPlaceFrame::InsertMenus method. Windows Explorer puts File and Edit drop-down menus in the File menu group, View and Tools menus in the Container menu group, and a Help menu in the Window menu group. Each drop-down menu will have a unique identifier, FCIDM_MENU_FILE/EDIT/VIEW/TOOLS/HELP. The view is allowed to insert menu items into those submenus by their identifiers, which is different from OLE's in-place activation mechanism. The command identifiers for menus that the view inserts into either Windows Explorer's submenus or its own submenus must be between FCIDM_SHVIEWFIRST and FCIDM_SHVIEWLAST.
Notes to Callers
This method is called by namespace extensions when they are first being activated so they can insert their menus into the frame-level user interface.
The object application asks the container to add its menus to the menu specified in the hmenuShared parameter and to set the group counts in the OLEMENUGROUPWIDTHS array pointed to by the lpMenuWidths parameter. The object application then adds its own menus and counts. Objects can call the IOleInPlaceFrame::InsertMenus method as many times as necessary to build up the composite menus. The container should use the initial menu handle associated with the composite menu for all items in the drop-down menus.
Notes to Implementers
For IShellBrowser implementations, the menu identifiers must be in the range of FCIDM_BROWSERFIRST to FCIDM_BROWSERLAST.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.