windows-server-2003/admin/pchealth/helpctr/rc/bdychannel/im_inc/sessions.idl

//+---------------------------------------------------------------------------
//
//  Copyright 2001 Microsoft Corporation. All Rights Reserved.
//
//  Contents: Messenger Session invitation interfaces
// 
//----------------------------------------------------------------------------

#ifdef __MKTYPLIB__
#define VARIANT_BOOL boolean
#else  // __MKTYPLIB__
cpp_quote("//+-------------------------------------------------------------------------")
cpp_quote("//")
cpp_quote("//  Microsoft Windows")
cpp_quote("//  Copyright 2001 Microsoft Corporation. All Rights Reserved.")
cpp_quote("//")
cpp_quote("//  File: sessions.h")
cpp_quote("//")
cpp_quote("//--------------------------------------------------------------------------")


import "objidl.idl";
import "oleidl.idl";
import "oaidl.idl";
import "lock.idl";
#endif // __MKTYPLIB__
#include "mdispid.h"

#ifdef __MKTYPLIB__
//--------------------------------------------------------------------------
// Type Library
[
	uuid(53CED51D-432B-45b2-A3E0-0CE2C24235D4), // LIBID_MsgrSessionManager
	version(1.0),
	helpstring("Messenger Session Manager Type Library")
]
library MsgrSessionManager
{
	importlib("stdole32.tlb");
    importlib("lock.tlb");
#endif // __MKTYPLIB__

	interface IMsgrSessionManager;
	interface IMsgrSession;

	typedef enum
	{
		SS_UNKNOWN,
		SS_READY,
		SS_INVITATION,
		SS_ACCEPTED,
		SS_CONNECTED,
		SS_CANCELLED,
		SS_DECLINED,
		SS_TERMINATED,
	} SESSION_STATE;

	#define SESS_E(e) (0x81000600 + (e))
	typedef enum
	{
		SR_APPLICATION_LAUNCH_FAILED	= SESS_E(0x01),
		SR_INVITATION_DECLINED			= SESS_E(0x02),
		SR_CONNECTION_FAILURE			= SESS_E(0x03),
		SR_AUTHENTICATION_FAILED		= SESS_E(0x04),
		SR_SESSION_NOT_READY            = SESS_E(0x05),
		SR_SESSION_CANCELLED_LOCAL		= SESS_E(0x06),
		SR_SESSION_CANCELLED_REMOTE		= SESS_E(0x07),
		SR_SESSION_PROTOCOL_ERROR		= SESS_E(0x08),
		SR_SESSION_TIMEOUT				= SESS_E(0x09),
		SR_CANCEL_BEFORE_CONNECT		= SESS_E(0x0a),
		SR_NOT_INVITEE					= SESS_E(0x0b),
		SR_NOT_INVITER					= SESS_E(0x0c),
		SR_APP_ALREADY_REGISTERED		= SESS_E(0x0d),
		SR_APP_NOT_REGISTERED			= SESS_E(0x0e),
		SR_NOT_VALID_FOR_APP_INVITE		= SESS_E(0x0f),
		SR_APP_NOT_SPECIFIED			= SESS_E(0x10),
		SR_CONTEXT_DATA_OVER_LIMIT		= SESS_E(0x11),
		SR_NO_USER_INVITED				= SESS_E(0x12),
		SR_INVITED_SELF					= SESS_E(0x13),
		SR_SESSION_STATE_INVALID		= SESS_E(0x14),
		SR_INVITATION_SEND_FAILURE		= SESS_E(0x15),
		SR_CANCEL_SEND_FAILURE			= SESS_E(0x16),
		SR_DECLINE_SEND_FAILURE			= SESS_E(0x17),
		SR_ACCEPT_SEND_FAILURE			= SESS_E(0x18),
		SR_CONTEXT_DATA_SEND_FAILURE	= SESS_E(0x19),
	} SESSION_RESULT;

	typedef enum
	{
		SF_NONE					= 0x0000,
		SF_INVITER				= 0x0001,
		SF_INVITEE				= 0x0002,
		SF_APP_INVITE_COMPATIBLE= 0x0004,
	} SESSION_FLAGS;

	//--------------------------------------------------------------------------
	// IMsgrSessionManager Interface
	[
		uuid(305D86C6-6896-4099-91F5-CB7BA7733563), // IID_IMsgrSessionManager
		helpstring("Messenger Session Manager Interface"),
		dual,
		oleautomation
	]
	interface IMsgrSessionManager : IDispatch
	{
		[id(0),
		 helpstring("Create a new Session object."), helpcontext(0)]
		HRESULT CreateSession(
			[out, retval] IDispatch **ppSession);

		[id(1),
		 helpstring("Retrieves the session which launched the application."), helpcontext(0)]
		HRESULT GetLaunchingSession(
			[in] LONG lProcessID,	
			[out, retval] IDispatch **ppSession);

		[id(2),
		 helpstring("Register an app for use with Session Manager."), helpcontext(0)]
		HRESULT RegisterApplication(
			[in] BSTR bstrAppGUID,
			[in] BSTR bstrAppName,
			[in] BSTR bstrAppURL,
			[in] BSTR bstrPath,
			[in] LONG ulFlags);

		[id(3),
		 helpstring("Remove an app from the list."), helpcontext(0)]
		HRESULT UnRegisterApplication(
			[in] BSTR bstrAppGUID);

		[propget,
		 id(4),
		 helpstring("Get the collection of applications."), helpcontext(0)]
		HRESULT Applications(
			[out, retval] IDispatch **ppDisp);
	}

	//--------------------------------------------------------------------------
	// DMsgrSessionManagerEvents Interface
	[
		uuid(52AC8B62-8F88-46ca-902A-1F9106B0A9F4), // DIID_DMsgrSessionManagerEvents
		helpstring("Messenger Events for Session Manager Interface")
	]
	dispinterface DMsgrSessionManagerEvents
	{
		properties:
		methods:
		[id(DISPID_ONINVITATION),
		 helpstring("A new session invitation has been received."), helpcontext(0)]
		void OnInvitation(
			[in] IDispatch *pSession,
			[in] BSTR bstrAppData,
			[in, out] VARIANT_BOOL *pfHandled);

		[id(DISPID_ONAPPREGISTERED),
		 helpstring("A new application has been registered."), helpcontext(0)]
		void OnAppRegistered(
			[in] BSTR bstrAppGUID);

		[id(DISPID_ONAPPUNREGISTERED),
		 helpstring("An application has been unregistered."), helpcontext(0)]
		void OnAppUnRegistered(
			[in] BSTR bstrAppGUID);       
			
		[id(DISPID_ONLOCKCHALLENGE), helpstring("Challenge from server received."), helpcontext(0x0000)]
		void OnLockChallenge(
			[in] BSTR bstrChallenge,
			[in] long lCookie);

		[id(DISPID_ONLOCKRESULT), helpstring("Result from server lock and key service."), helpcontext(0x0000)]
		void OnLockResult(
			[in] VARIANT_BOOL fSucceed,
			[in] long lCookie);

		[id(DISPID_ONLOCKENABLE), helpstring("Enable/disable lock and key."), helpcontext(0x0000)]
		void OnLockEnable(
			[in] VARIANT_BOOL fEnable);

		[id(DISPID_ONAPPSHUTDOWN), helpstring("Messenger is shutting down."), helpcontext(0x0000)]
		void OnAppShutdown();	
	}

	//--------------------------------------------------------------------------
	// IMsgrSession Interface
	[
		uuid(42D7CAFC-0167-4941-A5D8-9FD7F104C41A), // IID_IMsgrSession
		helpstring("Messenger Session Interface"),
		oleautomation,
		dual
	]
	interface IMsgrSession : IDispatch
	{
		[propget,
		 id(0),
		 helpstring("Obtains the application GUID set by the inviter for this session."), helpcontext(0)]
		HRESULT Application(
			[out, retval] BSTR *pbstrAppGUID);

		[propput,
		 id(0),
		 helpstring("Sets the application GUID for the session."), helpcontext(0)]
		HRESULT Application(
			[in] BSTR bstrAppGUID);

		[propget,
		 id(1),
		 helpstring("Gets the current state of the session."), helpcontext(0)]
		HRESULT State(
			[out, retval] SESSION_STATE *pState);

		[id(2),
		 helpstring("Invites user to this session."), helpcontext(0)]
		HRESULT Invite(
			[in] IDispatch *pUser,
			[in] BSTR bstrAppData);

		[id(3),
		 helpstring("Decline an invitation."), helpcontext(0)]
		HRESULT Decline(
			[in] BSTR bstrAppData);

		[id(4),
		 helpstring("Cancel an invitation."), helpcontext(0)]
		HRESULT Cancel(
			[in] long hr,
			[in] BSTR bstrAppData);

		[id(5),
		 helpstring("Accept an invitation."), helpcontext(0)]
		HRESULT Accept(
			[in] BSTR bstrAppData);

		[propget,
		 id(6),
		 helpstring("Retrieve the IP address of the other party in the session."), helpcontext(0)]
		HRESULT RemoteAddress(
			[out, retval] BSTR *pbstrRemoteAddress);		

		[propget,
		 id(7),
		 helpstring("Retrieve session ID."), helpcontext(0)]
		HRESULT SessionID(
			[out, retval] BSTR *pbstrSessionID);

		[propget,
		 id(8),
		 helpstring("Retrieve the app-specific context data."), helpcontext(0)]
		HRESULT ContextData(
			[out, retval] BSTR *pbstrData);

		[propget,
		 id(9),
		 helpstring("Retrieve the application name."), helpcontext(0)]
		HRESULT ApplicationName(
			[out, retval] BSTR *pbstrName);

		[propget,
		 id(10),
		 helpstring("Retrieve the application URL."), helpcontext(0)]
		HRESULT ApplicationURL(
			[out, retval] BSTR *pbstrURL);

		[propget,
		 id(11),
		 helpstring("Retrieve the session flags."), helpcontext(0)]
		HRESULT Flags(
			[out, retval] LONG *plFlags);

		[propget,
		 id(12),
		 helpstring("Retrieve the other user."), helpcontext(0)]
		HRESULT User(
			[out, retval] IDispatch **ppUser);

		[propput,
		 id(13),
		 helpstring("Set the local IP address of the session."), helpcontext(0)]
		HRESULT LocalAddress(
			[in] BSTR bstrLocalAddress);

		[propget,
		 id(13),
		 helpstring("Retrieve the local IP address of the session."), helpcontext(0)]
		HRESULT LocalAddress(
			[out, retval] BSTR *pbstrLocalAddress);
	
		[id(14),
		 helpstring("Send app-specific context data."), helpcontext(0)]
		HRESULT SendContextData(
			[in] BSTR bstrData);

	}

	//--------------------------------------------------------------------------
	// DMsgrSessionEvents Interface
	[
		uuid(1847A74F-2E7F-43af-B7F9-55A4DE3276F5), // DIID_DMsgrSessionEvents
		helpstring("Messenger Events for Session Interface")
	]
	dispinterface DMsgrSessionEvents
	{
		properties:
		methods:
		[id(DISPID_ONSTATECHANGED),
		 helpstring("The session state has changed from prevState."), helpcontext(0)]
		void OnStateChanged(
			[in] SESSION_STATE prevState);

		[id(DISPID_ONAPPNOTPRESENT),
		 helpstring("The app for the invitation is not present."), helpcontext(0)]
		void OnAppNotPresent(
			[in] BSTR bstrAppName,
			[in] BSTR bstrAppURL);

		[id(DISPID_ONACCEPTED),
		 helpstring("The invitee has accepted the invitation."), helpcontext(0)]
		void OnAccepted(BSTR bstrAppData);

		[id(DISPID_ONDECLINED),
		 helpstring("The invitee has declined the invitation."), helpcontext(0)]
		void OnDeclined(BSTR bstrAppData);

		[id(DISPID_ONCANCELLED),
		 helpstring("The session has been cancelled."), helpcontext(0)]
		void OnCancelled(BSTR bstrAppData);

		[id(DISPID_ONTERMINATION),
		 helpstring("The session has ended."), helpcontext(0)]
		void OnTermination(
			[in] long hr,
			[in] BSTR bstrAppData);

		[id(DISPID_ONREADYTOLAUNCH),
		 helpstring("The session is approved for launch."), helpcontext(0)]
		void OnReadyToLaunch();

		[id(DISPID_ONCONTEXTDATA),
		 helpstring("New context data has arrived."), helpcontext(0)]
		void OnContextData(
			[in] BSTR bstrContextData);

		[id(DISPID_ONSENDERROR),
		 helpstring("The last operation failed when sending."), helpcontext(0)]
		void OnSendError(
			[in] long hr);
	}

#ifndef __MKTYPLIB__
//--------------------------------------------------------------------------
// Type Library
[
	uuid(53CED51D-432B-45b2-A3E0-0CE2C24235D4), // LIBID_MsgrSessionManager
	version(1.0),
	helpstring("Messenger Session Manager Type Library")
]
library MsgrSessionManager
{
	importlib("stdole32.tlb");
#endif // __MKTYPLIB__
	//--------------------------------------------------------------------------
	// Messenger session manager class definition
	[
		uuid(E3A3B1D9-5675-43c0-BF04-37BE11939FB7), // CLSID_MsgrSessionManager
		helpstring("Messenger Session Manager Object")
	]
	coclass MsgrSessionManager
	{
		[default] interface IMsgrSessionManager;
		[default, source] dispinterface DMsgrSessionManagerEvents;
	};
};
/* end */