// TortoiseSVN - a Windows shell extension for easy version control
//
// Copyright (C) 2008 - TortoiseSVN
//
// IMPORTANT: While the rest of TortoiseSVN is licensed under the GPL,
// this portion is public domain

midl_pragma warning(disable:2111) // identifier length exceeds 31 characters
import "oaidl.idl";
import "ocidl.idl";
midl_pragma warning(default:2111) // identifier length exceeds 31 characters

[
	object,
	uuid(298B927C-7220-423C-B7B4-6E241F00CD93),
	helpstring("IBugTraqProvider Interface"),
	pointer_default(unique)
]
interface IBugTraqProvider : IUnknown
{
	/** A provider might need some parameters (e.g. a web service URL or a database connection string).
	 * This information is passed as a simple string. It's up to the individual provider to parse and
	 * validate it.
	 *
	 * The ValidateParameters method is called from the settings dialog. This allows the provider to check
	 * that the parameters are OK. The provider can do basic syntax checking, it can check that the server
	 * is reachable, or it can do nothing.
	 *
	 * If the provider needs to report a validation error, it should do this itself, using hParentWnd as
	 * the parent of any displayed UI.
	 */
	HRESULT ValidateParameters (
		[in] HWND hParentWnd,					// Parent window for any UI that needs to be displayed during validation.
		[in] BSTR parameters,					// The parameter string that needs to be validated.
		[out, retval] VARIANT_BOOL *valid		// Is the string valid?
	);

	/** In the commit dialog, the provider is accessed from a button. It needs to know what text to
	 * display (e.g. "Choose Bug" or "Select Ticket").
	 */
	HRESULT GetLinkText (
		[in] HWND hParentWnd,					// Parent window for any (error) UI that needs to be displayed.
		[in] BSTR parameters,					// The parameter string, just in case you need to talk to your web
												// service (e.g.) to find out what the correct text is.
		[out, retval] BSTR *linkText			// What text do you want to display? Use the current thread locale.
	);

	/** Get the commit message. This would normally involve displaying a dialog with a list of the
	 * issues assigned to the current user.
	 */
	HRESULT GetCommitMessage (
		[in] HWND hParentWnd,					// Parent window for your provider's UI.
		[in] BSTR parameters,					// Parameters for your provider.
		[in] BSTR commonRoot,
		[in] SAFEARRAY(BSTR) pathList,
		[in] BSTR originalMessage,				// The text already present in the commit message.
												// Your provider should include this text in the new message, where appropriate.
		[out, retval] BSTR *newMessage			// The new text for the commit message. This replaces the original message.
	);
};

[
	object,
	uuid(C5C85E31-2F9B-4916-A7BA-8E27D481EE83),
	helpstring("IBugTraqProvider2 Interface"),
	pointer_default(unique)
]
interface IBugTraqProvider2 : IBugTraqProvider
{
	/** Get the commit message. This would normally involve displaying a dialog with a list of the
	 * issues assigned to the current user.
	 */
	HRESULT GetCommitMessage2 (
		[in] HWND hParentWnd,					// Parent window for your provider's UI.
		[in] BSTR parameters,					// Parameters for your provider.
		[in] BSTR commonURL,					// the common url of all items in the commit dialog (checked or unchecked!),
												// with the url of the item that was selected to bring up the commit dialog having precedence.
		[in] BSTR commonRoot,
		[in] SAFEARRAY(BSTR) pathList,
		[in] BSTR originalMessage,				// The text already present in the commit message.
												// Your provider should include this text in the new message, where appropriate.
		// you can assign custom revision properties to a commit by setting the next two params.
		// note: both safearrays must be of the same length. For every property name there must be a property value!
		[in] BSTR bugID,						// the content of the bugID field (if shown)
		[out] BSTR * bugIDOut,					// modified content of the bugID field
		[out] SAFEARRAY(BSTR) * revPropNames,	// a list of revision property names which are applied to the commit
		[out] SAFEARRAY(BSTR) * revPropValues,	// a list of revision property values which are applied to the commit
		[out, retval] BSTR * newMessage			// The new text for the commit message. This replaces the original message.
	);

	/** Called right before the commit dialog is dismissed. This is the last chance to reject
	 * a commit. You can check the commit log message here and return an error message if it does not
	 * match your specification. An empty error string means the commit is allowed.
	 */
	HRESULT CheckCommit (
		[in] HWND hParentWnd,
		[in] BSTR parameters,
		[in] BSTR commonURL,
		[in] BSTR commonRoot,
		[in] SAFEARRAY(BSTR) pathList,
		[in] BSTR commitMessage,
		[out, retval] BSTR * errorMessage
		);

	HRESULT	OnCommitFinished (
		[in] HWND hParentWnd,					// Parent window for any (error) UI that needs to be displayed.
		[in] BSTR commonRoot,					// The common root of all paths that got committed.
		[in] SAFEARRAY(BSTR) pathList,			// All the paths that got committed.
		[in] BSTR logMessage,					// The text already present in the commit message.
		[in] ULONG revision,					// The revision of the commit.
		[out, retval] BSTR * error				// An error to show to the user if this function returns something else than S_OK
		);

	HRESULT HasOptions(
		[out, retval] VARIANT_BOOL *ret			// Whether the provider provides options
		);

	// this method is called if HasOptions() returned true before.
	// Use this to show a custom dialog so the user doesn't have to
	// create the parameters string manually
	HRESULT ShowOptionsDialog(
		[in] HWND hParentWnd,					// Parent window for the options dialog
		[in] BSTR parameters,					// Parameters for your provider.
		[out, retval] BSTR * newparameters		// the parameters string
		);
};