Loading...
 
Location : Commetrex Support & Development Site » MSCML for Fax Media Server MSCML for Fax Media Server

MSCML for Fax Media Server

Version 1.2
November 2, 2012

1.0 MSCML ADDITIONS FOR FAX

The following sections specify the MSCML request and response sequences that FMS supports.

1.1 faxrecord Request

The faxrecord request instructs the FMS to simulate the called end of a fax session. Typically, in this mode a fax will be received by FMS. The specific syntax is:
<request>
 <faxrecord lclid=”id” [recurl=”url”]
 [header[=”string”]]
 [rx_coding=”encoding”]
 [plyurl=”url” [rmtid=”id”] [header[=”string”]] >
</request>

The faxrecord request causes the FMS to operate in an answer mode. In this mode, the FMS will behave as a called fax machine, sending a initial DIS and attaching the specified lclid. If the recurl is specified, the FMS will advertise that it can receive. If plyurl is specified, it will also advertise that it can transmit. One of recurl or plyurl must be specified for the operation to be valid. The operation of this command is based on the combination of plyurl and recurls:
plyurlreculrOperation
no no Invalid command, the operation fails
no yes Standard receive operation. The FMS receives the fax into the recurl.
yes no Standard polling operation. plyurl is sent to the connected fax machine if it is capable of receiving and commands the FMS to send. If rmtid is specified, the transmit operation will only be performed if the remote machine ID matches the rmtid.
yes yes A turnaround polling operation. The FMS is configured to send and receive. If the connected fax wishes to transmit, the FMS receives the image into the recurl. If the connected fax commands a transmission, the FMS sends the fax image contained in plyurl. If rmtid is specified, the transmit operation will only be performed if the remote machine ID matches the rmtid.

1.2 faxplay Request

This request instructs the FMS to behave as a calling fax terminal. Typically, this mode sends a fax.
<request>
	<faxplay lclid=”id” [plyurl=”url”] 
 	[header[=”string”]]
[recurl=”url”
[rx_coding=”encoding”]
[header[=”string”]]]
>
</request>

The faxplay request cause the FMS to enter originate mode. In this mode, the FMS waits for a DIS from the connected fax terminal. The operation of this command is based on the combination of plyurl and recurls:
plycurlrecurlOperation
nonoInvalid command, the operation fails
yesnoStandard transmit operation. plyurl is sent to the connected fax machine.
noyesStandard poll operation. The connected fax is commanded to send to the FMS. If the connected fax cannot send, the operation fails.
yesyesA turnaround polling operation. The FMS first sends the plyurl to the connected fax machine. If that machine advertises that it can transmit, the FMS commands that it send to it and stores the result in recurl.

In this mode it is assumed that the application server is aware of the identity of the remote fax machine and has pre-approved the polling operation.

1.3 Request Parameters

The following sections discuss the parameters contained in request .

1.3.1 plyurl and recurl Tags

The plyurl parameter specifies the TIFF file to send. recurl specifies a file to receive. The value may be either an URL or a FILE. The format for URL shall begin with “HTTP:” while the file option begins with “FILE:”.

1.3.2 header Tag

The header tag instruct FMS to insert a header on the associated option. FMS can insert headers on transmitted and receiving faxes. If the header tag is present without the format string, the FMS configured default header is used.
If the header field contains a format string, that string is used to format the header. This string can contain variable fields. These fields are replaced as required at the time the page is sent. Normal text is rendered into the header. The variable fields are:

Table 1: Page Header Format Codes

FieldDescription
%a3 character day of week abbreviation
%dDay of the month, 01-31
%mMonth, 01-12
%y2 digit year, 00-99
%Y4 digit year, 0000-9999
%IHour 00-12
%HHour 00-24
%MMinutes 00-59
%SSeconds 00-59
No value assignedPInsert the current page number
%TTotal number of pages (0 for receive header)
%DInsert date as specified in “time” field of IEFT_HDR_PARMS
%lInsert the local fax id.
%rInsert the remote fax id.
%%insert “%”

Table 1 Page Header Format Codes

1.3.3 rx_encoding Tag

This tag of the request applies to a receive operation. It specifies the encoding format of the received TIFF file. The valid options are:
mh – modified Huffman encoding, 1 dimensional
mr – modified Reed encoding, 2 dimensional
mmr – modified MR encoding.
For more information, refer to ITU specification T.6.

1.3.4 lclid Tag

This tag contains the local terminal ID that the FMS is to used for T.30 negotiations.
Typically, this value may appear in an header or on the display of a remote terminal. Some fax machines will refuse to communicate with a terminal that does not supply an ID. The value should contain numbers, “+” and “-“.

1.4 Fax Response

A fax response is sent at the end of a fax operation to indicate the result of the operation. A response may also be sent periodically during the operation to signal progress. Typically, a response will be sent:
  • At the end of negotiation
  • End of each page
  • At the end of the entire operation
The format of the response is:
<response>
<request=”[faxplay|faxrecord]” 
 	code=”code” 
[plypages=”cnt”]
[recpages=”cnt”]
text=”txt”
rmtid=”id”
reason=”reason”
error=”error”
[fmserror=”fmserror”[local_file=”file”]]>
</response>

The response transaction will contain the following tags.

1.4.1 rmtid Tag

rmtid tag contains the ID of the remote fax machine. If no ID was received, the value “none” will be supplied.

1.4.2 plypages and recpages Tag

This tag contains the number of pages sent or received up to that point in the operation.

1.4.3 reason Tag

The reason tag provides the reason for the response message. The values for reason are:
ReasonDescription
completeFax operation completed. There may have been errors.
op_startoperation started.
negotiatedsession negotiated successfully
page_doneprocessing on a page has completed
eomchange of mode. Switch from play to receive or receive to play.

1.4.4 code Parameter

The code parameter is a summary of the current operation. The values of code are bit mapped as follows:
CodeDescription
1Operation Failed
2Operation Complete
4Partial Success
8Progress Report
16Image received. Pages were written to recurl.
32Image sent. Some or all pages of plyurl were transferred.
64Invalid rmtid. Transmission not performed.
128IO error on plyurl. plyurl could not be read.
256IO error on recurl. recurl could not be written.
512Negotiation failure on send phase. There was a problem in the capabilities of the remote fax that prevented the send operation.
1024Negotiation failure on receive phase. There was a problem in the capabilities of the remote fax that prevented the receive operation.
2048IP connection lost.
4096Irrecoverable IP packet loss. Depending on the exact packets lost, this may cause a termination of the session.
8192No fax (T1 timeout)
16384Fail To Train
32768Procedure Interrupt
65536FMS non-fax error

1.4.5 text Tag

The values of text tag are :
TextDescription
okAll operations completed as specified
inprogressFax operation is not complete.
fttFailed to train at any available rate
protocolerrorUnspecified protocol error occurred.
failFax negotiation failed to agree on transfer format.
partialSome pages were transferred.
notfaxNo fax was detected.
fmserrorNon-fax error prevented the operation

1.4.6 error Tag

The error tag contains the error code that terminated the session . The valid codes are:
Error tagDescription
“no_error” No fax error occurred.
“no_carrier” No fax signal was detect for T1 seconds
“t1_timeout”Fax signals where present, but invalid
“no_dis_dtc” Carrier was detected but no DIS or DTC
“operation_mismatch” Neither Tx or Rx was possible
“train_failed” Train was attempted at all available speeds and was not acceptable.
“no_train_resp” Got no response to the TCF
“invalid_train_resp” Got invalid frame in response to TCF
“invalid_nsx” Recognized NSF/NSS/NSC was invalid
“invalid_dis” Received DIS/DTC was invalid
“out_of_rates” FTT at all available rates
“page_size_mismatch” Failed due to mismatch in page size
“resolution_mismatch” Failed due to mismatch in resolutions
“encoding_mismatch” Failed due to mismatch in image encoding
“modem_mismatch” Failed due to mismatch in available modems
“invalid_remote_id” Failed due to missing ID from remote
“padding_mismatch”Padding needed, but OTF configuration prevents padding
“no_pmc” No Post Message Command Received
“page_size_invalid” Failed due to invalid page size
“resolution_invalid” Failed due to invalid resolution
“encoding_invalid” Failed due to invalid encoding
“modem_rate_invalid” Failed due to invalid modem rate
“ecm_mode_invalid” Failed due to invalid ecm mode
“record_len_invalid” Failed due to invalid record length
“invalid_dcs” DCS did not match values in DIS
“dcs_from_dis_failed” Valid DCS could not be constructed from DIS or DTC
“no_pmr” No post message response was received
“invalid_pmr” Invalid post message response was received
“invalid_pmc” Invalid/Unrecognized Post Message command
“no_dcn_after_eop” Session complete thru EOP-MCF, but no DCN
“ctc_failure” Operation stopped due to excessive ecm retranmissions
“t5_expired” Receiver failed to become ready before T5
“no_rr_response” No response to RR frame. Most likely other end disconnected
“no_rnr_response” No response to RNR frame. Most likely other end disconnected
“no_ctc_response” No response to CTC frame. Most likely other end disconnected
“no_ctr_response” No response to CTR frame. Most likely other end disconnected
“no_eor_response” No response to EOR frame. Most likely other end disconnected
“no_pps_response” No response to PPS frame. Most likely other end disconnected
“invalid_rr_response” Invalid response to RR frame. Most likely machines are out of sync sending wrong frames
“invalid_rnr_response” Invalid response to RNR frame. Most likely machines are out of sync sending wrong frames
“invalid_ctc_response” Invalid response to CTC frame. Most likely machines are out of sync sending wrong frames
“invalid_ctr_response” Invalid response to CTR frame. Most likely machines are out of sync sending wrong frames
“invalid_eor_response” Invalid response to EOR frame. Most likely machines are out of sync sending wrong frames
“invalid_pps_response” Invalid response to PPS frame. Most likely machines are out of sync sending wrong frames
“rx_open_fail” Could not open document file for receive
“bad_file_format” File queued for transmit was not in TIFF-F format
“file_io_fail” I/O error reading/writing a document
“doc_missing” Document was missing when transmission was attempted
“file_eof” Unexpected end of file was encountered
“ecm_get_buffer_error” ECM error getting transmit buffer
“tio_general_error” Unspecified TIO error
“hw_fail” Unspecific hardware failure
“v21_tx_fail” V21 Transmission failed
“v21_rx_fail” V21 Receive started but did not complete
“hs_tx_fail” High speed modem failed to complete
“hs_rx_fail” High speed modem receive started but did not complete
“hw_init_fail” Modem could not be initialized
“ecm_fail” Problem in ECM package
“no_memory” Attempted to allocate memory and failed
“no_function” Attempted to use a function that is not implemented in this version. The fax operation terminated
“loss_of_hs_sync” No valid EOL was detected for 5 seconds session disconnected
“internal_failure” Internal failure timer expired. Typically a result of hardware failure
“third_frm_check_error”Third frame check error without good frame
“third_dis_received” Got a 3rd DIS frame, remote side can’t hear us
“canceled” Session canceled by application
“operator_interrupt” Session stopped for operator interrupt
“pri_no_response” PRI-xx was not responeded to after 3 tries
“remote_disconnect” Remote side disconnected
“unexpected_condition” Unexpected condition occurred
“third_t2_timeout” 3rd timeout on Op Alert
“pmr_dcn” Unexpected DCN or PostPageMessage Response DCN
"t2_timeout"T2 timeout
"page_not_found"EFT Starting page not found in TIFF
"early_eof"EFT TIFF File ended early, ending page not found
“user_abort” User abort
“too_many_rtns” Got RTNs to multiple pages and ran out of lower rates
“overload” session terminated by an overload condition
“api_err_invalid_handle” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_sess_active” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_sess_not_active”API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_resource”API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_conn_failed” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_already_active” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_not_active” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_negotiation_failed” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_more_licenses” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_license” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_license_already_allocated” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_queue_empty” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_file_exists” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_file_not_found” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_bad_file_format” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_doc” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_queue_too_late” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_session_failed” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_unsupported” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_queue_failed” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_bad_page_size” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_file_io_failure” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_conversion_required” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_check_bad_lines” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_check_diff_attrib” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_more_documents” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_incorrect_library_ver” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_rate_too_low” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_queue_overflow” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_already_attached” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_image_receive_fail” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_out_of_memory” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_session” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
api_err_bad_argument” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_fax_resources” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_queue” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_document_not_found” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_queue_corrupted” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_q_type” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_function_not_implemented” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_event” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_file_type”API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_bad_file_name” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_cpcd_busy” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_failure” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_resource_assigned” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_cpcd_port” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_no_password” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_monitor_missing” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_msec_was_allocated” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_font_error” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_font_too_large” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_font_not_found” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_page_length” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_page_type” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_page_size” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_resolution” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_encoding” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_convert” },API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_macro_bad_command”API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_macro_bad_syntax” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_font_bmp_too_large” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_not_initialized” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.
“api_err_invalid_rate” API errors typically represent failures within the Bladeware Fax subsystem and are not normally encountered. They are included here for completeness.

See appendix 1 for more detail on the generation of the error codes.

1.4.7 fms_error Tag

fms_error provides errors that are not part of the fax operation. These pertain to the FMS operations. This tag is not present unless an error occurs. The following values are possible:
fms_errorDescription
get_failedHTTP get failed. Operation aborted.
put_failedHTTP put failed. The file was successfully received, but the put operation failed. The file is still available on the FMS.
request_failedNo resources were available to handle the request.

The local_file tag bears some explanation. For a receive operation, the FMS receives the fax to a local file. When the fax is completed, it transfers the fax via an HTTP PUT. If this operation fails, the file is still available locally on the FMS. The local_file tag contains the name of the file containing the fax.

2.0 APPENDIX 1 – CODES MAPPED TO T.30 FLOWS

The following diagrams show the result codes and error codes generated by various exit points in the T.30 flow diagrams. These diagrams do not reflect the entire T.30 flow diagrams, but cover most of the exit conditions.
Image
Figure 1: Receiver Flow with Codes


Image
Figure 2: Transmitter Flow Chart with Result and Error Returns


Image
Figure 3: Receiver Flow Chart Part 2 with Result and Error Returns


Image
Figure 4: Transmitter Flow Chart Part 2 with Result and Error Returns


Image
Figure 5: Miscellaneous Flow Charts with Error and Result Codes

Online Users

8 online users