IOleUILinkContainer::GetLinkSource

Returns information about a link that can be displayed in the UI.

HRESULT GetLinkSource(

DWORD dwLink,	//Unique 32-bit link identifier
LPTSTR FAR* lplpszDisplayName,	//Indirect pointer to length of display name portion
ULONG FAR* lplenFileName,	//Pointer to length of file name portion
LPTSTR FAR* lplpszFullLinkType,	//Indirect pointer to full-link type string
LPTSTR FAR* lplpszShortLinkType,	//Indirect pointer to short-link type string
BOOL FAR* lpfSourceAvailable,	//Pointer to availability of link
BOOL FAR* lpfIsSelected	//Pointer to indicate that link entry should be selected in listbox
);

Parameters

dwLink

[in] Container-defined unique 32-bit identifier for a single link. See IOleUILinkContainer::GetNextLink.

lplpszDisplayName

[out] Indirect pointer to the allocated full-link source display name string. The Links dialog box will free this string.

lplenFileName

[out] Pointer to the length of the leading file name portion of the lplpszDisplayName string. If the link source is not stored in a file, then *lplenFileName should be 0. For OLE links, call IOleLink::GetSourceDisplayName.

lplpszFullLinkType

[out] Indirect pointer to the allocated full-link type string that is displayed at the bottom of the Links dialog box. The Links dialog box will free this string. For OLE links, this should be the full User Type name. Use IOleObject::GetUserType, specifying USERCLASSTYPE_FULL for dwFormOfType.

lplpszShortLinkType

[out] Indirect pointer to the allocated short-link type string that is displayed in the listbox of the Links dialog box. The Links dialog box will free this string. For OLE links, this should be the short User Type name. Use IOleObject::GetUserType, specifying USERCLASSTYPE_SHORT for dwFormOfType.

lpfSourceAvailable

[out] Pointer that returns FALSE if it is known that a link is unavailable since the link is to some known but unavailable document. Certain options, such as Update Now, are disabled (grayed in the UI) for such cases.

lpfIsSelected

[out] Pointer to a BOOL variable that tells the Edit Links dialog box that this link’s entry should be selected in the dialog’s multi-selection listbox. OleUIEditLinks calls this method at least once for each item to be placed in the links list. If none of them return TRUE, then none of them will be selected when the dialog box is first displayed. If all of them return TRUE, then all will be displayed. That is, it returns TRUE if this link is currently part of the selection in the underlying document, FALSE if not. Any links that are selected in the underlying document are selected in the dialog box; this way, the user can select a set of links and use the dialog box to update them or change their source(s) simultaneously.

Return Values

This method supports the standard return values E_FAIL,

E_INVALIDARG, and E_OUTOFMEMORY, as well as the following:

S_OK

Successfully returned link information.

E_ACCESSDENIED

Insufficient access permissions.

Remarks

Notes To Callers

Call this method during dialog box initialization, after returning from the Change Source dialog box.

See Also

IOleLink::GetSourceDisplayName, IOleObject::GetUserType, USERCLASSTYPE, OleUIChangeSource, OLEUICHANGESOURCE_com_OLEUICHANGESOURCE_str