|
|
#ifndef _SERVERDLL_INC
#define _SERVERDLL_INC
#ifdef __cplusplus
extern "C" {#endif
/***************************************************************************
Name : lmi.h
Comment : Defines the Logical Modem Interface.
Created : 9/9/93
Author : Sharad Mathur
Contribs :
Changes : 12/29/93: Changed UINTS to WORDS 12/29/93: Put min length restriction on String in LMI_AddModem 12/29/93: Changed display string comments to remove "Fax Modem on" 12/29/93: Changed NetAuthenticateDll API 8/4/94 : Defined FAXERROR 8/4/94 : Changed capabilities to bits & added new ones 8/4/94 : Changed SERVERSTATE to be a bitfield 8/4/94 : Changed NetReportRecv & LMI_ReportSends to return DWORD counts. 8/4/94 : Changed enum's to #define's 8/4/94 : Changed LPSTR to LPTSTR, & added fUnicode. 9/23/94 : Added Poll request support - LMIPOLLREQUEST, POLLTYPE, wszPollRequest(LMISENDJOB), dwPollContext(LMIRECVSTATUS), POLL_REQUEST capability 9/23/94 : Added Custom msg options support LMI_SetCustomMsgOptions, wrgbCustomOptionsOffset(LMISENDJOB), CUSTOM_MSG_OPTIONS capability. 9/23/94 : Added 4 ext error codes to T30_DIALFAIL. 9/23/94 : Added lpatError to LMI_CheckProvider. 9/26/94 : Added NRR_COMMITTED_RECEIVE to LMI_ReportReceives 10/6/94 : Added ABOVE64K_STRUCTURES to caps, and made total size & struct offsets in LMISENDJOB DWORDS. 10/6/94 : Made all structs DWORDS aligned. 10/6/94 : Added User request fields to LMI_ReportSends 10/6/94 : Added user request flags to LMI_GetQueueFile 10/6/94 : Changed dwNumEntries in LMIQUEUEFILEHEADER to dword 10/6/94 : Updated AtWork address definition to include \@ & | 10/7/94 : Consolidated all unsupported dialchar codes. 10/17/94: Added NCUDIAL_BADDIALSTRING 10/17/94: Moved lpatClientName from LMI_InitProvider to LMI_InitLogicalModem 10/17/94: Added LMIERR_PROVIDER_BUSY
03/16/95 (kentse) The big reorg. changed from Srvrdll to LMI. (A large change). 04/05/95 (kentse) Completed the big rewrite.
***************************************************************************/
#define MAX_SERVERNAME_SIZE 32
#define MAX_SUBJECT_SIZE 128
typedef ATOM FAR* LPATOM;typedef UINT FAR* LPUINT;
//////////////////////// OVERVIEWS ///////////////////////////////////////
/****
@doc EXTERNAL SRVRDLL OVERVIEW
@topic Introduction to the Logical Modem Interface | The Logical Modem Interface (LMI) was developed to facilitate the easy creation of a fax service provider for a Microsoft Fax transport running on a PC. Microsoft Fax is supported in Windows 95 and will be supported in the shell update release of Windows NT 3.51. There is also support in Windows for Workgroups<tm> 3.11 (where Microsoft Fax was known as Microsoft At Work <tm>). A fax service provider written to the LMI will work on all these platforms. For this discussion of the LMI, no distinction is made between operating environments.
The Logical Modem Interface divides Microsoft Fax support in Windows into two parts: a fax transport that sits above the LMI, and one or more LMI providers that sit underneath. The fax transport is a messaging provider integrated with mail (MAPI) that can expose faxing capabilities to the user in many ways. Most fundamentally, faxing capability is exposed through the Microsoft Mail or Microsoft Exchange Send Note form, where fax is treated as just another valid address type by the user. But faxing capability is also exposed to the user through a <lq>print to fax<rq> mechanism hooked into the printing system (this user interface is more typical for alternative fax packages). In the new Windows shell, fax is also exposed through a <lq>send fax wizard<rq>. Regardless of the method chosen by the user to compose a fax, once <lq>sent<rq> by the user the fax message ends up as a message in the mail store. In general, any outbound message in the store is extracted by MAPI, and, if addressed to one or more fax recipients, the message is handed over to the fax transport for delivery.
The fax transport performs several types of processing on a fax message after receiving it from MAPI. The objective of this processing is to create a data stream that contains the actual bits that need to be sent across the wire. (It is assumed that in most cases, a fax will be sent over a PSTN connection. This need not always be so, such as in the case of a NetFax server.) The format of this data might be one of the standard MH, MR, or MMR formats; or it might be the Microsoft Fax linearized file format, which allows multiple, binary attachments. The transport intelligently decides which format or formats to generate (more than one may be generated) based partly on cached (or unknown) capabilities of the recipient, and partly on preferences expressed by the user. Especially in cases where the transport cannot decide the best format, it may generate several, postponing the actual decision of which to send until run time. Once the appropriate formats have been generated, the main work of the fax transport is done. From that point, responsibility for sending the fax belongs to the active LMI provider. The user could have several LMI providers installed, such as a local modem and a network fax service provider, but only one can be active at a time.
The fax transport has no knowledge of any physical modem or phone line. It only knows about the existence of a <lq>logical modem<rq>. The transport can submit jobs to be sent over this modem without worrying about how they will be sent. An LMI provider can accept these jobs and complete them in any way, including by forwarding the data to a different machine (which could be running a custom operating system) where a physical fax modem is installed.
Once it completes sending the fax, the LMI provider must return the results of the send to the sending fax transport. Because sending faxes and communicating between machines can be time-consuming, the interface is completely asynchronous. None of the calls into the interface require blocking of the fax transport while the LMI provider performs some operation. The LMI provider benefits from this division of labor because all of the intelligence is kept common in the fax transport, including all knowledge about keeping capabilities, rendering attachments to the message, getting data from OLE objects, and so on.
The LMI is designed so that all structures and data passed through the interface are already marshaled into blocks of BYTES. This simplifies the implementation of the LMI provider in the case where the provider is used with a network front-end processor and where the actual fax call is not made in the same process context as the provider interface. The LMI provider must parse the structures, dial the numbers, and send the appropriate format across the connection. To communicate with other Microsoft Fax-enabled machines over a PSTN connection, the LMI provider must be able to talk the Microsoft Extended Fax Protocol (MEFP) on the wire. MEFP is a set of NSF extensions to the ITU T.30 protocol; the details of this protocol are documented elsewhere. The current document assumes that the LMI provider can talk to Microsoft Fax clients and decipher their capabilities in order to make intelligent decisions about which format is to be sent.
There is a wide range of functionality an LMI provider may choose to provide. At the simplest, an LMI provider can decide to only provide send-fax services, with no capability of queuing, scheduling, and so on. A more complex LMI provider can have it's own phone books, generate cover pages, print incoming faxes, do inbound routing of other faxes, do load balancing with multiple hardware phone lines, and much more. The LMI encourages vendors to differentiate their offerings. The same fax transport can talk to an LMI provider with any kind of functionality. The fax transport makes dynamic decisions based on capability flags that are part of the LMI.
Except for a few configuration functions, the interface is guaranteed to be called from a single process context. However, the client software can consist of multiple threads, each of which may call portions of this interface. It is possible for a second API to be called while still in the middle of a previous call (the calls would be in different thread contexts). This is important. It means that the LMI provider must protect itself from reentrancy issues.
A logical modem is treated as a single queue to which jobs can be sent. There is not necessarily a one-to-one correspondence between a logical modem and a physical modem. An implementation can hide several modems behind a single queue and do load balancing among the modems.
Important: Unless explicitly stated otherwise, an LMI provider should not present any user interface in any interface calls. Many of these calls are made in the background and are not expected to put up UI (including message boxes).
@topic Overview of the LMI Provider Interface | This document describes the services a fax provider must implement to act as a fax provider to a Microsoft Fax client through the LMI. The interface has several main components. The parts are installation, configuration, queue administration and status, sending faxes, receiving faxes, and uploading documents and cover pages. Each of these is covered in detail in the following sections.
It is useful to present a high-level overview of how the fax transport calls into the Logical Modem Interface. At first, the transport's configuration user interface calls <f LMI_AddModem> and <f LMI_RemoveModem> to control which modems exist in the list of available modems. It also calls <f LMI_ExchangeCaps> to make any necessary configuration decisions. When the fax transport initializes, it calls <f LMI_InitProvider> and <f LMI_InitLogicalModem>. The transport can then send faxes with <f LMI_SendFax>. The transport polls for the status of sent faxes with <f LMI_ReportSend> and looks at the provider's queue with <f LMI_GetQueueFile>. To abort or reschedule a fax that has been sent but has not yet left the queue, the transport can call <f LMI_AbortSendJob> and <f LMI_RescheduleSendJob>. The transport polls for received faxes with <f LMI_ReportReceives>. Finally, the transport calls <f LMI_DeinitLogicalModem> and <f LMI_DeinitProvider> when it is time to shut down.
A useful example to study for understanding the flow across the LMI is the simple case of a send on one machine leading to a receive on another. A send starts off as a note composed in a mail client by the user. In this example, the user types in some text and attaches a bitmap. The user addresses the note to a single fax recipient at the phone number 555-1234 and chooses to send the note in the best format possible at the cheap-rate time. When the note is ready, the user <lq>sends<rq> the note (this really just saves the message to the store).
The message is then picked up from the store and is handed to the fax transport, because the message has a fax recipient. The fax transport looks into its capability database for the number 555-1234, but (in this example) finds no entry. Because the user chose to send the message in the best format possible, the fax transport converts the message into two formats: a rendered, MMR version (images only) and a linearized file-format version (binary file). For the rendered version, the transport itself renders the text; calls Paintbrush to render the bitmap file; and finally generates a file combining the rendered images, to which it attaches a linearized header. For the linearized version, the transport calls the linearizer, which assembles the binary attachments as-is into a file with a linearized header.
After creating the two separate files, the fax transport calls <f LMI_SendFax> in the LMI provider. In the call, the transport passes in the details of the job as well as the file name for each of the two formats that were generated. In response to the call, the LMI provider examines the details of the send job. Seeing that the fax (in this example) is to be sent at cheap rates, it leaves the job on its internal queue. The fax transport periodically polls the LMI provider for the status of the fax.
When cheap times roll around, the LMI provider connects to 555-1234 using a local modem and sends the appropriate format (the MMR file if the receiver is a G3 fax machine, or the linearized file if the receiver uses Microsoft Fax). The next time the fax transport calls <f LMI_ReportSend> after the fax is sent over the wire, the LMI provider returns the final status of the send job. Upon receipt of this status, the fax transport passes it on to the user, typically generating a Non-Delivery Report (NDR) if there was an error, or moving the message into the Sent Mail folder if the send was successful.
Received faxes are available immediately to the LMI provider on the remote machine, since it is the one picking up the phone. The LMI provider then has to decide to which client the message needs to be routed. For reception of G3 faxes, intelligent decisions are not possible since there is no structured routing information; routing to some default client is probably best. For Microsoft Fax messages, the LMI provider can interpret the linearized header (using some helper functions) and extract the Microsoft Fax address of the recipient. If this address contains a routing name, the name can be matched to a list of clients and the fax can be easily routed.
Once the LMI provider has decided on the recipient client, it waits for that client's fax transport to regularly poll for new faxes. When polled (by a call to <f LMI_ReportReceives>), the provider creates a file with the received data in an appropriate format. If the fax was received from a G3 fax machine, the provider can use helper functions to construct a file starting with a linearized header, followed by AWG3 page headers, finally followed by the data. For linearized file-format faxes, the exact data received is passed in. Finally, the client fax transport parses the data file (of whichever format) and creates a new message in the mail client Inbox containing the data in a format the user can view. @topic Installation | Installing a new LMI provider module is a two step process. First, the installation program must create an entry in the MSATWORK.INF file as defined below.
MSATWORK.INF file format:
[External Devices]<nl> \<device name\>=\<description\><nl> .<nl> .<nl> \<device name\>=\<description\>
[\<device name\>]<nl> Display Name=\<name to show devices list box\><nl> DLL Name=\<name of the DLL for this device\><nl> Flags=\<see below\><nl>
[\<device name\>]<nl> Display Name=\<name to show devices list box\><nl> DLL Name=\<name of the DLL for this device\><nl> Flags=\<see below\>
Explanation:
\<device name\>: Name of the section of the below device.<nl> \<description\>: Description of the device, for INF-file purposes only, not used anywhere else.<nl> Display Name: Name of the device. This name will be displayed in the AddDevice dialog listbox.<nl> DLL Name: Name of the DLL that services this device.<nl> Flags: Currently will be zero. Can be used for various device capabilities, like whether this device allows setup, etc.
Example:
[External Devices]<nl> IFAX=An intelligent fax machine<nl> AcmeFax=A future fax provider
[IFAX]<nl> Display Name=Intelligent fax machine<nl> DLL Name=ifax32.dll<nl> Flags=0
[AcmeFax]<nl> DLL Name=acme32.dll
Next, when the user installs a new fax modem from the configuration interface, the user is presented with a list of all strings from the Display Name section of the MSATWORK.INF file. When the user chooses Display Name, <f LMI_AddModem> is called to allow the LMI provider to put up a dialog box that asks the user to choose a logical modem from that LMI provider.
<f LMI_AddModem> returns a string representing the logical modem the user has selected. This string is then displayed in the list of currently available modems. The user can choose the current default fax modem from this list.
@topic Configuration | The user is allowed to configure any of the available fax modems (logical modems). <f LMI_ConfigureModem> is called for the appropriate LMI provider. This function allows the user to do whatever remote configuration options are permitted. These may be divided into user-configurable and administrator-configurable options. In general, there should be very few user configurable options. For administrator options, this function should probably use some kind of password protection.
@topic Initialization | When the fax transport starts, the <f LMI_InitProvider> function is called for the appropriate LMI provider. Then, the <f LMI_InitLogicalModem> function is called for the modem the client wants to use. This function intializes the logical modem and return to the client a handle to the modem, as well as the modem�s capabilities. The capabilities include support for advanced features and are used by the client to decide what kind of operations are supported by the LMI provider. An example of an important capability is whether or not the modem is Microsoft Fax enabled. The phone number of the modem is some other information returned by this call. Several logical modems may be initialized at the same time. All operations on a modem use the handle returned by the <f LMI_InitLogicalModem> call.
@topic Queue Management | To allow the user to see up-to-date status for all the jobs of an LMI provider, functions have been defined to let the client monitor and administer the provider's queue. <f LMI_GetQueueFile> is called whenever the user wants to see the queue. This function gives access to a specific set of information about each job in the provider's queue. The information is displayed in a uniform manner by the fax transport. To allow value-added, extended-status displays, arbitrary binary information can also be passed back as part of the status. If the user wants detailed status on a particular job, <f LMI_DisplayCustomStatus> is called with this binary information to display more detailed status. If the user wants to cancel or reschedule jobs, the functions <f LMI_AbortSendJob> and <f LMI_RescheduleSendJob> may be called.
@topic Sending Faxes | When a fax is to be sent, the transport assumes all responsibility for rendering the appropriate formats for transmission. The transport maintains a cache of the capabilities for all fax machines it has talked to before and uses the database to attempt intelligent decisions about the most efficient format to be sent. The transport also takes into account explicit user preferences. There are three different formats that can be sent. The first is for sending to standard fax machines and consists of MH, MR or MMR data. The second format is a linearized EFAX message containing only image data. The third format is a linearized EFAX message containing binary data. All three formats are always preceded by a linearized header describing the file. See <lq>Microsoft At Work Linearized File Format<rq> for details of this header. Details of the fax file format are in <lq>AWG3 File Format<rq>.
When the fax has been sent, the LMI provider reports the final status for the job via <f LMI_ReportSend>. This function is polled periodically by the fax transport. Along with the final status, the Provider must return the newly found capabilities of all the recipients of the fax. The client can also ask for attention using the <f LMI_CheckProvider> function.
Poll requests are also submitted using LMI_SendFax. Fields in the LMISENDJOB structure provide the information for the poll request.
@topic Receiving Faxes| All received faxes need to be routed by the fax transport to the appropriate LMI provider. The Microsoft At Work fax transport polls for received faxes using the <f LMI_ReportReceives> function.
As with sent faxes, received faxes can be in any one of three formats. The header for the file describes the format and gives information about the recipients of this message. All formats MUST have a linearized header describing the format and contents of the message. See <lq>Microsoft At Work Linearized File Format<rq> for details of this header. Details of the Fax file format are in <lq>AWG3 File Format<rq>.****/
/********
@doc EXTERNAL SRVRDLL DATATYPES
@topic Microsoft At Work Address |
This section describes the Microsoft At Work address format. In its most common form, this consists of a name and a phone number. The phone number is assumed to begin at the last @ in the address. In its more complex forms, the name could contain more routing information.
Ideally, the phone number in the address is in the canonical form. This consists of +\<country code\>[\<area code\>]\<local number\>[\|\<suffix\>].
Other important things to note: An @ can be escaped by using a backslash, and a suffix may be added to the canonical number by using a \| symbol after the number and following that with the suffix.
@ex Some Examples: | A simple Micsosoft At Work Address might look like
JohnDoe@+1(206)5551212|$999
which would indicate that after dialing the number, we should wait for a beep and dial a 999. THe receiving number would then route to JohnDoe. If the number is an IFAX machine, John would have an account with the login JohnDoe, or if the number was a PC, JohnDoe would be the email alias for his account. In general, the <name> part of the address must be interpreted by the receiving machine and can contain any routing information necessary for inbound routing by this machine.
*********/
/****
@doc EXTERNAL SRVRDLL OVERVIEW
@topic Constants| The following section contains a list of predefined return codes, error codes, and other predefined values used throughout this document.
****/
/********
@doc EXTERNAL SRVRDLL DATATYPES
@type NONE | LMI_RETURN | Return codes for LMI provider API's.
@emem LMI_SUCCESS | No error - function was successful.
@emem LMIERR_CONNECT_FAILED | Connection to Provider failed. Client should go offline.
@emem LMIERR_NOT_SUPPORTED | Some function/parameter was not supported by this LMI provider.
@emem LMIERR_OPERATION_FAILED | Generic failure code.
@emem LMIERR_OP_CANCELLED | Operation canceled by user.
@emem LMIERR_PROVIDER_BUSY | The Provider was temporarily unavailable to accept requests. This might be useful for Providers which have limits on the number of connections supported. The clients response to this error code should be to try and retry the operation if possible, particularly for API's like <f LMI_SendFax>. However, some clients may treat this as a failure.
@emem LMIERR_SERVER_RESOURCES_LOW | The Provider failed due to a low resource situation on a server.
********/
typedef DWORD LMI_RETURN;
#define LMI_SUCCESS 0
#define LMIERR_CONNECT_FAILED 1
#define LMIERR_NOT_SUPPORTED 2
#define LMIERR_OPERATION_FAILED 3
#define LMIERR_OP_CANCELLED 4
#define LMIERR_PROVIDER_BUSY 5
#define LMIERR_SERVER_RESOURCES_LOW 6
/********
@doc EXTERNAL SRVRDLL DATATYPES
@type NONE | FAXERROR | DWORD Error status codes returned in the <t LMIFORMAT>, <t LMIRECIPSTATUS>, <t LMISENDSTATUS>, and <t LMIRECVSTATUS> structures. This error consists of three parts: an error code, an extended error code, and error specific data (in some cases). The extended error code must be set to T30_UNKNOWN if the means for setting a more meaningful error are not available. A value of zero in the data field implies that there is no valid data for this error. In those cases where the extended error or data fields are unused, they must be set to zero. This is to allow these fields to be used in the future.
@emem Error Code | The low BYTE of the low word of the error is the error code. Use the macro GetErrCode(error) to extract this BYTE. The error codes defined are:
@flag T30_CALLFAIL | An error occured during actual transmission of the fax. Detailed error status can be determined from the extended error field. @flag T30_DIALFAIL | An error occured during dialing the fax number. Detailed error status can be determined from the extended error field. @flag T30_ANSWERFAIL | An error occured during answering of a phone call. Detailed error status can be determined from the extended error field. @flag T30_NOMODEM | The Provider could not find any hardware modem to send the fax over. This would typically indicate that the user had physically removed some hardware from the machine. @flag T30_FILE_ERROR | An error occured trying to read or parse the format files which were passed in. Detailed error status may be found in the extended error. @flag T30_MODEMERROR | An error occured while trying to talk with the hardware modem. @flag T30_PORTBUSY | The port on which the hardware modem was installed cannot be opened. Extended error status contains more details. @flag T30_MODEMDEAD | The hardware modem has stopped responding to any AT commands. This typically requires some human intervention, such as turning the power off and back on. @flag RES_NOMEMORY | The Provider ran out of memory resources. @flag RES_LOWDISK | The Provider ran out of disk space. @flag USER_ABORT | The job was cancelled on a user request. @flag RENDERING_FAILURE | For Provider's that do any rendering, this indicates the class of failures which result in the inability to render a final format to be sent. Extended errors give more details. @flag RES_LOW_SERVER | The Provider failed due to a low resource problem on a server. @flag CUSTOM_ERROR | If the Provider happens to get an error which does not fall into any of the classes specifically defined here, then it can pass back a custom error. In this case the data field contains a global atom which identifies a string describing the error in terms understandable to the user. NOTE: This error is not supported by Windows 95, but will be in a later release. @flag GENERAL_FAILURE | Indicates a serious internal error in the software.
@emem Extended error codes for T30_DIALFAIL | Any of the following could be the reason for a dial failure:
@flag NCUDIAL_ERROR | Detailed error is unknown. @flag NCUDIAL_BUSY | The called number was busy. @flag NCUDIAL_NOANSWER | The dialed number did not answer. @flag NCUDIAL_NODIALTONE | No dialtone could be detected. @flag NCUDIAL_MODEMERROR | There was some hardware problem in the modem while trying to dial. @flag NCUDIAL_BADDIALSTRING | The dial string was badly formed. In general, logical modems should try to be as robust as possible, ignoring characters which are not understood. This error code should only be used for cases where the string is so obviously malformed that there is no point even attempting to dial.
@emem Extended error codes for T30_ANSWERFAIL | The provider does not have to report receives which failed in the answering phase itself. However, if it chooses to do so, the following codes apply:
@flag NCUANSWER_ERROR | Detailed error is unknown. @flag NCUANSWER_NORING | No ring was detected. @flag NCUANSWER_MODEMERROR | There was some hardware problem in the modem while trying to answer.
@emem Extended error codes for T30_PORTBUSY | The port could be busy for two reasons:
@flag PORTBUSY_SELFUSE | The port is already being used by us. A common case causing this error is if a receive is in progress. The client will typically retry the call at a later time, transparently to the user. @flag PORTBUSY_OTHERAPP | The device or port is used by some other application.
@emem Extended error codes for T30_CALLFAIL | This is likely to be the most common error, and very detailed error codes are defined for it. The extended error can be any of the following:
@flag T30FAILS_T1 | Send T1 timeout (No NSF/DIS Received). @flag T30FAILS_TCF_DCN | Received DCN after TCF. @flag T30FAILS_3TCFS_NOREPLY | No reply to three attempts at training (TCF). @flag T30FAILS_3TCFS_DISDTC | Remote does not see our TCFs. @flag T30FAILS_TCF_UNKNOWN | Got garbage response to TCF. @flag T30FAILS_SENDMODE_PHASEC | Modem error or timeout at start of page. @flag T30FAILS_MODEMSEND_PHASEC | Modem error or timeout within page. @flag T30FAILS_MODEMSEND_ENDPHASEC | Modem error or timeout at end of page. @flag T30FAILSE_SENDMODE_PHASEC | Modem error or timeout at start of ECM page. @flag T30FAILSE_MODEMSEND_PHASEC | Modem error or timeout within ECM page. @flag T30FAILSE_MODEMSEND_ENDPHASEC | Modem error or timeout at end of ECM page. @flag T30FAILSE_BADPPR | Bad PPR received from receiver. @flag T30FAILS_3POSTPAGE_NOREPLY | No response after page: Probably receiver hungup during page transmit. @flag T30FAILS_POSTPAGE_DCN | Received DCN after page. @flag T30FAILSE_3POSTPAGE_NOREPLY | No response after page. Probably receiver hungup during page transmit. @flag T30FAILSE_POSTPAGE_DCN | Received DCN after ECM page. @flag T30FAILSE_POSTPAGE_UNKNOWN | Received garbage after ECM page. @flag T30FAILSE_RR_T5 | Receiver was not ready for more than 60 seconds during ECM flow-control. @flag T30FAILSE_RR_DCN | Received DCN after RR during ECM flow-control. @flag T30FAILSE_RR_3xT4 | No response from receiver during ECM flow-control. @flag T30FAILSE_CTC_3xT4 | No response from receiver after CTC (ECM baud-rate fallback). @flag T30FAILSE_CTC_UNKNOWN | Garbage response from receiver after CTC (ECM baud-rate fallback). @flag T30FAILR_PHASEB_DCN | Receiver: Sender decided we're incompatible. @flag T30FAILR_T1 | Receiver: Caller is not a fax machine or hung up. @flag T30FAILR_UNKNOWN_DCN1 | Receiver: Received DCN when command was expected. @flag T30FAILR_T2 | Receiver: No command was received for seven seconds. @flag T30FAILR_UNKNOWN_UNKNOWN2 | Receiver: Received garbage when command was expected. @flag T30FAILR_MODEMRECV_PHASEC | Receiver: Page not received, modem error or timeout at start of page. @flag T30FAILRE_MODEMRECV_PHASEC | Receiver: Data not received, modem error or timeout during page. @flag T30FAILRE_PPS_RNR_LOOP | Receiver: Timeout during ECM flow control after PPS. @flag T30FAILRE_EOR_RNR_LOOP | Receiver: Timeout during ECM flow control after EOR. @flag T30FAIL_NODEA_UNKNOWN | Sender: Garbage frames instead of DIS/DTC. @flag T30FAILS_POSTPAGE_UNKNOWN | Sender: Unknown response after page. @flag T30FAILS_POSTPAGE_OVER | Sender: We've sent a DCN (decided to end call). @flag T30FAILS_4PPR_ERRORS | Sender: Too many line errors in ECM mode. @flag T30FAILS_FTT_FALLBACK | Sender: Receiver doesn't like our training at all speeds. @flag T30FAILS_RTN_FALLBACK | Sender: Too many line errors in non-ECM mode even at 2400. @flag T30FAILS_4PPR_FALLBACK | Sender: Too many line errors in ECM mode even at 2400. @flag T30FAILS_MG3_NOFILE | Negotiation failed: Remote was G3 and there was no AWG3 format to send. @flag T30FAILS_NEGOT_ENCODING | Negotiation failed: Encoding mismatch. @flag T30FAILS_NEGOT_WIDTH | Negotiation failed: Paper Size Not Supported. @flag T30FAILS_NEGOT_LENGTH | Negotiation failed: Paper Size Not Supported. @flag T30FAILS_NEGOT_RES | Negotiation failed: Resolution Not Supported. @flag T30FAILS_EFX_BADFILE | Bad Linearized file was passed. @flag T30FAILS_MG3_BADFILE | Bad AWG3 file was passed in. @flag T30FAIL_ABORT | User abort @flag T30FAILS_SECURITY_NEGOT | Negotiation failed: Remote machine does not support security. If set, the error data contains the security version number supported by the recipient. @flag T30FAILS_NEGOT_MSGPROTOCOL | Negotiation failed: Remote machine does not support a compatible message protocol. If set, the error data contains the message protocol version number supported by the recipient. @flag T30FAILS_NEGOT_SECURITY | Negotiation failed: Remote machine does not support security. If set, the error data contains the security version number supported by the recipient. @flag T30FAILS_NEGOT_BINARYDATA | Negotiation failed: Remote machine does not support receiving binary data. @flag T30FAILS_NEGOT_COMPRESSION | Negotiation failed: Remote machine does not support a compatible version of compression. If set, the error data contains the compression version supported by the recipient. @flag T30FAILS_NEGOT_POLLING | Negotiation failed: Remote machine does not support polling. @flag T30FAILS_NEGOT_POLLBYNAME | Negotiation failed: Remote machine does not support poll by name. @flag T30FAILS_NEGOT_POLLBYRECIP | Negotiation failed: Remote machine does not support poll by recipient name. @flag T30FAILS_NEGOT_FILEPOLL | Negotiation failed: Remote machine does not support poll by filename.
@emem Error data values for T30_CALLFAIL | Error data must be zero for negotiation failures. For all other failures, the error data may be set to one of the following fields:
@flag T30_SENTNONE | Indicates that no pages were sent at all. @flag T30_SENTSOME | Indicates that some pages were successfuly transmitted and acknowledged by the remote machine. @flag T30_SENTALL | Indicates that all pages were successfuly sent. This should not really happen; it would generally indicate a successful transmission.
@emem Extended error codes for T30_FILE_ERROR | This error indicates a problem in one of the format files sent across the interface by the client. Different possible extended error codes are:
@flag AWG3_INVALID_LINHDR | The linearized header at the head of the AWG3 file was invalid. @flag AWG3_INVALID_AWG3HDR | An invalid AWG3 header was found in the file. @flag LIN_INVALIDHDR | A linearized file had an invalid header.
********/
typedef DWORD FAXERROR;
#define GetErrCode(fe) (LOBYTE(LOWORD(fe)))
#define GetExtErrCode(fe) (HIBYTE(LOWORD(fe)))
#define GetErrData(fe) (HIWORD(fe))
#define FormFaxError(ErrCode,ExtErrCode,ErrData) MAKELONG(MAKEWORD(ErrCode,ExtErrCode),ErrData)
// Error codes
#define T30_CALLFAIL 2
#define T30_DIALFAIL 4
#define T30_ANSWERFAIL 5
#define T30_NOMODEM 9
#define T30_FILE_ERROR 11
#define T30_MODEMERROR 15
#define T30_PORTBUSY 16
#define T30_MODEMDEAD 17
#define RES_NOMEMORY 64
#define RES_LOWDISK 65
#define USER_ABORT 66
#define RENDERING_FAILURE 67
#define RES_LOW_SERVER 68
#define CUSTOM_ERROR 254
#define GENERAL_FAILURE 255
// Extended Error codes
#define T30_UNKNOWN 0
// RENDERING_FAILURE
#define ATTACH_NOT_PRINTABLE 1
#define COVER_TEMPLATE_INVALID 2
// T30_FILE_ERROR
#define AWG3_INVALID_LINHDR 1
#define AWG3_INVALID_AWG3HDR 2
#define LIN_INVALIDHDR 3
// T30_DIALFAIL
#define NCUDIAL_ERROR 0
#define NCUDIAL_BUSY 2
#define NCUDIAL_NOANSWER 3
#define NCUDIAL_NODIALTONE 4
#define NCUDIAL_MODEMERROR 5
#define NCUDIAL_UNSUPPORTED_DIALCHAR 6
#define NCUDIAL_BADDIALSTRING 7
// Extended error code for T30_ANSWERFAIL
#define NCUANSWER_ERROR 0
#define NCUANSWER_NORING 8
#define NCUANSWER_MODEMERROR 5
// Extended error code for T30_PORTBUSY
#define PORTBUSY_SELFUSE 0
#define PORTBUSY_OTHERAPP 1
// Includes T30FAIL.H so that the values here (which should be a subset of
// those in T30FAIL.H) are kept in sync.
#include <t30fail.h>
// Extended error code for T30_CALLFAIL
#define T30FAILS_T1 6 // Send T1 timeout (No NSF/DIS Recvd)
#define T30FAILS_TCF_DCN 7 // Recvd DCN after TCF (weird...)
#define T30FAILS_3TCFS_NOREPLY 8 // No reply to 3 attempts at training (TCF)
#define T30FAILS_3TCFS_DISDTC 9 // Remote does not see our TCFs for some reason
#define T30FAILS_TCF_UNKNOWN 10 // Got garbage response to TCF
#define T30FAILS_SENDMODE_PHASEC 11 // Modem Error/Timeout at start of page
#define T30FAILS_MODEMSEND_PHASEC 12 // Modem Error/Timeout within page
#define T30FAILS_MODEMSEND_ENDPHASEC 14 // Modem Error/Timeout at end of page
#define T30FAILSE_SENDMODE_PHASEC 15 // Modem Error/Timeout at start of ECM page
#define T30FAILSE_MODEMSEND_PHASEC 17 // Modem Error/Timeout within ECM page
#define T30FAILSE_MODEMSEND_ENDPHASEC 19 // Modem Error/Timeout at end of ECM page
#define T30FAILSE_BADPPR 20 // Bad PPR recvd from Recvr (bug on recvr)
#define T30FAILS_3POSTPAGE_NOREPLY 21 // No response after page: Probably Recvr hungup during page transmit
#define T30FAILS_POSTPAGE_DCN 22 // Recvd DCN after page. (weird...)
#define T30FAILSE_3POSTPAGE_NOREPLY 23 // No response after page: Probably Recvr hungup during page transmit
#define T30FAILSE_POSTPAGE_DCN 24 // Recvd DCN after ECM page. (weird...)
#define T30FAILSE_POSTPAGE_UNKNOWN 25 // Recvd garbage after ECM page.
#define T30FAILSE_RR_T5 26 // Recvr was not ready for more than 60secs during ECM flow-control
#define T30FAILSE_RR_DCN 27 // Recvd DCN after RR during ECM flow-control(weird...)
#define T30FAILSE_RR_3xT4 28 // No response from Recvr during ECM flow-control
#define T30FAILSE_CTC_3xT4 29 // No response from Recvr after CTC (ECM baud-rate fallback)
#define T30FAILSE_CTC_UNKNOWN 30 // Garbage response from Recvr after CTC (ECM baud-rate fallback)
#define T30FAILR_PHASEB_DCN 35 // Recvr: Sender decided we're incompatible
#define T30FAILR_T1 36 // Recvr: Caller is not a fax machine or hung up
#define T30FAILR_UNKNOWN_DCN1 37 // Recvr: Recvd DCN when command was expected(1)
#define T30FAILR_T2 38 // Recvr: No command was recvd for 7 seconds
#define T30FAILR_UNKNOWN_UNKNOWN2 40 // Recvr: Recvd grabge when command was expected
#define T30FAILR_MODEMRECV_PHASEC 41 // Recvr: Page not received, modem error or timeout at start of page
#define T30FAILRE_MODEMRECV_PHASEC 42 // Recvr: Data not received, modem error or
#define T30FAILRE_PPS_RNR_LOOP 43 // Recvr: Timeout during ECM flow control after PPS (bug)
#define T30FAILRE_EOR_RNR_LOOP 44 // Recvr: Timeout during ECM flow control after EOR (bug)
#define T30FAIL_NODEA_UNKNOWN 45 // Sender: Garbage frames instead of DIS/DTC
#define T30FAILS_POSTPAGE_UNKNOWN 47 // Sender: Unknown response after page
#define T30FAILS_POSTPAGE_OVER 48 // Sender: We've sent a DCN (decided to end call)
#define T30FAILS_4PPR_ERRORS 50 // Sender: Too many line errors in ECM mode
#define T30FAILS_FTT_FALLBACK 51 // Sender: Recvr doesn't like our training at all speeds
#define T30FAILS_RTN_FALLBACK 52 // Sender: Too many line errors in non-ECM mode even at 2400
#define T30FAILS_4PPR_FALLBACK 53 // Sender: Too many line errors in ECM mode even at 2400
#define T30FAILS_MG3_NOFILE 63 // Negotiation failed: Remote in G3-only and no MG3 file *** Email Form Not Supported ***
#define T30FAILS_NEGOT_ENCODING 64 // Negotiation failed: Encoding mismatch
#define T30FAILS_NEGOT_WIDTH 66 // Negotiation failed: Send image too wide *** Paper Size Not Supported ***
#define T30FAILS_NEGOT_LENGTH 67 // Negotiation failed: Send image too long *** Paper Size Not Supported ***
#define T30FAILS_NEGOT_RES 68 // Negotiation failed: Resolution mismatch *** Resolution Not Supported ***
#define T30FAILS_EFX_BADFILE 69 // Bad EFX file
#define T30FAILS_MG3_BADFILE 71 // Bad MG3 file
#define T30FAIL_ABORT 87 // User abort
#define T30FAILS_SECURITY_NEGOT 110// Negotiation failed: Remote in G3-only and no MG3 file *** Email Form Not Supported ***
// New failure codes
#define T30FAILS_NEGOT_MSGPROTOCOL 128
#define T30FAILS_NEGOT_SECURITY 129
#define T30FAILS_NEGOT_BINARYDATA 130
#define T30FAILS_NEGOT_COMPRESSION 131
#define T30FAILS_NEGOT_COVERATTACH 132
#define T30FAILS_NEGOT_ADDRATTACH 133
#define T30FAILS_NEGOT_METAFILE 134
#define T30FAILS_NEGOT_POLLING 135
#define T30FAILS_NEGOT_POLLBYNAME 136
#define T30FAILS_NEGOT_POLLBYRECIP 137
#define T30FAILS_NEGOT_FILEPOLL 138
#define T30FAILS_NEGOT_RELAY 139
// Data word
// Data for T30_CALLFAIL - non negotiation errors
#define T30_UNKNOWN 0
#define T30_SENTALL 1
#define T30_SENTNONE 2
#define T30_SENTSOME 3
/********
@doc EXTERNAL SRVRDLL DATATYPES
@type NONE | FORMATTYPE | These are all the different kinds of formats that can be rendered for sending. It is typedef'd to a WORD.
@emem LMIFORMAT_G3 | A standard T4/T6 encoded file, with a linearizer header put on top of it. See <lq>AWG3 File Format<rq> for details.
@emem LMIFORMAT_LIN_IMAGE | A Linearized Microsoft At Work rendered image file.
@emem LMIFORMAT_LIN_BINARY | A linearized binary file.
********/
typedef WORD FORMATTYPE;
#define LMIFORMAT_G3 1
#define LMIFORMAT_LIN_IMAGE 2
#define LMIFORMAT_LIN_BINARY 3
#define LMIFORMAT_STORE_REF 4
/********
@doc EXTERNAL SRVRDLL DATATYPES
@type NONE | POLLTYPE | These are all the different kinds of poll requests that can be sent. It is typedef'd to a WORD.
@emem POLLREQ_ADDRESS | Polls for a document for a particular address. The Poll name is the address for which messages are desired, and a password can also be used. This feature is unimplemented and should not be used.
@emem POLLREQ_FILE | Polls for a directory or file on the recipient system. The poll name contains the file system path to be accessed, and a password can also be used. This feature is unimplemented and should not be used.
@emem POLLREQ_MSGNAME | Polls for a particular message name. The poll name contains the message name wanted, and a password can also be used.
@emem POLLREQ_G3 | Standard G3 compliant poll request. Polls for any file which has been stored at the recipient machine. Neither pollname or password are currently supported.
All poll types except POLLREQ G3 require both sender and receiver to be Microsoft Extended Fax Protocol (MEFP)-enabled.********/
typedef WORD POLLTYPE;
#define POLLREQ_ADDRESS 1
#define POLLREQ_FILE 2
#define POLLREQ_MSGNAME 3
#define POLLREQ_G3 4
/********
@doc EXTERNAL SRVRDLL DATATYPES
@type NONE |SCHEDTYPE | Kinds of possible scheduling. Typedef'd to a WORD.
@emem SCHED_ASAP | Schedule immediately.
@emem SCHED_BEFORE | Schedule immediately, and fail if the specified time is past.
@emem SCHED_AFTER | Schedule any time after the specified time is past.
@emem SCHED_CHEAPTIMES | Schedule only between cheap time periods as specified by the Provider's local settings. Only the time of day, as specified by the start time and stop time elements of the <t SENDJOBTIME> structure, have any meaning. In fact, the day, date, month, and year are not guaranteed to be filled in.
********/
typedef WORD SCHEDTYPE;
#define SCHED_ASAP 1
#define SCHED_BEFORE 2
#define SCHED_AFTER 3
#define SCHED_CHEAPTIMES 4
/********
@doc EXTERNAL SRVRDLL
@type NONE | PROVIDERSTATE | A DWORD which describes the state of the Provider. Can consist of a combination of the following flags:
@emem PROVIDER_OK | Standard OK state - no action is required.
@emem PROVIDER_OFFLINE | Provider is offline - client should do the same. Offline indicates that the Provider is no longer actively able to send or receive jobs.
@emem PROVIDER_NO_RESPONSE | No response from Provider. Client should go offline.
@emem PROVIDER_BADERROR | Bad error at Provider. Client should go offline.
@emem PROVIDER_RECEIVES_WAITING | Client should poll for receives.
@emem PROVIDER_SENDS_COMPLETED | Client should poll for completed send status.********/
typedef DWORD PROVIDERSTATE;
#define PROVIDER_OK 0x0000
#define PROVIDER_OFFLINE 0x0001
#define PROVIDER_NO_RESPONSE 0x0002
#define PROVIDER_BADERROR 0x0004
#define PROVIDER_RECEIVES_WAITING 0x0008
#define PROVIDER_SENDS_COMPLETED 0x0010
/********
@doc EXTERNAL SRVRDLL
@type NONE | JOBSTATE | A WORD identifying the state of a fax job.
@emem jstNewMsg | Just received from mail spooler. @emem jstProcessingRecipients | Deciding what needs to be sent. @emem jstRendering | Being rendered (Used internally by client). @emem jstReadyToSend | Waiting to be schedulable. @emem jstSchedulable | Ready to be transmitted. @emem jstTransmitting | Being transmitted. @emem jstWaitingForServer | Given to network Provider (Used internally by client). @emem jstWaitingForClient | Waiting for client to take back.
********/
typedef WORD JOBSTATE;
#define jstNewMsg 0
#define jstProcessingRecipients 1
#define jstRendering 2
#define jstReadyToSend 3
#define jstSchedulable 4
#define jstTransmitting 5
#define jstAllDone 6
#define jstWaitingForServer 7
#define jstWaitingForClient 8
/****
@doc EXTERNAL SRVRDLL OVERVIEW
@topic Data Structures | Most structures defined here are in a packed format; that is, there are no pointers to external objects. This is done so they can be easily stored in a file or transmitted as a block across the network.
Most structures have two size fields. The HeaderSize field gives the defined size of the structure, which is used for versioning the structure. If the structure is expanded in the future, this size can be used to maintain backward compatibility. The TotalSize field indicates the size of the whole structure along with all its data.
All strings and other variable-length data items such as structures are represented in the structure by an offset from the beginning of the structure. The actual data for these elements begins at that offset. The length of the data is indicated by the item itself. If it is a string, it is null-terminated. If it is another structure, the size fields will convey this information.
All files referenced in the structures are created in the spool directory specified in LMI_InitProvider.
****/
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMICUSTOMOPTION | Overlay of LMI Custom Option data. For MAPI 1.0, Win32 implementations, this structure is found in the MAPI message property PR_FAX_LMI_CUSTOM_OPTION (property tag value 0x4513.)
@field DWORD | dwTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wNumRecords | Number of records in the Custom Option data. This is also eqaul to the size of the dwOffsetTable.
@field DWORD | dwOffsetTable[] | Table of offsets to the records of type LMICUSTOMOPTIONRECORD. All offsets are from the top of the LMICUSTOMOPTION structure. The records should directly follow this array.********/
#ifndef RC_INVOKED
#pragma warning (disable: 4200)
#endif
typedef struct _LMICUSTOMOPTION { DWORD dwTotalSize; WORD wHeaderSize; WORD wNumRecords; DWORD dwOffsetTable[0];} LMICUSTOMOPTION, FAR *LPLMICUSTOMOPTION;
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMICUSTOMOPTIONRECORD | Record overlay of LMI Custom Option data.
@field DWORD | dwTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wPad | Keep DWORD alignment.
@field CHAR | szUniqueName[32] | Unique name specified by provider. This is used for identification of the provider's record within the LMICUSTOMOPTION and should contain some encoding of the provider developer company. eg, "Microsoft:Netfax". The string MUST be null terminated so that providers may do strcmp's to detect their own section.
@field BYTE | lpData[] | Here's the data.
********/typedef struct _LMICUSTOMOPTIONRECORD { DWORD dwTotalSize; WORD wHeaderSize; WORD wPad; CHAR szUniqueName[32]; BYTE lpData[];} LMICUSTOMOPTIONRECORD, FAR *LPLMICUSTOMOPTIONRECORD;
#ifndef RC_INVOKED
#pragma warning (default: 4200)
#endif
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMIFORMAT | Describes a format.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field FAXERROR | feError | Indicates if there were any errors while trying to generate this format. If this field is not set to zero, the format file pointed to by the szFileName field may be invalid and should not be used. This error value might need to be propagated into the <e LMIRECIPSTATUS.feError> field for recipients which fail as a result of this format not being ready.
@field CHAR | szFileName[16] | The filename containing the actual format data.
@field FORMATTYPE | ftFormatType | Which format this represents.
@field WORD | wPad | Keep DWORD alignment.********/typedef struct _LMIFORMAT { WORD wHeaderSize; WORD wTotalSize; FAXERROR feError; CHAR szFileName[16]; FORMATTYPE ftFormatType; WORD wPad;} LMIFORMAT, FAR *LPLMIFORMAT;#define MAXFORMATSIZE (sizeof(LMIFORMAT))
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMIPOLLREQUEST | Describes a poll request message.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wszRecipName | The name of this recipient. This is present only if this recipient is from a Provider implemented address book. In this case <e LMIRECIPIENT.wszAddressOffset> is zero.
@field WORD | wszAddressOffset | The Microsoft At Work address for this recipient. Not present for recipients implemented in the Provider's address book. See <t Microsoft At Work Address> for details.
@field DWORD | dwPollContext | The provider should report this value in the dwPollContext field of the LMIRECVSTATUS structure for all the messages received as a result of this poll request. This enables the client to associate the received messages (reported to the client via LMI_ReportReceives) with a particular poll request. A value of zero is valid, but not useful, because all non-polled receives reported by LMI_ReportReceives have zero as the dwPollContext in their LMIRECVSTATUS structure.
@field POLLTYPE | ptPollType | What type of a poll request this is.
@field WORD | wszPollNameOffset | The name to be sent along with the poll request. The specific semantic meaning depends on the poll type.
@field WORD | wszPollPasswordOffset | Offset to the password to be sent along with the poll request.
@field WORD | wPad | Keep DWORD alignment.********/typedef struct _LMIPOLLREQUEST { WORD wHeaderSize; WORD wTotalSize; WORD wszRecipName; WORD wszAddressOffset; DWORD dwPollContext; POLLTYPE ptPollType; WORD wszPollNameOffset; WORD wszPollPasswordOffset; WORD wPad;} LMIPOLLREQUEST, FAR *LPLMIPOLLREQUEST;
/********
@doc EXTERNAL SRVRDLL
@types LMIQUEUEDATA | Represents queue information about a single job.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field DWORD | dwUniqueID | This can be used by the Provider to pass in a context. Along with <e LMIQUEUEDATA.dwUniqueID2> and <e LMIQUEUEDATA.wszSenderMachineNameOffset> this must uniquely identify this job.
@field DWORD | dwUniqueID2 | See <e LMIQUEUEDATA.dwUniqueID>.
@field WORD | wszSenderMachineNameOffset | Points to a string which identifies the machine originating this job. Used for display in the queue. Also uniquely identifies the job along with the unique ID's. This should be the same as the string pointed to by the <e LMISENDJOB.wszSenderMachineNameOffset> field in <t LMISENDJOB>.
@field WORD | wszSubjectOffset | Offset to the subject of this message. This should be the same as the string pointed to by the <e LMISENDJOB.wszSubjectOffset> field in <t LMISENDJOB>.
@field DWORD | dwSize | This should be the same as what was passed in as <e LMISENDJOB.dwTotalFileSize> in <t LMISENDJOB>.
@field WORD | wNumRecipients | This should be the same as what was passed in as <e LMISENDJOB.wNumRecipients> in <t LMISENDJOB>.
@field JOBSTATE | jstState | Current overall status for this job.
@field WORD | wNumRecipDone | Number of recipients for which transmission has been completed, either succesfully or unsuccesfully.
@field WORD | wtmSendTimeOffset | Current scheduling state for this job. Offset to a <t SENDJOBTIME> structure.
@field WORD | wrgbCustomStatusOffset | Offset to Provider defined custom status information. This is passed to the <f LMI_DisplayCustomStatus> function when the user asks to see detailed status for this job.
@field WORD | wCustomDataSize | Size of the custom data pointed to by the <e LMISENDJOB.wrgbCustomStatusOffset> field.
********/
typedef struct _LMIQUEUEDATA { WORD wHeaderSize; WORD wTotalSize; DWORD dwUniqueID; DWORD dwUniqueID2; WORD wszSenderMachineNameOffset; WORD wszSubjectOffset; DWORD dwSize; WORD wNumRecipients; JOBSTATE jstState; WORD wNumRecipDone; WORD wtmSendTimeOffset; WORD wrgbCustomStatusOffset; WORD wCustomDataSize;} LMIQUEUEDATA, NEAR *NPLMIQUEUEDATA, FAR *LPLMIQUEUEDATA;
/********
@doc EXTERNAL SRVRDLL
@types LMIQUEUEFILEHEADER | A queue file consists of this header followed by the queue data.
@field DWORD | dwSig | This must be set to SIG_QUEUEFILE.
@field DWORD | dwSize | Must be set to the total file size.
@field DWORD | dwNumEntries | Number of queue entries in the file. The header is followed by this many <t LMIQUEUEDATA> structures.********/
#define SIG_QUEUEFILE 0x56873
typedef struct _LMIQUEUEFILEHEADER { DWORD dwSig; // Should always be NQFH
DWORD dwSize; // Total file size
DWORD dwNumEntries; // Num of entries in the file
} LMIQUEUEFILEHEADER;
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMIRECIPIENT | Describes a recipient.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wszRecipName | The name of this recipient. This is present only if this recipient is from a Provider implemented address book. In this case <e LMIRECIPIENT.wszAddressOffset> is zero and <e LMIRECIPIENT.szCoverFile> is a reference to a template on the Provider.
@field WORD | wszAddressOffset | The Microsoft At Work address for this recipient. Not present for recipients implemented in the Provider's address book. See <lq>Microsoft At Work Address<rq> for details.
@field CHAR | szCoverFile[16] | The filename containing the cover page data if any for this recipient. This could be a reference to a previously uploaded template if this is a recipient from the Provider's address book. If the first word of this character array is 0 but the second word is non-null, then the second word represent a WORD offset into the LMIRECIPIENT structure where the fully qualified path may be found.
@field CHAR | szEncryptFile[16] | If one of the linearized formats pointed to by this recipient structure is a public key encrypted message being sent to multiple recipients, then this field contains the filename for a linearized format of the message encrypted with this recipients public key. This field will not be valid under any other circumstance.
@field WORD | wG3FormatIndex | If non-zero, this specifies a 1-based index into the format structure array. It implies that this recipient can accept this version of the G3 format. Note that there may still be some run time conversions necessary on this format at the time of sending. For instance, the format may be MMR, whereas on calling it may be discovered that the recipient only accepts MH. In this case, the Provider is responsible for converting this on the fly.
@field WORD | wLinImageFormatIndex | Index into the format array. Pointer to a linearized image format which can be sent to this recipient.
@field WORD | wLinBinaryFormatIndex | Index into the format array. Pointer to a linearized binary format which can be sent to this recipient.
@field WORD | wPad | Keep DWORD alignment. ********/
typedef struct _LMIRECIPIENT { WORD wHeaderSize; WORD wTotalSize; WORD wszRecipName; WORD wszAddressOffset; CHAR szCoverFile[16]; CHAR szEncryptFile[16]; WORD wG3FormatIndex; WORD wLinImageFormatIndex; WORD wLinBinaryFormatIndex; WORD wPad;} LMIRECIPIENT, FAR *LPLMIRECIPIENT;#define MAXRECIPIENTSIZE (sizeof(LMIRECIPIENT) + MAX_ADDRESS_LENGTH)
/*******
@doc EXTERNAL SRVRDLL DATATYPES
@types LMIRECIPSTATUS | Used to convey information for the final status of the completed send for a recipient.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wrcCapsOffset | An offset to a <t MACHINECAPS> structure containing the updated capabilites for this recipient.
@field FORMATTYPE | ftSentFormat | The format type which was finally sent to this recipient.
@field FAXERROR | feError | The final status for this recipient.
@field SYSTEMTIME | dtTransmitTime | The time at which the fax was last attempted to be sent.
@field DWORD | dwConnectTime | Connect time for the transmission in seconds.
*******/
typedef struct _LMIRECIPSTATUS { WORD wHeaderSize; WORD wTotalSize; WORD wrcCapsOffset; FORMATTYPE ftSentFormat; FAXERROR feError; DWORD dwConnectTime; SYSTEMTIME dtTransmitTime;} LMIRECIPSTATUS, FAR *LPLMIRECIPSTATUS;
/********
@doc EXTERNAL SRVRDLL
@types LMIRECVSTATUS | Gives the status for a received fax.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field FAXERROR | feError | The final status for this receive.
@field SYSTEMTIME | dtRecvTime | Should be filled with the time at which the fax was received.
@field DWORD | dwConnectTime | The connect time for the transmission in seconds.
@field DWORD | dwPollContext | If this receive was actually in response to a poll request, then this will be set to the same value which was passed in in the <t LMIPOLLREQUEST> structure sent along with the poll request.
@field ATOM | atFile | The filename containing the received fax file. This file should be in the spool directory agreed upon in the <f LMI_InitLogicalModem> call.
@field WORD | wPad | Keep DWORD alignment.
********/
typedef struct _LMIRECVSTATUS { WORD wHeaderSize; WORD wTotalSize; FAXERROR feError; SYSTEMTIME dtRecvTime; DWORD dwConnectTime; DWORD dwPollContext; ATOM atFile; WORD wPad;} LMIRECVSTATUS, FAR *LPLMIRECVSTATUS;
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMISENDJOB | Describes a new fax job. A fax job specifies a send to one or more recipients.
@field DWORD | dwTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | fUnicode | Indicates whether the string pointed to by <e LMISENDJOB.wszSenderMachineNameOffset> is a Unicode string or not. @field WORD | wszSenderMachineNameOffset | Points to a string which identifies the machine originating this job. Used for display in the queue. Also uniquely identifies the job along with the unique ID's.
@field WORD | wszSubjectOffset | Subject of the message. Used for display purposes in the queue.
@field DWORD | dwUniqueID | Used by the client to uniquely identify this send fax job along with <e LMISENDJOB.dwUniqueID2>.
@field DWORD | dwUniqueID2 | Used along with <e LMISENDJOB.dwUniqueID> to identify this job.
@field DWORD | dwBillingCode | Billing code for this job. This is to allow Providers to keep accurate billing logs.
@field DWORD | dwTotalFileSize | An approximation for the total size of the data required to be transmitted for this message for all recipients combined. Meant for display purposes in the queue to allow some idea of how long the job is likely to take.
@field WORD | wtmSendTimeOffset | Offset to a <t SENDJOBTIME> scheduling structure.
@field WORD | wprPollRequestOffset | Offset to a poll request structure. See <t LMIPOLLREQUEST> for details. If this offset is set, there are no recipient or format structures associated with this job. In other words, the rgwStructOffsets field will be zero.
@field WORD | wrgbCustomOptionOffset | Offset to custom message options set for this message. This is an offset to data returned by a call to <f LMI_SetCustomMsgOptions>. The first DWORD of the data indicates the size of the data.
@field WORD | wNumRecipients | The number of recipients for this job.
@field WORD | wNumFormats | The number of rendered formats associated with this job.
@field WORD | wPad | Keep DWORD alignment. @field DWORD | rgdwStructOffsets[] | Array of size <e LMISENDJOB.wNumFormats> and <e LMISENDJOB.wNumRecipients> offsets to format and recipient structures. The <t LMISENDJOB> structure is followed by all these structures. The <t LMIFORMAT> structures come first.
********/
#ifndef RC_INVOKED
#pragma warning (disable: 4200)
#endif
// The basic fax job structure for any send
typedef struct _LMISENDJOB { DWORD dwTotalSize; WORD wHeaderSize; WORD fUnicode; WORD wszSenderMachineNameOffset; WORD wszSubjectOffset; DWORD dwUniqueID; DWORD dwUniqueID2; DWORD dwBillingCode; DWORD dwTotalFileSize; WORD wtmSendTimeOffset; WORD wprPollRequestOffset; WORD wrgbCustomOptOffset; WORD wNumRecipients; WORD wNumFormats; WORD wPad; DWORD rgdwStructOffsets[];} LMISENDJOB, FAR *LPLMISENDJOB;
#ifndef RC_INVOKED
#pragma warning (default: 4200)
#endif
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types LMISENDSTATUS | Conveys back status information at the end of a send job.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field FAXERROR | feJobError | Indicates any global error which caused all recipients to fail, such as cancellation by the user, or an out of memory situation. This should only be set if none of the recipients for this message were succesfully contacted.
@field DWORD | dwUniqueID | Used by the client to uniquely identify this send fax job along with <e LMISENDSTATUS.dwUniqueID2>. This should be the same as the one passed in the <t LMISENDJOB> structure.
@field DWORD | dwUniqueID2 | Used along with <e LMISENDSTATUS.dwUniqueID> to identify this job. Should be the same as the one passed in the <t LMISENDJOB> structure.
@field WORD | fUnicode | Indicates that the <e LMISENDSTATUS.szSenderMachineName> field contains a unicode string.
@field WORD | wPad | Keep DWORD alignment. @field CHAR | szSenderMachineName[MAX_SERVERNAME_SIZE * 2] | Points to a string which identifies the machine originating this job. This should be the same as the one passed in the <t LMISENDJOB> structure.
@field LMIRECIPSTATUS | rgnrsRecipStatus[] | An array of recipient status structures, one for each recipient of the message. These structures are not required if <e LMISENDSTATUS.feJobError> is set. If present, the order of recipients in this array must be the same as the order in which they were submitted in the <t LMISENDJOB> structure.
********/#ifndef RC_INVOKED
#pragma warning (disable: 4200)
#endif
typedef struct _LMISENDSTATUS { WORD wHeaderSize; WORD wTotalSize; FAXERROR feJobError; DWORD dwUniqueID; DWORD dwUniqueID2; WORD fUnicode; WORD wPad; CHAR szSenderMachineName[MAX_SERVERNAME_SIZE*2]; LMIRECIPSTATUS rgnrsRecipStatus[];} LMISENDSTATUS, FAR *LPLMISENDSTATUS;
#ifndef RC_INVOKED
#pragma warning (default: 4200)
#endif
/*******
@doc EXTERNAL SRVRDLL DATATYPES
@types MACHINECAPS | This structure describes the capabilites for a fax machine. It is used to return updated capabilities for any fax machine contacted and allows intelligent preprocessing the next time a fax is sent to the same number.
@field WORD | wHeaderSize | Gives the size for the fixed size header portion of the structure.
@field WORD | wTotalSize | Total number of BYTES occupied by the structure along with its concomitant variable sized data.
@field WORD | wbDISCapsOffset | Offset to a DIS frame containing capabilities of the machine. The format of the frame is defined by the <t FR> structure. @field WORD | wbNSFCapsOffset | Offset to a sequence of encrypted Microsoft At Work NSF frames containing At Work capabilities for the machine. The format of each frame is defined by the <t FR> structure. A frame with a null type and 0 length terminates the sequence. Valid for any Microsoft At Work enabled Provider.*******/
typedef struct { WORD wHeaderSize; WORD wTotalSize; WORD wbDISCapsOffset; WORD wbNSFCapsOffset;} MACHINECAPS, FAR *LPMACHINECAPS;
/********
@doc EXTERNAL SRVRDLL INITIALIZATION
@types MODEMCAPS | Specifies all the capabilities for a logical modem. When specified by the client (for example in LMI_ExchangeCaps), the structure represents the capabilities which are supported by the client.
@field WORD | wHeaderSize | Size of this structure.
@field WORD | wTotalSize | Total size with concomitant data.
@field DWORD | dwGenCaps | Lists general capabilities. The following flags can be set: @flag OWN_ADDRESS_BOOK | Indicates that the modem can maintain it's own address book. @flag ADVANCED_STORE | Indicates that the modem can manage its own store and upload messages to it. @flag COVER_PAGE_RENDERER | Indicates that the modem can render Microsoft At Work cover page templates. @flag REAL_TIME_STATUS | Indicates that real time status updates for the current job are supported. @flag MULTIPLE_RECIPIENTS | Indicatest that messages can be sent to multiple recipients. @flag PER_RECIP_COVER | Indicates that per recipient cover pages are supported. If this is not set, the <e LMIRECIPIENT.szCoverFile> field of the <t LMIRECIPIENT> structure will not be used. @flag PER_RECIP_ENCRYPTION | Indicates that key encrypted sends to multiple recipients are supported. If this is not set, the <e LMIRECIPIENT.szEncryptFile> field of the <t LMIRECIPIENT> structure will never be used. @flag CUSTOM_MSG_OPTIONS | Indicates that the modem supports setting of custom per message options. If not set, the function <f LMI_SetCustomMsgOptions> need not be implemented. @flag POLL_REQUEST | Indicates that poll requests using T30 fields is supported. If not, the <t LMIPOLLREQUEST> structure should not be used. @flag ABOVE64K_STRUCTURES | Indicates that the <t LMISENDJOB> structure can have a total size > 64K. For x86 based systems, this allows far pointers to be used instead of huge pointers.
@flag ALLOW_SHARING | Indicates that this device can be shared.
@flag PRECIOUS_RESOURCE | Indicates that this device is a precious resource on the local machine which may need to be shared with other MAPI providers. For example, a modem which may be used by another provider to access dial-up services for mail delivery. The MAPI transport will use this flag to determine if it should support MAPI's FlushQueues semantics.
@field DWORD | dwSchedCaps | Lists scheduling related capabilities. The following flags are defined:
@flag SUPPORT_QUEUEING | Indicates whether the modem can queue up multiple jobs at a time, or can only process them one at a time. @flag ALLOW_SCHED_ASAP | Indicates that jobs can be scheduled as ASAP. @flag ALLOW_SCHED_AFTER | Indicates that jobs can be scheduled as SCHED_AFTER. @flag ALLOW_SCHED_BEFORE | Indicates that jobs can be scheduled as SCHED_BEFORE. @flag ALLOW_SCHED_CHEAPTIMES | Indicates that jobs can be scheduled for cheap times. This capability assumes that the cheap times are defined by the Provider. @flag ALLOW_CLIENT_CHEAPTIMES | Allows the client to set the cheap times independently for each job. @flag USE_UTC_TIMES | Indicates that the times indicated in the <t SENDJOBTIME> structure are in UTC and not in local time. If any of the client or the Provider do not support this capability the times will revert to being local times.
@field WORD | wmcOffset | Offset to <t MACHINECAPS> structure which should be filled in with all the capabilities which this modem has: essentially what it would send back to a caller in the DIS and NSF frames.
@field WORD | wMaxRetries | Indicates the maximum number of retries permitted for a send. The client should not set the <e SENDJOBTIME.wNumRetries> field of the <t SENDJOBTIME> structure to a number greater than this.
@field WORD | wMinTimeBetweenRetries | Specifies the minimum amount of time that can be specified between retries. The client should never set the <e SENDJOBTIME.wMinBetweenRetries> field of the <t SENDJOBTIME> structure to anything less than this.
@field WORD | wPad | Keep DWORD alignment. ********/
typedef struct { WORD wHeaderSize; WORD wTotalSize; DWORD dwGenCaps; DWORD dwSchedCaps; WORD wmcOffset; WORD wMaxRetries; WORD wMinTimeBetweenRetries; WORD wPad;} MODEMCAPS, FAR *LPMODEMCAPS;
// General caps
#define OWN_ADDRESS_BOOK 0x0001
#define ADVANCED_STORE 0x0002
#define COVER_PAGE_RENDERER 0x0004
#define REAL_TIME_STATUS 0x0008
#define MULTIPLE_RECIPIENTS 0x0010
#define PER_RECIP_COVER 0x0020
#define PER_RECIP_ENCRYPTION 0x0040
#define CUSTOM_MSG_OPTIONS 0x0080
#define POLL_REQUEST 0x0100
#define ABOVE64K_STRUCTURES 0x0200
#define ALLOW_SHARING 0x0400
#define ALLOW_RESHARING 0x0800
#define PRECIOUS_RESOURCE 0x1000
// Sched caps
#define SUPPORT_QUEUEING 0x0001
#define ALLOW_SCHED_ASAP 0x0002
#define ALLOW_SCHED_AFTER 0x0004
#define ALLOW_SCHED_BEFORE 0x0008
#define ALLOW_SCHED_CHEAPTIMES 0x0010
#define ALLOW_CLIENT_CHEAPTIMES 0x0020
#define USE_UTC_TIMES 0x0040
/********
@doc EXTERNAL SRVRDLL DATATYPES
@types SENDJOBTIME | Contains all the scheduling informations for a job.
@field WORD | wHeaderSize | Size of this structure.
@field WORD | wNumRetries | Maximum number of retries for busy numbers.
@field WORD | wMinBetweenRetries | Minutes to be allowed to elapse between successive retries.
@field SCHEDTYPE | stSchedType | Type of scheduling required for this job.
@field SYSTEMTIME | dtStartTime | Time after which job is schedulable.
@field SYSTEMTIME | dtStopTime | Time after which job is not schedulable.
********/
typedef struct { WORD wHeaderSize; WORD wNumRetries; WORD wMinBetweenRetries; SCHEDTYPE stSchedType; SYSTEMTIME dtStopTime; SYSTEMTIME dtStartTime;} SENDJOBTIME, FAR *LPSENDJOBTIME;
/****
@doc EXTERNAL SRVRDLL
@topic The Logical Modem Interface | The following section details the functions that make up the Logical Modem Interface.
****/
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_AbortSendJob | Aborts the specified send job from the Provider's queue.
@parm DWORD | dwLogicalModem | The logical modem from whose queue the job is to be cancelled.
@parm LPTSTR | lpszSenderMachineName | String identifying the sender machine name. This parameter, along with the <p dwUniqueID> and <p dwUniqueID2> uniquely identify this job for the Provider. These all must be same as the values passed in the <t LMISENDJOB> structure passed into <f LMI_SendFax>.
@parm DWORD | dwUniqueID | See <p lpszSenderMachineName>.
@parm DWORD | dwUniqueID2 | See <p lpszSenderMachineName>.
@rdesc LMI_SUCCESS on success.
@comm The abort can be performed asynchronously by the Provider. Return from this function does not imply any guarantees as to the time within which the job will be aborted. The provider reports the final state of the job via LMI_ReportSend. The client will ensure that this function is only called to abort jobs which were initiated on its machine.
********/
LMI_RETURN FAR PASCAL LMI_AbortSendJob(DWORD dwLogicalModem, LPTSTR lpszSenderMachineName, DWORD dwUniqueID, DWORD dwUniqueID2);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_AbortSendJob)(DWORD dwLogicalModem, LPTSTR lpszSenderMachineName, DWORD dwUniqueID, DWORD dwUniqueID2);
/********
@doc EXTERNAL SRVRDLL INSTALLATION
@func LMI_RETURN | LMI_AddModem | Called to add a new logical modem to the list of current modems.
@parm HWND | hDlg | The window handle of the parent dialog box. This should be used as the parent for any new dialog boxes which are displayed.
@parm LPTSTR | modembuf | Pointer to the buffer where the call should return a zero-terminated string uniquely identifying the logical modem the user selected. <p buflen> gives the maximum length this string can be (including the zero termination).
@parm WORD | buflen | Length of the buffer pointed to by <p modembuf>. This is guaranteed to be at least 64 BYTES. @rdesc The dialog should handle notifying the user of errors if it can put its first dialog up.
@comm This function is called to put up a dialog box allowing the user to select a logical modem to add to the list of current modems. The function should return a displayable string that is shown in the user list. This is also the string which is passed in to identify the modem in the <f LMI_InitLogicalModem> call.
********/
LMI_RETURN FAR PASCAL LMI_AddModem(HWND hDlg, LPTSTR modembuf, WORD buflen);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_AddModem)(HWND hDlg, LPTSTR modembuf, WORD buflen);
/********
@doc EXTERNAL SRVRDLL
@api PROVIDERSTATE | LMI_CheckProvider | Pings the Provider to see if it is alive.
@rdesc Returns state of Provider. This return value can be used to make the client poll the Provider for events.
@comm This can be called periodically by the client and should be implemented in as efficient a manner as possible. It can be used by the client to decide whether it needs to go offline among other things.
It is not mandatory for this to return a completely accurate state of the Provider. If finding this information is very expensive, the Provider can, at its discretion, do this less frequently, and return the stale state in the intermediate polls.
@parm DWORD | dwLogicalModem | Handle representing the logical modem to be checked.
@parm LPATOM | lpatError | If there was an error and the Provider is having problems, a global atom containing a descriptive string for this error can be returned here. Any string returned will be displayed to the user at the client's discretion. The atom will be freed by the client.********/
PROVIDERSTATE FAR PASCAL LMI_CheckProvider(DWORD dwLogicalModem, LPATOM lpatError);typedef PROVIDERSTATE (FAR PASCAL FAR *LPLMI_CheckProvider) (DWORD dwLogicalModem, LPATOM lpatError);
/*******
@doc EXTERNAL SRVRDLL CONFIGURATION
@api LMI_RETURN | LMI_ConfigureModem | Called to let the user configure a logical modem.
@parm HWND | hDlg | The window handle of the parent dialog box. This should be used as the parent for any new dialog boxes which are displayed.
@parm LPTSTR | lpszModem | Pointer to string representing the logical modem to be configured. This is the same string which was returned by <f LMI_AddModem>.
@rdesc Returns LMI_SUCCESS if successful.
*******/
LMI_RETURN FAR PASCAL LMI_ConfigureModem(HWND hDlg, LPTSTR lpszModem);
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_DeinitLogicalModem | Deinitializes the specified logical modem.
@parm DWORD | dwLogicalModem | Handle representing the logical modem to be deinitialized.
@rdesc LMI_SUCCESS if successful.********/
LMI_RETURN FAR PASCAL LMI_DeinitLogicalModem (DWORD dwLogicalModem);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_DeinitLogicalModem) (DWORD dwLogicalModem);
/********
@doc EXTERNAL SRVRDLL @api LMI_RETURN | LMI_DeinitProvider| Deinitializes the LMI provider.
@rdesc LMI_SUCCESS if successful.********/
LMI_RETURN FAR PASCAL LMI_DeinitProvider (VOID);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_DeinitProvider) (VOID);
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_DisplayCustomStatus | Displays extended status information for a job.
@parm HWND | hwndParent | Parent window handle which should be used for displaying any dialogs.
@parm LPBYTE | lpbCustomData | Pointer to the start of the custom data associated with this job.
@parm WORD | wCustomDataSize | Size in BYTES of the data pointed to by <p lpbCustomData>.*********/ LMI_RETURN FAR PASCAL LMI_DisplayCustomStatus(HWND hwndParent, LPBYTE lpbCustomData, WORD wCustomDataSize);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_DisplayCustomStatus)(HWND hwndParent, LPBYTE lpbCustomData, WORD wCustomDataSize);/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_ExchangeCaps | Allows the client and the Provider to exchangde <t MODEMCAPS> structures without having to initialize the Provider or a logical modem. This is one of two calls which can be made without an initialized modem.
@parm LPTSTR | lpszLogicalModem | Pointer to string identifying logical modem the caps belong to.
@parm LPMODEMCAPS | lpmcClient | Pointer to a <t MODEMCAPS> structure that describes the capabilities of the client. This should be used by the Provider to decide which formats can be understood by the client. For instance, if the client only understands MH, then the Provider would need to convert any received faxes into MH before reporting them in <f LMI_ReportReceives>. Similarly, this can indicate to the Provider whether or not features such as uploading of messages and Provider address books are supported by this particular client implementation. If this pointer is null, it should be ignored.
@parm LPMODEMCAPS | lpmcProvider | Points to a <t MODEMCAPS> structure which should be filled in with the capabilities of this Provider. The size of the memory pointed to by this structure is filled in the wTotalSize field of the structure. If this pointer is null, no capabilities need to be returned.
@rdesc LMI_SUCCESS on success.
@comm It is perfectly valid for a Provider to return LMIERR_NOT_SUPPORTED for this call. A Provider may need to do this if it cannot determine the modem capabilities without actually initializing the modem.********/
LMI_RETURN FAR PASCAL LMI_ExchangeCaps (LPTSTR lpszLogicalModem, LPMODEMCAPS lpmcClient, LPMODEMCAPS lpmcProvider);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_ExchangeCaps)(LPTSTR lpszLogicalModem, LPMODEMCAPS lpmcClient, LPMODEMCAPS lpmcProvider);
/********
@doc EXTERNAL SRVRDLL
@api DWORD | LMI_GetQueueFile | Retrieves the name of the queue file for a logical modem from the Provider.
@parm DWORD | dwLogicalModem | A handle to the logical modem for which the queue is desired. If a valid handle is supplied, the <p lpszLogicalModemName> parameter should be NULL.
@parm LPTSTR | lpszLogicalModemName | A string identifying the logical modem for which the user wants to see the queue, if this modem has not been initialized previously. This is one of two APIs which can be called without initializing a modem. If this parameter is used, the <p dwLogicalModem> parameter should be ignored.
@parm LPATOM | lpatFileName | The function should return a global atom containing a fully qualified path name to the queue file. This does not have to be on the local disk. The pathname should be such that it can be passed to a Windows CreateFile call.
@parm WORD | wFlags | Can be any combination of the following flags:
@flag NGQ_USER_REQUEST | Implies that the queue update request is being made due to an explicit user refresh request. Transports which have expensive updates can use this to divide the normal refresh rate while making sure that explicit requeusts do not get ignored.
@rdesc LMI_SUCCESS on success.
@comm Ideally the client should be able to retrieve the queue for any logical modem supported by this Provider, not necessarily the one which is currently initialized. This allows the client to choose a new modem intelligently if needed.
********/
#define NGQ_USER_REQUEST 0x0001
LMI_RETURN FAR PASCAL LMI_GetQueueFile (DWORD dwLogicalModem, LPTSTR lpszLogicalModemName, LPATOM lpatFileName, WORD wFlags);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_GetQueueFile)(DWORD dwLogicalModem, LPTSTR lpszLogicalModemName, LPATOM lpatFileName, WORD wFlags);
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_InitLogicalModem | Used to initialize a particular logical modem.
@parm LPTSTR | lpszLogicalModem | String identifying the logical modem to be initialized.
@parm LPDWORD | lpdwLogicalModem | A DWORD handle representing this logical modem should be returned in this pointer if the function is successful. The handle is valid until the client calls LMI_DeinitLogicalModem with this handle.
@parm LPATOM | lpatClientName | A global atom containing an ASCII name identifying this client must be returned here. This string is used in the queue displays to identify jobs from this client on the Provider. It is used by clients to restrict the jobs which can be cancelled or rescheduled from their machines, so it should be unique enough to prevent security holes. All string comparisons using this name should be case-insensitive because case is not necessarily preserved when using atoms.
@parm LPATOM | lpatPhone | A global atom containing the canonical phone number for this logical modem. This is used to construct the client's Microsoft At Work Address, and is the number put into the FROM field of any messages sent. This needs to be filled in if a non-null pointer is passed in.
@parm LPMODEMCAPS | lpmc | Points to a <t MODEMCAPS> structure which should be filled in with the capabilities of this logical modem. The size of the memory pointed to by this structure is filled in the wTotalSize field of the structure. If this pointer is null, no capabilities need to be returned.
@rdesc LMI_SUCCESS if successful. A handle to the logical modem should be returned in <p lpdwLogicalModem>.
@comm Initializes a logical modem for further operations. The Provider should use this to set up any necessary connections, and to make sure that the Provider is up and running. The handle returned by this function is used by any subsequent functions invoked for this modem. Multiple modems may be initialized at the same time. The handle returned may be used in multiple process contexts, so the implementor should make sure any memory it references can be accessed in different process contexts.********/
LMI_RETURN FAR PASCAL LMI_InitLogicalModem (LPTSTR lpszLogicalModem, LPDWORD lpdwLogicalModem, LPATOM lpatClientName, LPATOM lpatPhone, LPMODEMCAPS lpmc);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_InitLogicalModem) (LPTSTR lpszLogicalModem, LPDWORD lpdwLogicalModem, LPATOM lpatClientName, LPATOM lpatPhone, LPMODEMCAPS lpmc);
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_InitProvider | Used to initialize the LMI provider.
@parm LPTSTR | lpszCurSpoolDir | Pointer to the current spool directory. The spool directory is where all intermediate format files get created, and where the client expects received fax files.
@parm LPMODEMCAPS | lpmcClient | Pointer to a <t MODEMCAPS> structure that describes the capabilities of the client. This should be used by the Provider to decide which formats can be understood by the client. For instance, if the client only understands MH, then the Provider would need to convert any received faxes into MH before reporting them in <f LMI_ReportReceives>. Similarly, this can indicate to the Provider whether or not features such as uploading of messages and Provider address books are supported by this particular client implementation.
@parm LPTSTR | lpszDefRecipAdd | For incoming G3 faxes for which the recipient is unknown, this address should be used. This typically happens for faxes received from G3 machines without a programmed CSI. In this case, this address should be put inside the linearized header on the AWG3 file. If this address ends in an <lq>@<rq> the Provider should append the phone number of the modem on which the fax was received, as well as any locally-obtained subaddressing information, using the Microsoft Fax Address format. For example, if the provider detects a DID string \<did\>, it should append <lq>\<local-phone-number>\|\<did\><rq> after the <lq>@<rq> sign.
@parm LPTSTR | lpszDefRecipName | Friendly name to be used for the default recipient. Goes along with <p lpszDefRecipAdd> to form an address pair.
@rdesc LMI_SUCCESS if successful.
@comm This call is made once per session. It is guaranteed to be the first call made to the Provider.
********/
LMI_RETURN FAR PASCAL LMI_InitProvider (LPTSTR lpszCurSpoolDir, LPMODEMCAPS lpmc, LPTSTR lpszDefRecipAdd, LPSTR lpszDefRecipName);typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_InitProvider) (LPTSTR lpszCurSpoolDir, LPMODEMCAPS lpmc, LPTSTR lpszDefRecipAdd, LPSTR lpszDefRecipName);
/********
@doc EXTERNAL SRVRDLL INSTALLATION
@func LMI_RETURN | LMI_RemoveModem | Called when a logical modem is removed from the list of current modems.
@parm LPTSTR | lpszModem | Pointer to the string identifying the logical modem being removed.
@rdesc Returns LMI_SUCCESS if successful.
@comm This call should be used to delete any context which has been cached for this logical modem. For instance, if in the <f LMI_AddModem> call, a lot of connection information had been stored in an ini file with the key being returned as the logical modem name, then this call would be used to delete this information.
********/
LMI_RETURN FAR PASCAL LMI_RemoveModem(LPTSTR lpszModem);typedef LMI_RETURN (FAR PASCAL FAR * LPLMI_RemoveModem)(LPTSTR lpszModem);
/********
@doc EXTERNAL SRVRDLL
@api DWORD | LMI_ReportReceives | Lets LMI provider report back received faxes.
@parm DWORD | dwLogicalModem | Handle representing the logical modem to be checked. If this is null, all logical modems owned by this Provider should be checked.
@parm WORD | wFlags | Can consist of a combination of the following flags:
@flag NRR_USER_REQUEST | This flag will be set if new faxes are being checked for on an explicit user request. This is meant for transports which tend to reduce the number of times they actually check for receives to reduce overhead. Providers should make sure to do the checks when this flag is set. @flag NRR_RETRIEVE_DATA | Set if the client wishes to process the 1st receive in the queue. If set, the provider fills out a LMIRECVSTATUS structure and specifies a pointer to it in *lplpnrtStatus. If the client makes successive calls specifying NRR_RETRIEVE_DATA (but not NRR_COMMITTED_RECV), information on the same receive (the 1st one on the queue) should be returned. Each time, a fresh atom needs to be allocated for the atFile field in LMIRECVSTATUS, and the client is responsible for freeing this atom. If this flag is not set, indicates that the client wants to simply find out if there are any receives waiting, and the provider should ignore lplpnrtStaus.
@flag NRR_COMMITTED_RECV | Indicates that the previous receive has been committed to permanent storage by the client and can be deleted by the Provider from its queue. It also indicates that the memory used for the LMIRECVSTATUS structure for that job can be freed or reused. Until this point, the Provider must not remove the received fax from its internal permanent storage. This helps avoid a fax being lost if the power goes off in the middle of the handoff. In the worst case, it causes two copies of the received fax to be processed instead of none. If this flag is specified, NRR_RETRIEVE_DATA is irrelevant and if specified should be ignored by the provider.
@parm LPDWORD | lpdwNumRecvs | Pointer to a DWORD which should be filled in with the number of new received faxes which are waiting to be picked up. If NRR_RETRIEVE_DATA is set in wFlags, the received fax being returned in the current call should not be included in this count. @parm LPLMIRECVSTATUS FAR* | lplpnrtStatus | Pointer to a pointer which should be set to point to a <t LMIRECVSTATUS> structure. The client assumes this pointer to point into accesible memory which is valid until the next call made with the flag NRR_COMMITTED_RECEIVE set. There can never be more than one pending receive, so a single piece of memory can be reused. This should be set only if <p wFlags> has the RETRIEVE_DATA flag set. The atom passed in this structure will be freed by the client. It should be set to null if there are no receives.
@rdesc Returns LMI_SUCCESS if succesful.
@comm It is possible for receives to be routed independent of this API directly to the client's mail store. This would happen if the client and Provider could communicate using another mail transport (such as Microsoft SFS) to do this more easily.********/
#define NRR_USER_REQUEST 0x0001
#define NRR_RETRIEVE_DATA 0x0002
#define NRR_COMMITTED_RECV 0x0004
LMI_RETURN FAR PASCAL LMI_ReportReceives(DWORD dwLogicalModem, WORD wFlags, LPDWORD lpdwNumRecvs, LPLMIRECVSTATUS FAR *lplpnrtStatus);
typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_ReportReceives)(DWORD dwLogicalModem, WORD wFlags, LPDWORD lpdwNumRecvs, LPLMIRECVSTATUS FAR *lplpnrtStatus);
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_ReportSend | Reports status of completed send jobs.
@parm DWORD | dwLogicalModem | Handle representing the logical modem to be checked. If this is null, all logical modems owned by this Provider should be checked.
@parm WORD | wFlags | Can consist of a combination of the following flags:
@flag NRS_USER_REQUEST | This flag will be set if the fax status is being checked for on an explicit user request. This is meant for transports which tend to reduce the number of times they actually check for receives to reduce overhead. Such transports should make sure to do the checks when this flag is set. @flag NRS_RETRIEVE_DATA | If set, indicates that the client wishes to process the status for the first one in the queue. If not set, indicates that the client wants to simply find out if there are any jobs completed.
@parm LPDWORD | lpdwNumDone | Pointer to a DWORD which should be filled in with the number of jobs which have been completed and are waiting to be picked up. If NRS_RETRIEVE_DATA flag is set, then this should be filled in with the number of jobs left not counting the one being returned in this call. @parm LPLMISENDSTATUS FAR* | lplpnstStatus | Pointer to a pointer which should be set to point to a <t LMISENDSTATUS> structure. The client assumes this pointer to be valid until the next call it makes to this function. It should be set to null if there are no completed sends. It should only be filled in if NRS_RETRIEVE_DATA is set in wFlags.
@rdesc Returns LMI_SUCCESS if succesful.********/
#define NRS_USER_REQUEST 0x0001
#define NRS_RETRIEVE_DATA 0x0002
LMI_RETURN FAR PASCAL LMI_ReportSend(DWORD dwLogicalModem, WORD wFlags, LPDWORD lpdwNumDone, LPLMISENDSTATUS FAR *lplpnstStatus);
typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_ReportSend)(DWORD dwLogicalModem, WORD wFlags, LPDWORD lpdwNumDone, LPLMISENDSTATUS FAR *lplpnstStatus);
/********
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_RescheduleSendJob | Reschedules the specified send job from the Provider's queue.
@parm DWORD | dwLogicalModem | The logical modem in whose queue the job to be rescheduled lives. This does not have to be the currently active modem.
@parm LPTSTR | lpszSenderMachineName | Pointer to a string identifying the sender machine name. This parameter, along with the <p dwUniqueID> and <p dwUniqueID2> uniquely identify this job for the Provider. These all must be same as the values passed in the <t LMISENDJOB> structure passed into <f LMI_SendFax>.
@parm DWORD | dwUniqueID | See <p lpszSenderMachineName>.
@parm DWORD | dwUniqueID2 | See <p lpszSenderMachineName>.
@parm LPSENDJOBTIME | lpsjtNewTime | Pointer to a new <t SENDJOBTIME> structure containing the reschedule information.
@rdesc LMI_SUCCESS on success.
@comm The reschedule can be performed asyncronously by the Provider. Return from this function does not imply any guarantee as to the time within which the job will be rescheduled. The client will ensure that this function is only called to reschedule jobs which were initiated on its machine.
********/
LMI_RETURN FAR PASCAL LMI_RescheduleSendJob (DWORD dwLogicalModem, LPTSTR lpszSenderMachineName, DWORD dwUniqueID, DWORD dwUniqueID2, LPSENDJOBTIME lpsjtNewTime);
typedef LMI_RETURN (FAR PASCAL FAR *LPLMI_RescheduleSendJob) (DWORD dwLogicalModem, LPTSTR lpszSenderMachineName, DWORD dwUniqueID, DWORD dwUniqueID2, LPSENDJOBTIME lpsjtNewTime);
/*******
@doc EXTERNAL SRVRDLL
@api LMI_RETURN | LMI_SendFax | Accepts a job for sending. Job is already completely rendered.
@parm DWORD | dwLogicalModem | Handle representing the logical modem from which this should be sent.
@parm LPLMISENDJOB | lpnj | Points to a <t LMISENDJOB> structure containing all the pertinent information about this job. The structure is allocated by the client and is freed on return of this call.
@rdesc Returns LMI_SUCCESS if the job is accepted. A successful return of this function implies that the job has been queued for subsequent processing and transmission. This function should fail only if there is a general failure in the provider or a parameter validation failure. Processing or transmission failures should be returned in the appropriate <f LMI_ReportSend> call.
*******/
LMI_RETURN FAR PASCAL LMI_SendFax (DWORD dwLogicalModem, LPLMISENDJOB lpnj);
typedef LMI_RETURN (FAR PASCAL FAR * LPLMI_SendFax) (DWORD dwLogicalModem, LPLMISENDJOB lpnj);
/*******
@doc EXTERNAL SRVRDLL
@api LPBYTE | LMI_SetCustomMsgOptions | This function is called to allow the user to set custom per message options.
@parm DWORD | dwLogicalModem | Handle representing the logical modem which is currently in use.
@parm LPBYTE | lpbOld | Pointer to a previously returned piece of memory which needs to be freed. If this parameter is being used the function should simply free the memory and return without putting up any UI.
@rdesc Returns a pointer to a memory block containing all the custom information which has been set. The first DWORD of the block MUST contain the total size of the memory being used. This data will be passed along with the <t LMISENDJOB> structure when this message is finally submitted. The memory will be freed by calling this same API again with the memory pointer passed in as a parameter. @comm This function can be used to enable all kinds of advance options to the user. One example of this could be usage of TAPI locations and credit cards for calls. If the Provider can support these, it can allow the user to setup credit card calls and then use these when resolving the phone numbers into dialable strings. If the Provider is using the TAPI translation services, the user could select a specific outbound device or line for the call, and do a credit card ID override on cards setup on the Provider TAPI setup.
*******/
LPBYTE FAR PASCAL LMI_SetCustomMsgOptions(DWORD dwLogicalModem, LPBYTE lpbOld);typedef LPBYTE (FAR PASCAL FAR *LPLMI_SetCustomMsgOptions)(DWORD dwLogicalModem, LPBYTE lpbOld);
#ifdef __cplusplus
} // extern "C" {
#endif
#endif
|
