eFax Class Reference

The PHP script to send and receive faxes over the Internet. More...


Public Member Functions
	eFax ()
	Initializes the eFax object.
	send ($msg)
	Send the message to eFax.
	parse_disposition ($msg)
	Function used to parse the disposition.
	parse_inbound_message ($msg)
	Parse an Inbound Fax.
	message ()
	Create the XML message.
	set_outbound_url ($url)
	Set the URL used to send the fax.
	set_account_id ($account_id)
	Set the account idenfitier.
	set_raw_account_id ($account_id)
	Set the account idenfitier.
	set_user_name ($user_name)
	Set the user name.
	set_user_password ($user_password)
	Set the user password.
	set_fax_id ($fax_id)
	Set this fax request identifier.
	set_duplicate_id ($duplicate_id)
	Set whether fax identifiers can be duplicated.
	set_resolution ($resolution)
	Set the resolution used for transmission.
	set_priority ($priority)
	Set the priority for this transmission.
	set_self_busy ($self_busy)
	Queue faxes sent to the same number.
	set_fax_header ($fax_header)
	Defines the fax header.
	set_disposition_url ($disposition_url)
	Defines the return URL to signal disposition of the request.
	set_disposition_level ($disposition_level)
	Defines the type of reply.
	set_disposition_method ($method)
	Defines the method to use to send the reply.
	add_disposition_email ($name, $email)
	Add an email address for the response.
	add_recipient ($name, $company, $fax)
	Add a recipient name, company and fax number.
	add_file ($type, $contents)
	Add a file: the content of the fax.
	get_response ()
	The response of the last `eFax::send()` command.
	get_status ()
	Get the status of the last call to `eFax::send()`.
	get_docid ()
	Return the document identifier after a `eFax::send()`.
	get_error_level ()
	Get the last error level.
	get_error_description ()
	Get the last error description.
	get_result_fax_id ()
	Return the fax identifier.
	get_result_docid ()
	Return the document identifier from a disposition or inbound request.
	get_result_fax_number ()
	Return the fax number at the other end.
	get_result_completion_date ()
	Return the date and time when the transmission ended.
	get_result_fax_status ()
	Return the disposition or fax request status.
	get_result_csid ()
	Return the recipient or sender fax machine identification.
	get_result_duration ()
	Return the duration of the fax transmission.
	get_result_pages ()
	Return the number of pages sent.
	get_result_retries ()
	Return the number of times eFax had to dial to process the fax.
	get_result_error_message ($status=null)
	Return the error message from a status code.
	get_result_error_class ($status=null)
	Return the error class from a status code.
	get_result_request_date ()
	Get the date and time when the Inbound fax was received.
	get_result_request_type ()
	Get the type of inbound fax request.
	get_result_fax_name ()
	Retrieve the name of the fax received.
	get_result_user_fields ()
	Retrieve the array of user fields.
	get_result_barcodes ()
	Retrieve the array of barcode keys.
	get_result_files ()
	Retrieve the fax pages.
Public Attributes
const	RESPOND_SUCCESS = 1
	Received when sending the fax is a success.
const	RESPOND_ERROR = 2
	Received when sending the fax is a failure.

Detailed Description

This class is based on the developer documents provided by eFax (http://www.efax.com).

It will generate an XML file that is 100% compatible with the eFax specification. It supports all the data types and all the different modes available in the API.

If you know how much it costs to send one page, and you receive the disposition, you will be able to compute exactly how much sending the fax did cost:

 $fax_charge = $efax->get_result_pages() * $cost_per_page * $number_of_recipients;

Before calling eFax::send() you will need to call eFax::message(). Before calling eFax::message() you will need to at least call the following functions to setup your eFax object:

 $efax->set_account_id(...);
 $efax->set_user_name(...);
 $efax->set_user_password(...);
 $efax->add_file(...);
 $efax->add_recipient(...);

See also:: eFax::set_account_id() eFax::set_user_name() eFax::set_user_password() eFax::add_file() eFax::add_recipient()

Member Function Documentation

eFax::eFax ( )

By default, the output URL is the eFax URL expected by the eFax Developers. Namely, this is:

https://secure.efaxdeveloper.com/EFax_WebFax.serv

The outbound encoding is set to application/x-www-form-urlencoded.

The fax resolution is set to STANDARD.

The disposition level is set to both: success and error.

The status is set to 0 as if a response indicated a failure.

References RESPOND_ERROR, and RESPOND_SUCCESS.

eFax::send ( $ msg )

This function sends the specified message to eFax. The message can be generated using the eFax::message() function (actually, it is strongly recommanded that you do so unless you have another tool to generate such request reliably.)

IMPORTANT NOTE: You need to use the HTTPS protocol and for that you must have an HTTPS website with a valid certificate. Although just sending a fax does not require an HTTPS server, you will need to support connecting to an HTTPS server. And if you want to handle the disposition via your Web Server (instead of just getting an email), then you do not have a choice. You must have a valid SSL certificate.

Note:: If your system does not include HttpRequest, then you need to install it with the following commands. The php5-dev gives you the phpize that pecl needs. The pecl install the actual HTTP support. It needs to use a C compiler to recompile the module.

 sudo apt-get install php5-dev
 sudo pecl install pecl_http

Also, as mentioned at the end of a successful compile, add

 extension=http.so

in your php.ini file.

The phpize function is available in php5-dev (apt-get install php5-dev). You may also need the curl library development environment. Get the libcurl3-openssl-dev, for instance.

Exceptions:

eFaxException

is thrown if some parameter is invalid in the input or the response data. If somehow the transmission fails, the function returns false instead. However, the HttpRequest may throw some exception that will not be caught here.

Parameters:

[in] $msg The fax message (i.e. the XML message to forward.)

Returns:: true if the transmission succeeded with a positive response; false if the transmission does not occur

eFax::parse_disposition ( $ msg )

This function transforms the disposition XML message into a set of internal variables that can then be queried using get functions.

The disposition includes the user name and password. These will be checked against the user name and password defined in this eFax object. If there is a mismatch, then the function returns false and stops.

Please, see the Parsing the fax disposition section for an example of handling a disposition.

At this time, it is necessary to use stripslashes() before one can pass the XML data to this parse function.

 ...
 $msg = stripslashes($_POST["xml"]);
 $efax->parse_disposition($msg);
 ...

Note:: The function returns false if anything in this message represents a failure of some kind. This does not means that the fax was not partially transmitted.

Exceptions:

eFaxException

is raised if the XML message is not a valid outbound disposition file.

Parameters:

[in] $msg The message to parse

Returns:: true if the message represents a successful fax transmission; false in all other cases

See also:: eFax::set_user_name()
eFax::set_user_password()

eFax::parse_inbound_message ( $ msg )

This function is called whenever you receive an Inbound Fax from eFax Developer. It will send the necessary "Post Successful" response if the header of the message is parsed successfully. This means the login, password, and date of the message were valid.

The message includes the user name and password defined in the Inbound Settings section. These will be checked against the user name and password defined in this eFax object with the set_user_name() and set_user_password() functions. If there is a mismatch, then the function returns false and stops.

If the function returns true, then the data defined in the XML file is now available for you to query from your eFax object.

The message is expected to be received via a POST and will be in the $_POST['xml'] variable. Yet, the data will include backslashes and you must clean it before calling the parse function as in:

 ...
 $msg = stripslashes($_POST["xml"]);
 $efax->parse_inbound_message($msg);
 ...

Note:: This function returns false if the message is not valid. This means it is not valid XML, the user or password are wrong or the main tag is not InboundPostRequest. In all other cases, the function returns true meaning that the request is valid, not that the fax was properly received. You need to call the eFax::get_result_fax_status() to check whether the fax was successfully received (0) or not (!=0).

Exceptions:

eFaxException

is raised if the XML message is not a valid inbound request file. The minimum requirements checked are the following valid tags: InboundPostRequest (root tag), AccessControl (to ensure user), UserName (the login name), Password (your password), and FaxControl (the actual fax data, although all the sub-tags are not required.) The other tags are not considered so critical and as such only generate an error when missing.

Bug:: Because the function will quickly mark the received message as valid, it is strongly suggest that you save the XML message (i.e. write to a log or save in your database). That way, if the treatment of the message fails at a later time, you still have a copy of the message that generated that error. Especially, you may want to mark the message as "in process", and once you are done processing 100%, mark the message as done (or even remove that copy since it includes your login and password in clear...)

Parameters:

[in] $msg The raw XML data sent to you by eFax Developer via a POST request.

Returns:: true if the message is valid, false in all other cases; note that in the worst case scenario the function may instead raise an exception.

See also:

eFax::set_user_name()

eFax::set_user_password()

eFax::get_result_request_date()

eFax::get_result_request_type()

eFax::get_result_completion_date()

eFax::message ( )

This function generates the XML message that is to be sent to eFax.

Returns:: The XML message

eFax::set_outbound_url ( $ url )

This function sets the URL used to send the fax. The eFax class sets that variable to a default value that is the URL defined by eFax as their fax server.

Exceptions:

eFaxException

is raised whenever the parameter is not a string of at least 12 characters.

Parameters:

[in] $url The new URL to use to send the fax

eFax::set_account_id ( $ account_id )

This function is used to set the eFax account identifier. The identifier is your eFax Developer fax number.

The account identifier is required if you need to send a fax. It is not necessary if you just need to parse a disposition.

This is put in the $_POST['id'] variable of the request to the eFax Developer website.

Note:: Only digits must be presented to the eFax Developer interface. This function will automatically remove parenthesis, pluses, dashes and spaces if any. Also, the number is not expected to include a leading 1. If present, it is removed.

 "+1 (916) 988-1450" becomes "9169881450"
 "916-988-1450" becomes "9169881450"

Exceptions:

eFaxException is raised if $account_id is an array or an object.

Parameters:

[in] $account_id The eFax account identifier

See also:

eFax::set_raw_account_id()

eFax::set_user_name()

eFax::set_user_password()

eFax::set_raw_account_id ( $ account_id )

This function is used to set the eFax account identifier. The identifier is your eFax Developer fax number.

The account identifier is required if you need to send a fax. It is not necessary if you just need to parse a disposition.

This function uses the $account_id as is. Please, use the eFax::set_account_id() function to make sure that the identifier does not include invalid characters.

Note:: This function was added so special identifiers that are otherwise tempered with by the eFax::set_account_id() function can be used.

Exceptions:

eFaxException is raised if $account_id is an array or an object.

Parameters:

[in] $account_id The eFax account identifier.

See also:

eFax::set_account_id()

eFax::set_user_name()

eFax::set_user_password()

eFax::set_user_name ( $ user_name )

This function saves your user name (name used to login.)

The user name is required. Without a user name you cannot login and the request fails.

For outbound messages, the user name is saved in:

 OutboundRequest/AccessControl/UserName

For inbound messages, the user name is expected in:

 InboundPostReques/AccessControl/UserName

Note:: The outbound user name to use here is the user name that you use to login in your eFax Developer account here:

: https://secure.efaxdeveloper.com/EFax_UnifiedLogin.serv

Note:: The inbound user name is defined in the Inbound Settings of your eFax account. It can be set to the same user name as your outbound user name, yet we suggest that you choose a different user name.

Bug:: If your user name includes any blank character (space, new line, return, tabs, etc.), it is not impossible that it will fail because the data is being transfered in an XML file.

Exceptions:

eFaxException is raised if the $user_name is not a valid string. This means it is not null, not an array, not an object and has a length of at most 20 characters.

Parameters:

[in] $user_name The login name used to connect to eFax.

See also:

eFax::set_account_id()

eFax::set_raw_account_id()

eFax::set_user_password()

eFax::set_user_password ( $ user_password )

This function saves your user password.

The password is required. Without a password you cannot login and the request fails.

For outbound messages, the password is saved in:

 OutboundRequest/AccessControl/Password

For inbound messages, the password is expected in:

 InboundPostReques/AccessControl/Password

Note:: The outbound password to use here is the password that you use to login in your eFax Developer account here:

: https://secure.efaxdeveloper.com/EFax_UnifiedLogin.serv

Note:: The inbound password is defined in the Inbound Settings of your eFax account. It can be set to the same password as your outbound password, yet we suggest that you choose a different password.

Bug:: If your password includes any blank character (space, new line, return, tabs, etc.), it is not impossible that it will fail because the data is being transfered in an XML file.

Exceptions:

eFaxException is raised if the $user_password is not a valid string. This means it is not null, not an array, not an object and has a length of at most 20 characters.

Parameters:

[in] $user_password The password used to connect to eFax

See also:

eFax::set_account_id()

eFax::set_raw_account_id()

eFax::set_user_name()

eFax::set_fax_id ( $ fax_id )

This function saves the request identifier used for this fax. For instance, if the fax represents an order, you can use the order number as this fax identifier.

This identifier is optional. If none are defined, then none are sent.

The request identifier is saved in:

 OutboundRequest/Transmission/TransmissionControl/TransmissionID

Exceptions:

eFaxException

is raised if the parameter fax_id is not null, a string or a numeric, or if the length is more than 15 characters.

Parameters:

[in] fax_id The identifier used to identify this fax

eFax::set_duplicate_id ( $ duplicate_id )

This function can be used to determine whether the same fax identifier can be used multiple times (in several different requests.)

This identifier is optional. If this option is not set, then identifiers can be duplicated.

The request identifier is saved in:

 OutboundRequest/Transmission/TransmissionControl/NoDuplicates

Note:: The value 'true' means that you can duplicate the identifiers. The value 'false' means that you cannot duplicate the identifiers. Note that this is inverted from the NoDuplicates definition which is because the name starts with "No".

Exceptions:

eFaxException

is thrown whenever the parameter is not true, false or null.

Parameters:

[in] $duplicate_id One of true, false or null.

eFax::set_resolution ( $ resolution )

This function is used to set the transmission resolution. The resolution can be set to "STANDARD" or "FINE". Note that in general, eFax charges more for the "FINE" option.

The resolution is required. It is set to "STANDARD" by default so you do not need to set it if you want to send a standard fax.

The request identifier is saved in:

 OutboundRequest/Transmission/TransmissionControl/Resolution

Exceptions:

eFaxException

is thrown whenever the parameter is not one of "STANDARD" or "FINE".

Parameters:

[in] $resolution "STANDARD" or "FINE"

eFax::set_priority ( $ priority )

This function sets the priority of the transmission to one of NORMAL or HIGH.

This parameter is optional. The default is NORMAL.

The request identifier is saved in:

 OutboundRequest/Transmission/TransmissionControl/Priority

Exceptions:

eFaxException

is thrown whenever the parameter is not one of "NORMAL" or "HIGH".

Parameters:

[in] $priority "NORMAL" or "HIGH"

eFax::set_self_busy ( $ self_busy )

This function defines whether the phone number can accept multiple connections at once or not. If you do not know, it is recommanded that you set this value to true (which is the default).

SelfBusy is optional. If this option is not set, then faxes will be queued instead of sent when eFax is already sending a fax at the same number.

The request identifier is saved in:

 OutboundRequest/Transmission/TransmissionControl/SelfBusy

Exceptions:

eFaxException

is thrown whenever the parameter is not true, false or null.

Parameters:

[in] $self_busy One of true, false or null.

eFax::set_fax_header ( $ fax_header )

This function can be used to define the fax header.

eFax will provide a default if not specified.

The fax header is a string that can include @<name> and %<name> dynamic parameters. The @<name> parameters are usually specific to one fax. When the %<name> parameters are specific to each page of a fax.

The available dynamic fax header variables are:

@DATEx where x is a digit defining the format of the eFax server date (i.e. Pacific Time). y represents the year, m the month in digits, x the mon in letters, d the day. All formats imply a leading 0 to years, months and days.

    \@DATE0     yyyymmdd
    \@DATE1     mm/dd/yy
    \@DATE2     dd/mm/yy
    \@DATE3     dd/xx/yy
    \@DATE4     mm/dd/yyyy
    \@DATE5     dd xxx yyyy
    \@DATE6     xxxxx dd, yyyy
    \@DATE7     yy mm dd
    \@DATE8     yy-mm-dd
    \@DATE9     yymmdd

@TIMEx where x is a digit defining the format of the eFax server time (i.e. Pacific Time.) h represents the hour, m the minute, s the second, xx the AM/PM letters.

    \@TIME1     hh:mm
    \@TIME2     hh:mm:ss
    \@TIME3     hh:mmxx
    \@TIME4     hhmm

@ROUTETO{n} is replaced by the name of the recipient name and company. The value 'n' represents the maximum number of characters that will be printed in the header (i.e. "\@DATE3 \@TIME2 \@ROUTETO{20}" would print the date, time and up to 20 letters of the recipient name and recipient company name.) That name is looked up in the XML data:

 OutboundRequest/Transmission/Recipients/Recipient/RecipientName
 OutboundRequest/Transmission/Recipients/Recipient/RecipientCompany

@RCVRFAX is replaced by the fax number of the recipient. This is taken from the XML data:

 OutboundRequest/Transmission/Recipients/Recipient/RecipientFax

@SPAGES is the total number of pages for this fax including the cover sheet if there is one.

%P is the current page number.

%nf is used to defines the size of the font. 'n' must be replaced with a digit (0 through 3, i.e. %2f) to indicate the size. 0 is the default and is the largest font. 3 is the smallest font. This tag can appear as many times as required in the header.

The request identifier is saved in:

 OutboundRequest/Transmission/TransmissionControl/FaxHeader

Note:: Set this variable to " " (one space) if you do not want to have a header.

Exceptions:

eFaxException

is thrown whenever the parameter is not a string or null or if the string is over 80 characters.

Bug:: At this time, the input string is not checked for correctness.

Parameters:

[in] $fax_header A string with the header information or null.

eFax::set_disposition_url ( $ disposition_url )

This function is used to define the URL where the results of the request will be returned.

Your eFax account lets you define a default URL. This option lets you define the URL dynamically. However, be careful since the URL is limited to only 100 characters.

The request identifier is saved in:

 OutboundRequest/Transmission/DispositionControl/DispositionURL

Exceptions:

eFaxException

is thrown whenever the parameter is not a string or null or if the string is over 100 characters.

Bug:: At this time, the input string is not checked for correctness. (i.e. a valid URL.)

Parameters:

[in] $disposition_url A string with the header information or null.

eFax::set_disposition_level ( $ disposition_level )

This function is used to define the type of reply this request will generate.

By default, this class will force replies for both successful and erroneous request. It is strongly encouraged to keep it that way. The eFax default is NONE (i.e. zero--no reply whatsoever.)

It is possible to request no response at all.

The request identifier is saved in:

 OutboundRequest/Transmission/DispositionControl/DispositionLevel

Exceptions:

eFaxException

is thrown whenever the parameter is not one of 0, eFax::RESPOND_ERROR, eFax::RESPOND_SUCCESS or a mix of these flags.

Parameters:

[in] $disposition_level Logical OR of 0, eFax::RESPOND_ERROR and eFax::RESPOND_SUCCESS

References RESPOND_ERROR, and RESPOND_SUCCESS.

eFax::set_disposition_method ( $ method )

This function defines the method used to send back the reply. The reply can be sent using either a POST or an EMAIL.

This parameter is optional. The default is POST. Note that more often than not, emails are not secure.

IMPORTANT NOTE: The POST method requires you to have a secure web server (HTTPS protocol) with a valid certificate (one that eFax Developer computer can check automatically.)

The request identifier is saved in:

 OutboundRequest/Transmission/DispositionControl/DispositionMethod

Exceptions:

eFaxException

is thrown whenever the parameter is not one of null, "POST", "EMAIL" or "NONE".

Parameters:

[in] $method One of null, "POST", "EMAIL" or "NONE".

eFax::add_disposition_email	(	$	name,
		$	email
	)

This function adds one email address where the response will be sent. As many email addresses as you want can be included.

The default is no email addresses. However, your eFax setup may include an email address that is used by default whenever the disposition method is set to EMAIL.

When you add an email address, the recipient name is optional. This function is not capable of separating the recipient name from the email address. You must do that before calling this function.

The request identifier is saved in:

 OutboundRequest/Transmission/DispositionControl/DispositionEmails
 OutboundRequest/Transmission/DispositionControl/DispositionEmails/DispositionEmail
 OutboundRequest/Transmission/DispositionControl/DispositionEmails/DispositionEmail/DispositionRecipient
 OutboundRequest/Transmission/DispositionControl/DispositionEmails/DispositionEmail/DispositionAddress

Bug:: If the disposition method is not EMAIL then these emails will NOT be included in the output XML message. The system does not generate an error or anything like that in such circumstances.

Exceptions:

eFaxException

is thrown whenever the parameters are not null or strings.

Parameters:

`[in]`	$name	The name of the recipient (can be null)
`[in]`	$email	The email of the recipient (cannot be null)

eFax::add_recipient	(	$	name,
		$	company,
		$	fax
	)

This function adds one recipient to the list of recipients of this fax. The name and company name of the recipient are optional. The fax number is mandatory.

Internation fax numbers are dialed from the USA and must start with 011 and the country code character. The format of the fax phone number is "[-+ ()0-9]{5,25}". All characters other than digits are ignored. At least 5 characters and at most 25 are necessary.

The request identifier is saved in:

 OutboundRequest/Transmission/Recipients
 OutboundRequest/Transmission/Recipients/Recipient
 OutboundRequest/Transmission/Recipients/Recipient/RecipientName
 OutboundRequest/Transmission/Recipients/Recipient/RecipientCompany
 OutboundRequest/Transmission/Recipients/Recipient/RecipientFax

Exceptions:

eFaxException

is thrown whenever the parameters are not null, numeric or strings, a name is more than 50 characters or the fax number is less than 5 or more than 25 characters.

Parameters:

`[in]`	$name	The name of the fax recipient (can be null)
`[in]`	$company	The name of the fax recipient company (can be null)
`[in]`	$fax	The fax number where the fax is being sent (cannot be null)

eFax::add_file	(	$	type,
		$	contents
	)

This function adds one file to the content of the fax. There can be as many files as necessary to print out your entire fax. Each file can have a different format. The format must be correct for the data or the fax will fail.

The data parameter is the actual content of the file. This function will NOT read the content of a file on disk or otherwise. The function will encode the content for you (base64).

Supported file formats:

 doc    MS-Windows
 xls    Excel spreadsheet
 tif    Tag Interchange File Format (a TIFF image)
 pdf    Postscript Description Format file
 txt    Text only file
 htm or html    HTML file
 rtf    Rich Text Format

Exceptions:

eFaxException

is thrown if the file type is not one supported by eFax. Note that the names can be either all lowercase or all uppercase.

Parameters:

`[in]`	$type	One of: doc, xls, tif, pdf, txt, html, htm or rtf.
`[in]`	$contents	The contents of the file (NO file is read from disk!)

eFax::get_response ( )

This function returns the raw response of the last eFax::send() command.

Note:: If the eFax::send() does not send anything, then the response will be "not sent" when it happens before the HTTP POST or the empty string if no reply is received from the eFax::send().

Returns:: The response of the eFax server from the last eFax::send()

eFax::get_status ( )

This function returns the status that the last call to eFax::send() generated. By default, the status is set to 0 meaning that eFax::send() was never called. Once eFax::send() returns with no exception, then status will be set to either 1 (success) or 2 (failure).

When the status is 2, the eFax::get_error_level() and eFax::get_error_description() functions can be used to retrieve more information about the error.

Returns:: The eFax::send() command status on exit.

eFax::get_docid ( )

This function returns the document identifier found in the outbound response message. This can be reused later to request status information and when the final disposition is sent to us.

Returns:: The document identifier.

eFax::get_error_level ( )

This function returns the level of the last error that occured after a request was sent to eFax.

Returns:: The error level; one of User or System.

eFax::get_error_description ( )

This function returns the description of the last error that occured after a request was sent to eFax. This is a string of undefined length. It is intended for display and will be in English.

Returns:: The error description in plain English.

eFax::get_result_fax_id ( )

This function returns the fax identifier found in the disposition message or the fax request message. It is extracted from the message with a call to eFax::parse_disposition() or eFax::parse_inbound_message().

The disposition has a fax identifier only if you called the eFax::set_fax_id() before sending a fax with eFax::send(). This is that identifier that you probably want to make unique.

The fax request message sets the fax identifier to your account identifier (InboundPostRequest/FaxControl/AccountID). If you are handling multiple eFax accounts, it can be quite handy to check this identifier to know which number was used.

Note:: If the fax identifier is not available in the FaxControl, then the special string 'n.a.' is returned. Note that this could be viewed as an error since the AccountID tag is marked as mandatory.

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Returns:: The fax identifier, an empty string or null.

See also:

eFax::parse_disposition()

eFax::parse_inbound_message()

eFax::set_fax_id()

eFax::send()

eFax::get_result_docid ( )

This function returns the document identifier found in the disposition message or inbound request.

This identifier is automatically assigned by eFax to every single fax sent via eFax. This is the same as the identifier returned in the outbound response when you sent a fax.

Note:: Also not actually written anywhere in the eFax documents, this identifier is most certainly unique among all the faxes you will ever send or receive.

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Returns:: The document identifier.

See also:: eFax::parse_disposition()
eFax::parse_inbound_message()

eFax::get_result_fax_number ( )

This function returns the fax number at the other end. It may be found in the disposition message or the inbound fax request.

Note that you will receive one disposition per fax number defined in the outbound request and each one will have the same identifiers (fax identifier and document identifier.) Thus, if you need to distinguish each disposition, it is necessary to also check the fax number. (Although it may have been blocked and thus be undefined.)

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Returns:: The fax number used in link with this disposition, may be empty or 'Unknown' or some other label when it cannot be determined.

See also:: eFax::parse_disposition()
eFax::parse_inbound_message()

eFax::get_result_completion_date ( )

This function returns a Unix timestamp with the date and time when the transmission of the fax ended. The timestamp is defined in UTC.

The eFax::parse_inbound_message() may or may not return a completion date field. If so, this function returns -1.

Exceptions:

eFaxException is raised when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Bug:: This value may not be set. Please, check whether the returned reference is -1 before using the Unix timestamp.

Returns:: The Unix timestamp when the fax was 100% sent or received or -1 when not available

eFax::get_result_fax_status ( )

This function returns the status of the fax transmission from the message parsed with a call to eFax::parse_disposition() or eFax::parse_inbound_message().

The status is zero (0) when the fax was successfully sent or received. The status is an error number otherwise. Use the eFax::get_result_error_message() function to retrieve the corresponding error string.

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Returns:: The fax disposition or fax request status.

See also:

eFax::parse_disposition()

eFax::parse_inbound_message()

eFax::get_result_error_message()

eFax::get_result_csid ( )

This function returns some identification of the recipient (in a disposition) or the sender (in a fax request) as defined by the destination fax machine. This is not always available since many fax machines do not support this feature.

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Returns:: The recipient fax machine identification, may be an empty string.

See also:: eFax::parse_disposition()
eFax::parse_inbound_message()

eFax::get_result_duration ( )

This function returns the number of seconds that the fax transmission took. The time is rounded up to the closest second (i.e. if the time represents 0.1 second, then 1 is returned.)

Note:: The result is given to use in minutes. We multiply that number by 60. Note also that the result is a floating point so you may get a number that is not a multiple of 60. (i.e. 0.8 minutes represent 48 seconds.)

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition().

Returns:: The time the transmission of the fax took in seconds.

eFax::get_result_pages ( )

This function returns the number of pages that have been sent. If the fax transmission failed, this number indicates the number of pages that have successfully been sent.

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition() or eFax::parse_inbound_message().

Returns:: The number of pages that have successfully been sent or received.

See also:: eFax::parse_disposition()
eFax::parse_inbound_message()

eFax::get_result_retries ( )

This function returns the number of times eFax dial the fax number in order to transmit the documents. A first attempt success is represented by a 1 here.

Exceptions:

eFaxException when you call this function before a successful call to eFax::parse_disposition().

Returns:: The number of attemps made to send all the document pages.

See also:: eFax::parse_disposition()

eFax::get_result_error_message ( $ status = null )

This function converts a status code in an error message in English. The input status code parameter can be set to null in which case the internal result status code is used from the last call to the eFax::parse_disposition() function.

If the status code is not known, then the function returns the special error "unknown status code".

If the function is called with null and no disposition was parsed yet, the function returns "no disposition message has been parsed".

Parameters:

[in] $status The status code to convert or null

Returns:: The error message that corresponds to the $status code

See also:: eFax::parse_disposition()

eFax::get_result_error_class ( $ status = null )

This function converts a status code in an error class. The status code can be set to null in which case the result status code is used.

If the status code is not known, then the function returns the special class "?".

When there was no error, the special class " " is returned (a space.)

Parameters:

[in] $status The status code to convert or null

Returns:: The error message that corresponds to the $status

eFax::get_result_request_date ( )

This function returns the date and time in the form of a Unix timestamp of when the XML request was sent from eFax Developer.

If you want to know when the fax was received, use the eFax::get_result_completion_date() function instead.

Note:: This variable member is set only after a valid call to eFax::parse_inbound_message().

Exceptions:

eFaxException is raised if the eFax::parse_inbound_message() function was not called before hand.

Bug:: This value may not be set. Please, check whether the returned reference is -1 before using the Unix timestamp.

Returns:: The Unix timestamp when the XML request was sent to your server.

See also:: eFax::get_result_completion_date()
eFax::parse_inbound_message()

eFax::get_result_request_type ( )

The eFax Developer system can send a fax on receipt (New Inbound) and it can resend a fax that it received earlier (Manual Repost).

This function let you check the type of fax you are receiving.

Exceptions:

eFaxException is raised if the eFax::parse_inbound_message() function was not called before hand.

Returns:: One of "New Inbound" or "Manual Repost", unless it is undefined in which case null is returned.

eFax::get_result_fax_name ( )

This function returns the name of the of fax as defined in the eFax request.

Exceptions:

eFaxException is raised if the eFax::parse_inbound_message() function was not called before hand.

Returns:: The name of the fax or an empty string if not available.

See also:: eFax::parse_inbound_message()

eFax Class Reference

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation