/*++ Copyright (c) 1997-1999 Microsoft Corporation. All rights reserved. MODULE NAME: ismapi.h ABSTRACT: Service-to-ISM (Intersite Messaging) service API and ISM-to-plug-in-transport API. DETAILS: CREATED: 97/11/26 Jeff Parham (jeffparh) REVISION HISTORY: --*/ #ifndef __ISMAPI_H__ #define __ISMAPI_H__ #if _MSC_VER > 1000 #pragma once #endif // User-defined control #define ISM_SERVICE_CONTROL_REMOVE_STOP 0x00000080 #ifndef ISM_STRUCTS_DEFINED #define ISM_STRUCTS_DEFINED //============================================================================== // // ISM_MSG structure contains the message data (as a byte blob). // Note, this structure is part of the RPC interface for the IP transport // plug-in. You should not change this structure without renaming it and // preserving the old one; the old one must continue to be used as part of the // old IP RPC interface. // typedef struct _ISM_MSG { DWORD cbData; #ifdef MIDL_PASS [size_is(cbData)] BYTE * pbData; #else BYTE * pbData; #endif LPWSTR pszSubject; } ISM_MSG, *PISM_MSG; typedef ISM_MSG ISM_MSG_V1, *PISM_MSG_V1; //////////////////////////////////////////////////////////////////////////////// // // ISM_SITE_CONNECTIVITY structure describes how sites are interconnected via // a specific transport. // // The pulCosts element should be interpreted as a multidimensional array. // pLinkValues[i*cNumSites + j].ulCost is the cost of communication from site // pSiteDNs[i] to site pSiteDNs[j]. // typedef struct _ISM_LINK { ULONG ulCost; ULONG ulReplicationInterval; ULONG ulOptions; } ISM_LINK, *PISM_LINK; typedef struct _ISM_CONNECTIVITY { ULONG cNumSites; #ifdef MIDL_PASS [ref, size_is(cNumSites)] LPWSTR * ppSiteDNs; [ref, size_is(cNumSites * cNumSites)] ISM_LINK * pLinkValues; #else LPWSTR * ppSiteDNs; ISM_LINK * pLinkValues; #endif } ISM_CONNECTIVITY, *PISM_CONNECTIVITY; //////////////////////////////////////////////////////////////////////////////// // // ISM_SERVER_LIST structure describes a set of servers, identified by DN. // typedef struct _ISM_SERVER_LIST { DWORD cNumServers; #ifdef MIDL_PASS [ref, size_is(cNumServers)] LPWSTR * ppServerDNs; #else LPWSTR * ppServerDNs; #endif } ISM_SERVER_LIST, *PISM_SERVER_LIST; //////////////////////////////////////////////////////////////////////////////// // // ISM_SCHEDULE structure describes a schedule on which two sites are // connected. The byte stream should be interpreted as a SCHEDULE structure, // as defined in \nt\public\sdk\inc\schedule.h. // typedef struct _ISM_SCHEDULE { DWORD cbSchedule; #ifdef MIDL_PASS [ref, size_is(cbSchedule)] BYTE * pbSchedule; #else BYTE * pbSchedule; #endif } ISM_SCHEDULE, *PISM_SCHEDULE; //////////////////////////////////////////////////////////////////////////////// // Refresh reason codes typedef enum _ISM_REFRESH_REASON_CODE { ISM_REFRESH_REASON_RESERVED = 0, ISM_REFRESH_REASON_TRANSPORT, ISM_REFRESH_REASON_SITE, ISM_REFRESH_REASON_MAX // always last } ISM_REFRESH_REASON_CODE; // Shutdown reason codes typedef enum _ISM_SHUTDOWN_REASON_CODE { ISM_SHUTDOWN_REASON_RESERVED = 0, ISM_SHUTDOWN_REASON_NORMAL, ISM_SHUTDOWN_REASON_REMOVAL, ISM_SHUTDOWN_REASON_MAX // always last } ISM_SHUTDOWN_REASON_CODE; #endif // #ifndef ISM_STRUCTS_DEFINED #ifdef __cplusplus extern "C" { #endif #ifndef MIDL_PASS //============================================================================== // // Service-to-ISM (Intersite Messaging) service API. // DWORD I_ISMSend( IN const ISM_MSG * pMsg, IN LPCWSTR pszServiceName, IN LPCWSTR pszTransportDN, IN LPCWSTR pszTransportAddress ); /*++ Routine Description: Sends a message to a service on a remote machine. If the client specifies a NULL transport, the lowest cost transport will be used. Arguments: pMsg (IN) - The data to send. pszServiceName (IN) - Service to which to send the message. pszTransportDN (IN) - The DN of the Inter-Site-Transport object corresponding to the transport by which the message should be sent. pszTransportAddress (IN) - The transport-specific address to which to send the message. Return Values: NO_ERROR - Message successfully queued for send. other - Failure. --*/ DWORD I_ISMReceive( IN LPCWSTR pszServiceName, IN DWORD dwMsecToWait, OUT ISM_MSG ** ppMsg ); /*++ Routine Description: Receives a message addressed to the given service on the local machine. If successful and no message is waiting, immediately returns a NULL message. If a non-NULL message is returned, the caller is responsible for eventually calling I_ISMFree()'ing the returned message. Arguments: pszServiceName (IN) - Service for which to receive the message. dwMsecToWait (IN) - Milliseconds to wait for message if none is immediately available; in the range [0, INFINITE]. ppMsg (OUT) - On successful return, holds a pointer to the received message or NULL. Return Values: NO_ERROR - Message successfully returned (or NULL was returned, indicating no message is waiting). other - Failure. --*/ void I_ISMFree( IN VOID * pv ); /*++ Routine Description: Frees memory allocated on the behalf of the client by I_ISM* APIs. Arguments: pv (IN) - Memory to free. Return Values: None. --*/ DWORD I_ISMGetConnectivity( IN LPCWSTR pszTransportDN, OUT ISM_CONNECTIVITY ** ppConnectivity ); /*++ Routine Description: Compute the costs associated with transferring data amongst sites via a specific transport. On successful return, it is the client's responsibility to eventually call I_ISMFree(*ppConnectivity); Arguments: pszTransportDN (IN) - The transport for which to query costs. ppConnectivity (OUT) - On successful return, holds a pointer to the ISM_CONNECTIVITY structure describing the interconnection of sites along the given transport. Return Values: NO_ERROR - Success. ERROR_* - Failure. --*/ DWORD I_ISMGetTransportServers( IN LPCWSTR pszTransportDN, IN LPCWSTR pszSiteDN, OUT ISM_SERVER_LIST ** ppServerList ); /*++ Routine Description: Retrieve the DNs of servers in a given site that are capable of sending and receiving data via a specific transport. On successful return, it is the client's responsibility to eventually call I_ISMFree(*ppServerList); Arguments: pszTransportDN (IN) - Transport to query. pszSiteDN (IN) - Site to query. ppServerList - On successful return, holds a pointer to a structure containing the DNs of the appropriate servers or NULL. If NULL, any server with a value for the transport address type attribute can be used. Return Values: NO_ERROR - Success. ERROR_* - Failure. --*/ DWORD I_ISMGetConnectionSchedule( LPCWSTR pszTransportDN, LPCWSTR pszSite1DN, LPCWSTR pszSite2DN, ISM_SCHEDULE ** ppSchedule ); /*++ Routine Description: Retrieve the schedule by which two given sites are connected via a specific transport. On successful return, it is the client's responsibility to eventually call I_ISMFree(*ppSchedule); Arguments: pszTransportDN (IN) - Transport to query. pszSite1DN, pszSite2DN (IN) - Sites to query. ppSchedule - On successful return, holds a pointer to a structure describing the schedule by which the two given sites are connected via the transport, or NULL if the sites are always connected. Return Values: NO_ERROR - Success. ERROR_* - Failure. --*/ //============================================================================== // // ISM-to-plug-in-transport API. // typedef void ISM_NOTIFY( IN HANDLE hNotify, IN LPCWSTR pszServiceName ); /*++ Routine Description: Called by the plug-in to notify the ISM service that a message has been received for the given service. Arguments: hNotify (IN) - Notification handle, as passed to the plug-in in the IsmStartup() call. pszServiceName (IN) - Service for which a message was received. Return Values: None. --*/ typedef DWORD ISM_STARTUP( IN LPCWSTR pszTransportDN, IN ISM_NOTIFY * pNotifyFunction, IN HANDLE hNotify, OUT HANDLE *phIsm ); ISM_STARTUP IsmStartup; /*++ Routine Description: Initialize the plug-in. Arguments: pszTransportDN (IN) - The DN of the Inter-Site-Transport that named this DLL as its plug-in. The DS object may contain additional configuration information for the transport (e.g., the name of an SMTP server for an SMTP transport). pNotifyFunction (IN) - Function to call to notify the ISM service of pending messages. hNotify (IN) - Parameter to supply to the notify function. phIsm (OUT) - On successful return, holds a handle to be used in future calls to the plug-in for the named Inter-Site-Transport. Note that it is possible for more than one Inter-Site-Transport object to name a given DLL as its plug-in, in which case IsmStartup() will be called for each such object. Return Values: NO_ERROR - Successfully initialized. other - Failure. --*/ typedef DWORD ISM_REFRESH( IN HANDLE hIsm, IN ISM_REFRESH_REASON_CODE eReason, IN LPCWSTR pszObjectDN OPTIONAL ); ISM_REFRESH IsmRefresh; /*++ Routine Description: Called whenever changes occur according to the reason code. One reason is to the Inter-Site-Transport object specified in the IsmStartup() call. Another is a change to a site in the sites container. Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). dwReason (IN) - Dword indicating the reason we were called pszObjectDN (IN) - Object DN relating to the reason (Current) DN of the Inter-Site-Transport object that named this DLL as its plug-in. Note that this DN will differ from that specified in IsmStartup() if the transport DN has been renamed. Site DN of site that was added, renamed or deleted Return Values: NO_ERROR - Successfully updated. other - Failure. A failure return implies the plug-in has shut down (i.e., no further calls will be made on hIsm, including an IsmShutdown()). --*/ typedef DWORD ISM_SEND( IN HANDLE hIsm, IN LPCWSTR pszRemoteTransportAddress, IN LPCWSTR pszServiceName, IN const ISM_MSG * pMsg ); ISM_SEND IsmSend; /*++ Routine Description: Send a message over this transport. Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pszRemoteTransportAddress (IN) - Transport address of the destination server. pszServiceName (IN) - Name of the service on the remote machine that is the intended receiver of the message. pMsg (IN) - Message to send. Return Values: NO_ERROR - Message successfully queued for send. other - Failure. --*/ typedef DWORD ISM_RECEIVE( IN HANDLE hIsm, IN LPCWSTR pszServiceName, OUT ISM_MSG ** ppMsg ); ISM_RECEIVE IsmReceive; /*++ Routine Description: Return the next waiting message (if any). If no message is waiting, a NULL message is returned. If a non-NULL message is returned, the ISM service is responsible for calling IsmFreeMsg(hIsm, *ppMsg) when the message is no longer needed. If a non-NULL message is returned, it is immediately dequeued. (I.e., once a message is returned through IsmReceive(), the transport is free to destroy it.) Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). ppMsg (OUT) - On successful return, holds a pointer to the received message or NULL. Return Values: NO_ERROR - Message successfully returned (or NULL was returned, indicating no message is waiting). other - Failure. --*/ typedef void ISM_FREE_MSG( IN HANDLE hIsm, IN ISM_MSG * pMsg ); ISM_FREE_MSG IsmFreeMsg; /*++ Routine Description: Frees a message returned by IsmReceive(). Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pMsg (IN) - Message to free. Return Values: None. --*/ typedef DWORD ISM_GET_CONNECTIVITY( IN HANDLE hIsm, OUT ISM_CONNECTIVITY ** ppConnectivity ); ISM_GET_CONNECTIVITY IsmGetConnectivity; /*++ Routine Description: Compute the costs associated with transferring data amongst sites. On successful return, the ISM service will eventually call IsmFreeConnectivity(hIsm, *ppConnectivity); Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). ppConnectivity (OUT) - On successful return, holds a pointer to the ISM_CONNECTIVITY structure describing the interconnection of sites along this transport. Return Values: NO_ERROR - Success. ERROR_* - Failure. --*/ typedef void ISM_FREE_CONNECTIVITY( IN HANDLE hIsm, IN ISM_CONNECTIVITY * pConnectivity ); ISM_FREE_CONNECTIVITY IsmFreeConnectivity; /*++ Routine Description: Frees the structure returned by IsmGetConnectivity(). Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pSiteConnectivity (IN) - Structure to free. Return Values: None. --*/ typedef DWORD ISM_GET_TRANSPORT_SERVERS( IN HANDLE hIsm, IN LPCWSTR pszSiteDN, OUT ISM_SERVER_LIST ** ppServerList ); ISM_GET_TRANSPORT_SERVERS IsmGetTransportServers; /*++ Routine Description: Retrieve the DNs of servers in a given site that are capable of sending and receiving data via this transport. On successful return of a non-NULL list, the ISM service will eventually call IsmFreeTransportServers(hIsm, *ppServerList); Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pszSiteDN (IN) - Site to query. ppServerList - On successful return, holds a pointer to a structure containing the DNs of the appropriate servers or NULL. If NULL, any server with a value for the transport address type attribute can be used. Return Values: NO_ERROR - Success. ERROR_* - Failure. --*/ typedef void ISM_FREE_TRANSPORT_SERVERS( IN HANDLE hIsm, IN ISM_SERVER_LIST * pServerList ); ISM_FREE_TRANSPORT_SERVERS IsmFreeTransportServers; /*++ Routine Description: Frees the structure returned by IsmGetTransportServers(). Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pServerList (IN) - Structure to free. Return Values: None. --*/ typedef DWORD ISM_GET_CONNECTION_SCHEDULE( IN HANDLE hIsm, IN LPCWSTR pszSite1DN, IN LPCWSTR pszSite2DN, OUT ISM_SCHEDULE ** ppSchedule ); ISM_GET_CONNECTION_SCHEDULE IsmGetConnectionSchedule; /*++ Routine Description: Retrieve the schedule by which two given sites are connected via this transport. On successful return, it is the ISM service's responsibility to eventually call IsmFreeSchedule(*ppSchedule); Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pszSite1DN, pszSite2DN (IN) - Sites to query. ppSchedule - On successful return, holds a pointer to a structure describing the schedule by which the two given sites are connected via the transport, or NULL if the sites are always connected. Return Values: NO_ERROR - Success. ERROR_* - Failure. --*/ typedef void ISM_FREE_CONNECTION_SCHEDULE( IN HANDLE hIsm, IN ISM_SCHEDULE * pSchedule ); ISM_FREE_CONNECTION_SCHEDULE IsmFreeConnectionSchedule; /*++ Routine Description: Frees the structure returned by IsmGetTransportServers(). Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). pSchedule (IN) - Structure to free. Return Values: None. --*/ typedef void ISM_SHUTDOWN( IN HANDLE hIsm, IN ISM_SHUTDOWN_REASON_CODE eReason ); ISM_SHUTDOWN IsmShutdown; /*++ Routine Description: Uninitialize transport plug-in. Arguments: hIsm (IN) - Handle returned by a prior call to IsmStartup(). Return Values: None. --*/ #endif // #ifndef MIDL_PASS #ifdef __cplusplus } #endif #endif // __ISMAPI_H__