Mask Maximum
PKX_FAX_ENCODING_MMR
provides additional compression. Encoding lines are not separated by EOLs. Six EOLs indicate the end of the page. PKX_FAX_ENCODING_MR: 2-D encoding that provides additional compression by encoding two lines at a time. The second line specifies changes form the first. A special code is used for EOL.
PKX_FAX_ENCODING_MMR
eventMask This mask can be used to enable some optional FAX events. Possible events are:
PKX_FAX_EVENT_MASK_CONTROL_FRAME PKX_FAX_EVENT_MASK_DEFAULT PKX_FAX_EVENT_MASK_DISCONNECTED PKX_FAX_EVENT_MASK_DISCONNECTING PKX_FAX_EVENT_MASK_PAGE_SUCCESS PKX_FAX_EVENT_MASK_TRAINING 0
idRequired Indicates if an id number is required (PK_TRUE) or not (PK_FALSE).
PK_FALSE
level Used to change the modem signal level in dBm0. PKX_FAX_LEVEL_MAX: 0.0
PKX_FAX_LEVEL_DEFAULT: -13.5 PKX_FAX_LEVEL_MIN: -30.0
-13.5 (dBm0)
minimumRate The minimum transmit or receive rate in bps: PKX_FAX_RATE_2400 PKX_FAX_RATE_4800 PKX_FAX_RATE_7200 PKX_FAX_RATE_9600 PKX_FAX_RATE_12000 PKX_FAX_RATE_14400 PKX_FAX_RATE_2400
modemType The type of modem to transmit or receive: PKX_FAX_MODEM_V17 PKX_FAX_MODEM_V27 PKX_FAX_MODEM_V29 PKX_FAX_MODEM_V33 PKX_FAX_MODEM_V17 | PKX_FAX_MODEM_V29 | PKX_FAX_MODEM_V27 | PKX_FAX_MODEM_V33
printHeader Indicates if a print header is required (PK_TRUE) or not (PK_FALSE).
PK_FALSE
SID Sender Identification. This field should be set when sending a fax because some fax terminals reject faxes if the calling terminal does not identify itself.
timeout Indicates the timeout value, in ms. The possible settings are: PKX_FAX_TIMEOUT_MIN PKX_FAX_TIMEOUT_DEFAULT PKX_FAX_TIMEOUT_MAX PKX_FAX_TIMEOUT_DEFAULT 40000
5
Additional configuration parameters available for documents to be sent are:
Parameter
Description
Default
CNGEnabled EnableTransmit Calling Tone: Enabled (PK_TRUE) or Disabled (PK_FALSE).
PK_TRUE
maximumRate Specifies the maximum transmit rate in bps: PKX_FAX_RATE_2400 PKX_FAX_RATE_4800 PKX_FAX_RATE_7200 PKX_FAX_RATE_9600 PKX_FAX_RATE_12000 PKX_FAX_RATE_14400 PKX_FAX_RATE_14400
Additional configuration parameters available for documents to be received are:
Parameter
Description
Default
CEDEnabled Enable sending Transmit Called Station Identification tone: Enabled (PK_TRUE) or Disabled
(PK_FALSE).
PK_TRUE
NSF Non-standard Facilities frame NULL
NSFLength Size of actual data in NSF array 0 pageWidth Specifies the page width:
PKX_FAX_WIDTH_A3 (11.7x16.5 in/297x420 mm)
PKX_FAX_WIDTH_A4 (8.3x11.7 in/ 210x297 mm) PKX_FAX_WIDTH_ALL (all supported page widths) PKX_FAX_WIDTH_B4 (9.8x13.8 in/ 257x364 mm) PKX_FAX_WIDTH_LEGAL (8.5x14 in/ 216x356 mm) PKX_FAX_WIDTH_LETTER (8.5x11 in/216x279 mm) PKX_FAX_WIDTH_ALL
5
resolution Specifies the required resolution of the received document in dpi:
PKX_FAX_RESOLUTION_ALL (all supported values) PKX_FAX_RESOLUTION_HIGH (204x196) PKX_FAX_RESOLUTION_LOW (204x98) PKX_FAX_RESOLUTION_SUPER_HIGH (204x391) PKX_FAX_RESOLUTION_SUPER_HIGH
After the fax session starts, the user application receives the following events indicating the progress of the fax:
Event
Description
Parameters
PKX_EVENT_CHANNEL_FAX_STARTED The current fax session started sending or receiving a fax.
None
PKX_EVENT_CHANNEL_FAX_TRAINING The modems involved in the current fax session are training (optional event)
None
PKX_EVENT_CHANNEL_FAX_TRAINING_SUCCESS The current fax session has successfully negotiated transmission parameters (optional event)
None
PKX_EVENT_CHANNEL_FAX_TRAINING_FAILED The current fax session has failed to negotiate transmission parameters. Subsequent attempts to train at lower transfer rates may still succeed. (optional event)
None
PKX_EVENT_CHANNEL_FAX_CONTROL_FRAME The current fax session has sent or received a control frame.
p0: Indicates the type of control frame
PKX_EVENT_CHANNEL_FAX_DOCUMENT_BEGIN The current fax session has started exchanging a document
None
PKX_EVENT_CHANNEL_FAX_PAGE_BEGIN The current fax session started a page.
None
PKX_EVENT_CHANNEL_FAX_PAGE_END The current fax session finished a page.
None
5
PKX_EVENT_CHANNEL_FAX_DOCUMENT_END The current fax session finished a document.
None
PKX_EVENT_CHANNEL_FAX_DISCONNECTING The current fax session is disconnecting (optional event)
None
PKX_EVENT_CHANNEL_FAX_DISCONNECTED The current fax session has received a DCN message from the remote side (optional event)
None
PKX_EVENT_CHANNEL_DONE_FAX The current fax session is complete.
p0: mode p1: result p2: lastError
All parameters are the same as those in
PKX_TFaxStatus .
The user application can use the function PKX_CHANNEL_FaxGetStatus at any time to retrieve detailed information about the transmission progress, any errors, and negotiated parameters. Upon completion of the
transmission (indicated by receiving the event PKX_EVENT_CHANNEL_DONE_FAX) the application should use this function to determine the final outcome of the fax transmission. The function returns a structure
PKX_TFaxStatus which contains the following information. Some fields correspond to those specified in PKX_TFaxConfig and reflect the values chosen when the fax transmission was negotiated with the far end.
Field
Description
PK_UINT rate Current transmission rate.
PK_UINT resolution Current transmission resolution.
PK_UINT encoding Current transmission encoding.
PK_UINT pageWidth Current page width.
PK_UINT mode Current mode of operation. PKX_FAX_MODE_IDLE PKX_FAX_MODE_CONNECTING PKX_FAX_MODE_NEGOTIATING PKX_FAX_MODE_RECEIVING PKX_FAX_MODE_SENDING PKX_FAX_MODE_DISCONNECTING PKX_FAX_MODE_FINISHED
PK_UINT result Result of the previous fax attempted. PKX_FAX_RESULT_IN_PROGRESS PKX_FAX_RESULT_SUCCESSFUL PKX_FAX_RESULT_NOFAX PKX_FAX_RESULT_PARTIAL PKX_FAX_RESULT_NEG_FAILED PKX_FAX_RESULT_FAILED_TO_TRAIN PKX_FAX_RESULT_PROTOCOL_ERROR PKX_FAX_RESULT_FAILED
PK_UINT lastError Last error encountered.
PK_UINT ECMEnabled Indicates whether the previous fax was ECM.
PK_UINT duration Duration in milliseconds.
PK_UINT documentNumber Current document in progress.
PK_UINT pageNumber Current page of the document.
PK_UINT NEG_count Number of negotiating frames processed. PK_UINT FTT_count Failure to train frames processed.
PK_UINT CFR_count Confirmation to receive frames processed. PK_UINT MCF_count Message confirmation frames processed. PK_UINT PPR_count Partial page request frames processed. PK_UINT RTN_count Retrain negative frames processed.
PK_UINT DCN_count Disconnect frame processed.
PK_UINT badLineCount Number of bad lines on current page.
PK_UINT RXPages Number of pages received.
PK_UINT TXPages Number of pages transmitted.
PK_UINT RXBytes Number of bytes received by modem.
PK_UINT TXBytes Number of bytes transmitted by modem.
PK_UINT RXPageErrors Number of pages with line errors.
PK_UINT RXTotalLines Total lines.
PK_UINT TXTotalLines Total lines.
PK_CHAR documentName Document.
PK_CHAR remoteSID Received SID.
PK_U8 remoteNSF Received NSF.
PK_UINT synopsisLength Number of integers in session summary.
PK_INT synopsis T.30 protocol session summary.
When establishing a call to transmit a fax, the user application should enable call analysis to determine whether a fax machine has answered the call. Refer to section Call Analysis (pg. 33).
The following diagram shows establishing a call, sending a fax and the events the application can expect to receive.
The user application uses PKX_CHANNEL_Stop to stop a fax transmission (send or receive) already in progress. This function takes the following parameter:
• the channel on which the fax operation is being executed
The event PKX_EVENT_CHANNEL_STOPPED_FAX will be returned to indicate that the fax operation has been stopped.
The user application can use the function PKX_CHANNEL_ClearDocument if documents are added but send or receive has not started. This flushes the document queues; no documents are left in the queues.
Example
The following is an example of setting up a fax document and sending it.
5
// Send a fax. Channel is passed in from calling function. Header // is re-set to default as an example of how to set it. Minimum // transfer rate is set to 9600 as an example of modifying the // PKX_TFaxConfig struct. This function also adds a second page to // the fax. The opposite of this function (receive) can be achieved // by changing:
// -PKX_FAX_DOCUMENT_SEND to PKX_FAX_DOCUMENT_RECEIVE // -PKX_CHANNEL_FaxSend() to PKX_CHANNEL_FaxReceive()
// -Remove second PKX_CHANNEL_FaxAddDocument() call (only one // is needed to receive)
// NOTES:
// FAX_FILE_TO_SEND_P1/P2 are predefined strings containing // the address of the *.tif file
PK_BOOL sendFax(TPikaHandle channelHandle) { PKX_TFaxConfig faxconfig;
PKX_TFaxDocParms faxdocparms; PK_STATUS status = PK_SUCCESS;
memset(&faxdocparms, 0, sizeof(PKX_TFaxDocParms)); memset(&faxconfig,0,sizeof(PKX_TFaxConfig));
if ((status =
PKX_CHANNEL_FaxGetDefaultConfig(channelHandle,&faxconfig)) != PK_SUCCESS) {
// Error getting default configuration }
faxconfig.minimumRate = PKX_FAX_RATE_9600;
strncpy(faxdocparms.header,
"To: %r From: %l Date: %d/%m/%y Time: %H:%M Page: %P", PKX_FAX_MAX_HEADER_LENGTH); strncpy(faxdocparms.fileName, FAX_FILE_TO_SEND_P1,PKX_FAX_MAX_FILENAME_LENGTH); faxdocparms.sendOrReceive = PKX_FAX_DOCUMENT_SEND; if ((status = PKX_CHANNEL_FaxAddDocument(channelHandle,&faxdocparms)) != PK_SUCCESS) {
// Error adding document } strncpy(faxdocparms.fileName, FAX_FILE_TO_SEND_P2,PKX_FAX_MAX_FILENAME_LENGTH); if ((status = PKX_CHANNEL_FaxAddDocument(channelHandle,&faxdocparms)) != PK_SUCCESS) {
// Error adding document }
if ((status = PKX_CHANNEL_FaxSend(channelHandle,&faxconfig)) != PK_SUCCESS) {
// Error sending fax
} }
5.3.5.10.1 Fax Diagnostics
Fax includes some advanced logging capabilities that can be used to debug fax specific problems. There are two types of logs that can be enabled: audio recordings and fax protocol logs. It is also possible to have the logging facility only keep logs and recordings from fax sessions that fail. The logging does add additional stress on a system, so logs should not be be enabled on more than a few channels. Audio logging causes less stress than the protocol logging. Deleting successful logs and recordings adds additional system stress since the files are created and then deleted when a successful session completes.
There are two methods available for enabling the logging.
The easiest method is to set the logging in the configuration file. This method sets the logging on all channels. In the logging section of pikagp_aoh.cfg, the following can be added to enable fax logging:
[logs] level=none object.mediastream=0x0007000f ;files=2 ;size=12 ;cref=yes
Alternatively, if the user application needs to control the logging using an API call or if an application wants to control the logging on individual channel, the AoH logging API can be used. This mechanism is described in the Low Level API Programmer’s Guide, which is available on PIKA's website at SDK: downloads & docs for HMP Boards. To control logging on an individual channel, the function PKX_CHANNEL_GetBypassInfo is required to retrieve the output media stream handle. It is not necessary to enable bypass mode.
5.3.6 Conferencing
A conference object is required when more than two channels must be joined together. The PKX_CONF_Create function creates a new conference object of the type specified. The conference types available are: