IDSSHyperlink Interface Reference

List of all members.

---

Detailed Description

Main interface for a hyperlink object.

A hyperlink object records a link between two reports or documents. A hyperlink can be placed within a grid or field of a report writing document or on the grid of a report. When the user chooses to follow a hyperlink another report or document is executed. The execution may be modified by preanswering prompts on the destination report or document in a manner described by the hyperlink.

In addition to a number of properties about the hyperlink as a whole, the hyperlink can also record how prompts are to be handled. Each separate prompt is represented using a IDSSHyperlinkPrompt interface.

Public Member Functions
HRESULT	_NewEnum ([out, retval] IUnknown pp_NewEnum)
	Enumerator for this collection.
HRESULT	AddPrompt ([in] IDSSPrompt *ipPrompt,[out, retval] IDSSHyperlinkPrompt oppHyperlinkPrompt)
	Add support for a new prompt in the hyperlink.
HRESULT	AnswerMode ([out, retval] EnumDSSHyperlinkAnswerMode *opAnswerMode)
	Get the default answer mode for prompts in the target report or document.
HRESULT	AnswerMode ([in] EnumDSSHyperlinkAnswerMode iAnswerMode)
	Set the default answer mode for prompts in the target report or document.
HRESULT	ClearPrompts ()
	Delete information about all prompts.
HRESULT	Count ([out, retval] Int32 *opCount)
	Returns the number of hyperlink prompt objectss in this collection.
HRESULT	Index ([out, retval] Int32 *opIndex)
	Get the index number of this hyperlink in its collection.
HRESULT	Index ([in] Int32 iIndex)
	Set the index number of this hyperlink in its collection.
HRESULT	IsDefault ([out, retval] VARIANT_BOOL *opIsDefault)
	Get whether or not this is the default hyperlink in its question.
HRESULT	IsDefault ([in] VARIANT_BOOL iIsDefault)
	Set whether or not this is the default hyperlink in its question.
HRESULT	LoadFromXMLDOM ([in] IDSSXMLContext *ipXMLContext,[in] IDispatch *ipParent)
	Load this hyperlink from an XML context.
HRESULT	MultilingualName ([out, retval] IDSSMultilingualString oppMultilingualName)
	Get the multilingual string used to record the hyperlink's display name.
HRESULT	Name ([out, retval] BSTR *opName)
	Get the display name used to visually identify this hyperlink.
HRESULT	Name ([in] BSTR iName)
	Set the display name used to visually identify this hyperlink.
HRESULT	PromptItem ([in] VARIANT *ipIndex,[out, retval] IDSSHyperlinkPrompt oppHyperlinkPrompt)
	Access information about a prompt.
HRESULT	RemovePrompt ([in] VARIANT *ipIndex)
	Remove information about a prompt.
HRESULT	SaveToXMLDOM ([in] IDSSXMLContext *ipXMLContext,[in] IDispatch *ipParent)
	Save this hyperlink to XML.
HRESULT	Target ([out, retval] IDSSObjectInfo oppTarget)
	Get the report or document executed if this hyperlink is defined using an object.
HRESULT	Target ([in] IDSSObjectInfo *ipTarget)
	Set the report or document executed if this hyperlink is defined using an object.
HRESULT	Type ([out, retval] EnumDSSHyperlinkType *opType)
	Set the type of this hyperlink.
HRESULT	Type ([in] EnumDSSHyperlinkType iType)
	Set the type of this hyperlink.
HRESULT	URL ([out, retval] BSTR *opURL)
	Get the URL used when this hyperlink has URL type.
HRESULT	URL ([in] BSTR iURL)
	Set the URL used when this hyperlink has URL type.

---

Member Function Documentation

HRESULT IDSSHyperlink::_NewEnum (  [out, retval] IUnknown   pp_NewEnum  )

Enumerator for this collection. This is the standard property used to return the objects in a collection. It returns an enumerator object. Calling methods on the enumerator object retrieves the contents of the collection. After the enumerator object has been obtained, it is possible for both members of the collection to change. The effect of this change on the members of the collection that are returned by the enumeration object is implementation dependent. Note that the user doesn't retrieve the contents of the collection before calling the Next method on the enumerator object. This property does not presuppose that all of the objects are retrieved simultaneously. Parameters: pp_NewEnum  An IUnknown pointer to the enumerator object. The object is returned using the standard IEnumVARIANT interface. Returns: Usual COM result code: S_OK

HRESULT IDSSHyperlink::AddPrompt (  [in] IDSSPrompt *  ipPrompt, [out, retval] IDSSHyperlinkPrompt   oppHyperlinkPrompt )

Add support for a new prompt in the hyperlink. The prompt is interpreted as a prompt definition, not a prompt instance. All that matters is the ID of the prompt. It is not possible to distinguish between different instances or questions of the same prompt. The hyperlink may only contain one hyperlink-prompt interface for each prompt. If the given prompt already has a hyperlink prompt interface then the existing interface is returned and the collection is not modified. Since the order of prompts in this collection is immaterial, a newly created hyperlink prompt interface is always added to the new of the collection. Parameters: ipPrompt  A reference to the prompt object. oppHyperlinkPrompt  Return a reference to the new hyperlink object. Returns: Usual COM result code: S_OK E_INVALIDARG The ipPrompt object was NULL on entry.

HRESULT IDSSHyperlink::AnswerMode (  [out, retval] EnumDSSHyperlinkAnswerMode *  opAnswerMode  )

Get the default answer mode for prompts in the target report or document. This answer mode is used for all prompts that do not have an explicit setting. Not all values of the enumeration make sense as the default answer mode. Parameters: opAnswerMode  Current value for the property.

HRESULT IDSSHyperlink::AnswerMode (  [in] EnumDSSHyperlinkAnswerMode  iAnswerMode  )

Set the default answer mode for prompts in the target report or document. This answer mode is used for all prompts that do not have an explicit setting. Not all values of the enumeration make sense as the default answer mode. Parameters: iAnswerMode  New value for property.

HRESULT IDSSHyperlink::ClearPrompts (   )

Delete information about all prompts. It is not an error to call this method when the collection is already empty.

HRESULT IDSSHyperlink::Count (  [out, retval] Int32 *  opCount  )

Returns the number of hyperlink prompt objectss in this collection. Parameters: opCount  The number of objects in this collection. Returns: Usual COM result code: S_OK

HRESULT IDSSHyperlink::Index (  [out, retval] Int32 *  opIndex  )

Get the index number of this hyperlink in its collection. Changeing this value moves this hyperlink to a new place, reindexing the other items in the usual manner. Parameters: opIndex  The existing value. Returns: Usual COM result code: S_OK

HRESULT IDSSHyperlink::Index (  [in] Int32  iIndex  )

Set the index number of this hyperlink in its collection. Changeing this value moves this hyperlink to a new place, reindexing the other items in the usual manner. Parameters: iIndex  The new index value. Returns: Usual COM result code: S_OK DSSCOM_E_INDEX_OUT_OF_RANGE The index number was not in the range 1 less than or equal to iIndex less than or equal to Count

HRESULT IDSSHyperlink::IsDefault (  [out, retval] VARIANT_BOOL *  opIsDefault  )

Get whether or not this is the default hyperlink in its question. This property defaults to false for all hyperlinks. That is a freshly created hyperlink, even if it is the only hyperlink in the collection will not be the default hyperlink. It the property is set to true for some hyperlink, the previous default hyperlink of the collection, if any, will automatically be modified to false. Thus a hyperlink collection can contain at most one default hyperlink. Parameters: opIsDefault  Current value for the property.

HRESULT IDSSHyperlink::IsDefault (  [in] VARIANT_BOOL  iIsDefault  )

Set whether or not this is the default hyperlink in its question. This property defaults to false for all hyperlinks. That is a freshly created hyperlink, even if it is the only hyperlink in the collection will not be the default hyperlink. It the property is set to true for some hyperlink, the previous default hyperlink of the collection, if any, will automatically be modified to false. Thus a hyperlink collection can contain at most one default hyperlink. Parameters: iIsDefault  New value for property.

HRESULT IDSSHyperlink::LoadFromXMLDOM (  [in] IDSSXMLContext *  ipXMLContext, [in] IDispatch *  ipParent )

Load this hyperlink from an XML context. Where possible we attempt to reuse the existing state. That is if a property is not mentioned in the XML its existing value is kept. In the case of a multilingual string property the change is only made to the current locale. However if the XML contains a collection of hyperlink prompts then the collection is modified to be exactly as defined in the XML. We are not able to modify just one prompt and leave the rest alone. Parameters: ipXMLContext  The context to use while loading the XML. ipParent  XML node pointing at the hyperlink XML.

HRESULT IDSSHyperlink::MultilingualName (  [out, retval] IDSSMultilingualString   oppMultilingualName  )

Get the multilingual string used to record the hyperlink's display name. This interface can be used to access and modify the display name in locales other than the effective locale of the current user. Parameters: oppMultilingualName  A multilingual string interface.

HRESULT IDSSHyperlink::Name (  [out, retval] BSTR *  opName  )

Get the display name used to visually identify this hyperlink. This property is implemented using a multilingual string, so the name exposed here is actually the effective name of the hyperlink for the current user's MD locale preference. This property defaults to an empty string. There is no requirement that a hyperlink must be named to be valid. Parameters: opName  Current value for the property.

HRESULT IDSSHyperlink::Name (  [in] BSTR  iName  )

Set the display name used to visually identify this hyperlink. This property is implemented using a multilingual string, so the name exposed here is actually the effective name of the hyperlink for the current user's MD locale preference. This property defaults to an empty string. There is no requirement that a hyperlink must be named to be valid. Parameters: iName  New value for property.

HRESULT IDSSHyperlink::PromptItem (  [in] VARIANT *  ipIndex, [out, retval] IDSSHyperlinkPrompt   oppHyperlinkPrompt )

Access information about a prompt. Parameters: ipIndex  Variant value to describe the desired member. Possibilities are: Integer: Index number between 1 and Count String: ID of the desired prompt object. Pointer: Reference to an instance of the prompt (IDSSObjectInfo) oppHyperlinkPrompt  Return pointer to information about the given prompt. Never NULL if the method succeeds. Returns: Usual COM result code: S_OK E_INVALIDARG ipIndex was NULL. DSSCOM_E_INDEX_OUT_OF_RANGE ipIndex was number, but not in correct range. DSSCOM_E_OBJECT_NOT_FOUND ipIndex was string, but no such object was in the collection, or ipIndex was pointer, but no object with this ID was in the collection. DSSCOM_E_BAD_ITEM_SPEC ipIndex was wrong type of Variant.

HRESULT IDSSHyperlink::RemovePrompt (  [in] VARIANT *  ipIndex  )

Remove information about a prompt. The corresponding collection member is deleted. Parameters: ipIndex  Variant value to describe the desired member. Possibilities are: Integer: Index number between 1 and Count String: ID of the desired prompt object. Pointer: Reference to an instance of the prompt (IDSSObjectInfo) Returns: Usual COM result code: S_OK E_INVALIDARG ipIndex was NULL. DSSCOM_E_INDEX_OUT_OF_RANGE ipIndex was number, but not in correct range. DSSCOM_E_OBJECT_NOT_FOUND ipIndex was string, but no such object was in the collection, or ipIndex was pointer, but no object with this ID was in the collection. DSSCOM_E_BAD_ITEM_SPEC ipIndex was wrong type of Variant.

HRESULT IDSSHyperlink::SaveToXMLDOM (  [in] IDSSXMLContext *  ipXMLContext, [in] IDispatch *  ipParent )

Save this hyperlink to XML. Parameters: ipXMLContext  The context to use while serializing the XML. ipParent  XML node under which the hyperlink will be serialized.

HRESULT IDSSHyperlink::Target (  [out, retval] IDSSObjectInfo   oppTarget  )

Get the report or document executed if this hyperlink is defined using an object. This property defaults to NULL. It is ignored if the hyperlink is defined by a URL. Although the property appears to accept any object type, only reports or documents can be assigned to the property. Parameters: oppTarget  The current value of this property. Note that it is not an error for this value to be NULL, so callers should not assume that the value is non-NULL just because this method succeeds. Returns: Usual COM result code: S_OK

HRESULT IDSSHyperlink::Target (  [in] IDSSObjectInfo *  ipTarget  )

Set the report or document executed if this hyperlink is defined using an object. This property defaults to NULL. It is ignored if the hyperlink is defined by a URL. Although the property appears to accept any object type, only reports or documents can be assigned to the property. Parameters: ipTarget  New value for the property. May be NULL. Returns: Usual COM result code: S_OK E_INVALIDARG The object is not NULL, but it is neither a report nor a document.

HRESULT IDSSHyperlink::Type (  [out, retval] EnumDSSHyperlinkType *  opType  )

Set the type of this hyperlink. A hyperlink can either be defined using a URL (the default) or by explicitly specifying a target report or report writing document. Although some properties only make sense for certain types of hyperlink we do not attempt to clear unused properties based on the hyperlink's type. Instead unused properties are just ignored. Parameters: opType  Current value for the property.

HRESULT IDSSHyperlink::Type (  [in] EnumDSSHyperlinkType  iType  )

Set the type of this hyperlink. A hyperlink can either be defined using a URL (the default) or by explicitly specifying a target report or report writing document. Although some properties only make sense for certain types of hyperlink we do not attempt to clear unused properties based on the hyperlink's type. Instead unused properties are just ignored. Parameters: iType  New value for property.

HRESULT IDSSHyperlink::URL (  [out, retval] BSTR *  opURL  )

Get the URL used when this hyperlink has URL type. This property defaults to an empty string. It is not a multilingual string. Parameters: opURL  Current value for the property.

HRESULT IDSSHyperlink::URL (  [in] BSTR  iURL  )

Set the URL used when this hyperlink has URL type. This property defaults to an empty string. It is not a multilingual string. Parameters: iURL  New value for property.

---