INewShortcutHook::GetExtension
Interfaces

INewShortcutHook::GetExtension


HRESULT GetExtension(
    LPTSTR pszExtension, 
    int cchExtension
);

Retrieves the file extension for the shortcut object.

pszExtension
Address of a character buffer that receives the extension.
cchExtension
Size of the buffer at pszExtension, in characters.

See also INewShortcutHook

INewShortcutHook::GetFolder

HRESULT GetFolder(
    LPTSTR pszFolder, 
    int cchFolder
);

Retrieves the folder name for the shortcut object.

pszFolder
Address of a character buffer that receives the folder name.
cchFolder
Size of the buffer at pszFolder, in characters.

See also INewShortcutHook

INewShortcutHook::GetName

HRESULT GetName(
    LPTSTR pszName, 
    int cchName
);

Retrieves the file name of the shortcut object, without the extension.

pszName
Address of a character buffer that receives the name.
cchName
Size of the buffer at pszName, in characters.

See also INewShortcutHook

INewShortcutHook::GetReferent

HRESULT GetReferent(
    LPTSTR pszReferent, 
    int cchReferent
);

Retrieves the referent of the shortcut object.

pszReferent
Address of a character buffer that receives the referent.
cchReferent
Size of the buffer at pszReferent, in characters.

For Internet shortcut objects, this method is the same as IUniformResourceLocator::GetURL.

See also INewShortcutHook

INewShortcutHook::SetFolder

HRESULT SetFolder(
    LPTSTR pszFolder 
);

Sets the folder name for the shortcut object.

pszFolder
Address of a character buffer that contains the folder name.

See also INewShortcutHook

INewShortcutHook::SetReferent

HRESULT SetReferent(
    LPCTSTR pszReferent, 
    HWND hWnd
);

Sets the referent of the shortcut object.

pszReferent
Address of a character buffer that contains the referent.
hWnd
Handle to the window that will be used as the parent if the object needs to display a message box or dialog box.

For Internet shortcut objects, this method is the same as IUniformResourceLocator::SetURL.

See also INewShortcutHook

INotifyReplica

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.

INotifyReplica::YouAreAReplica

HRESULT INotifyReplica::YouAreAReplica(
   ULONG ulcOtherReplicas,		
   IMoniker ** rgpmkOtherReplicas		
   );		

Notifies an object that it may be subject to subsequent reconciliation through the IReconcilableObject::Reconcile method.

ulcOtherReplicas
Number of other replicas of the object. This parameter must not be zero.
rgpmkOtherReplicas
Address of an array that contains the addresses of the monikers to use to access the other replicas.

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.

IPersistFolder

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.

IPersistFolder::Initialize

HRESULT Initialize(
    LPCITEMIDLIST pidl,
   );	

Instructs a shell folder object to initialize itself based on the information passed.

pidl
Address of the ITEMIDLIST (item identifier list) structure that specifies the absolute location of the folder.

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

IQueryInfo

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.

IQueryInfo::GetInfoFlags

HRESULT GetInfoFlags(
    DWORD *pdwFlags 
);		

Retrieves the information flags for an item. This method is not currently used.

pdwFlags
Address of a DWORD that receives the flags for the item.

Version 4.71

See also IQueryInfo

IQueryInfo::GetInfoTip

HRESULT GetInfoTip(
    DWORD dwFlags,
    LPWSTR *ppwszTip
);		

Retrieves the info tip text information for an item.

dwFlags
Not currently used.
ppwszTip
Address of a wide character string pointer that receives the tip string pointer. The memory for this buffer is allocated by the implementation using the shell's allocator (see SHGetMalloc). The calling application is responsible for freeing this memory when it is no longer needed by using the shell's allocator.

Version 4.71

See also IQueryInfo

IReconcilableObject

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.

IReconcilableObject::GetProgressFeedbackMaxEstimate

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.

pulProgressMax
Address of the variable to receive the work estimate value.

See also IReconcilableObject

IReconcilableObject::Reconcile

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.

pInitiator
Address of the IReconcileInitiator interface for the initiator of the reconciliation process. This parameter must not be NULL.
dwFlags
Control flags for the reconciliation. This parameter may be zero or a combination of these values:
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.
hwndOwner
Handle to the window to be used as the parent for any child windows that the briefcase reconciler creates. This parameter is valid only if RECONCILEF_MAYBOTHERUSER is specified in dwFlags.
hwndProgressFeedback
Handle to the progress feedback window to be displayed by the initiator. This parameter is valid only if RECONCILEF_FEEDBACKWINDOWVALID is specified in dwFlags. The briefcase reconciler may call the SetWindowText function using this window handle to display additional reconciliation status information to the user.
ulcInput
Number of versions or partial residues specified in dwFlags. This parameter must not be zero.
rgpmkOtherInput
Address of an array that contains the addresses of the monikers to use to access the versions or partial residues to be reconciled.
plOutIndex
Address of the variable that receives an index value indicating whether the result of the reconciliation is identical to one of the initial versions. The variable is set to -1L if the reconciliation result is a combination of two or more versions. Otherwise, it is a zero-based index, with 0 indicating this object, 1 indicating the first version, 2 indicating the second version, and so on.
pstgNewResidues
Address of the IStorage interface used to store the new residues. This parameter can be NULL to indicate that residues should not be saved.
pvReserved
Reserved; must be NULL.

See also IReconcilableObject

IReconcileInitiator

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.

IReconcileInitiator::SetAbortCallback

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.

pUnkForAbort
Address of the IUnknown interface for the object. The initiator signals a request to terminate the reconciliation by using the IUnknown::Release method to release the object. This parameter may be NULL to direct the initiator to remove the previously specified object.

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

IReconcileInitiator::SetProgressFeedback

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.

ulProgress
Numerator of the progress fraction.
ulProgressMax
Denominator of the progress fraction.

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

IShellBrowser

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.

IShellBrowser::BrowseObject

HRESULT BrowseObject(
    LPCITEMIDLIST pidl,
    UINT *wFlags
   );	

Tells Windows Explorer to browse to another folder.

pidl
Address of an ITEMIDLIST (item identifier list) structure that specifies an object's location. This value is dependent on the flag or flags set in the wFlags parameter.
wFlags
Flags specifying the folder to be browsed. It can be zero or one or more of the following values. These first three flags specify whether another window is to be created.
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

IShellBrowser::EnableModelessSB

HRESULT EnableModelessSB(
    BOOL fEnable
   );	

Tells Windows Explorer to enable or disable its modeless dialog boxes.

fEnable
Specifies whether the modeless dialog boxes are to be enabled or disabled. If this parameter is nonzero, modeless dialogs are enabled. If this parameter is zero, modeless dialogs are disabled.

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

IShellBrowser::GetControlWindow

HRESULT GetControlWindow(
    UINT id,
    HWND *lphwnd
   );	

Retrieves the window handle to a browser control.

id
Specifies which control's handle is being requested. This parameter can be one of the following values:
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.
lphwnd
Address of the window handle to the Windows Explorer control.

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

IShellBrowser::GetViewStateStream

HRESULT GetViewStateStream(
    DWORD grfMode,
    LPSTREAM *ppStrm
   );	

Retrieves an IStream interface that can be used for storage of view-specific state information.

grfMode
Specifies the read and write access of the IStream interface. This may be one of the following values:
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.
ppStrm
Address that receives the IStream interface pointer.

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

IShellBrowser::InsertMenusSB

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.

hmenuShared
Specifies a handle to an empty menu.
lpMenuWidths
Address of an OLEMENUGROUPWIDTHS array of six LONG values. The container fills in elements 0, 2, and 4 to reflect the number of menu elements it provided in the File, View, and Window menu groups.

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.