aftp_format_error

The aftp_format_error call retrieves the current AFTP error information to a text buffer. The AFTP return code for the current error must not be AFTP_RC_HANDLE_NOT_VALID. If the current status is AFTP_RC_OK and the aftp_format_error call is invoked, the return_code value output by this call is AFTP_RC_STATE_CHECK. The aftp_format_error call should only be invoked when an error has occurred.

AFTP_ENTRY aftp_format_error(
IN AFTP_HANDLE_TYPE connection_id,
IN AFTP_DETAIL_LEVEL_TYPE detail_level,
OUT unsigned char AFTP_PTR error_str,
IN AFTP_LENGTH_TYPE error_str_size,
OUT AFTP_LENGTH_TYPE AFTP_PTR returned_length,
OUT AFTP_RETURN_CODE_TYPE AFTP_PTR return_code
);

Parameters

connection_id

An AFTP connection object originally created with aftp_create.

detail_level

The detail in which the error string will describe the AFTP error. These values can be OR'ed together to retrieve specific sets of information. For example, to return the primary message and the error log information, specify (AFTP_DETAIL_RC | AFTP_DETAIL_LOG).

AFTP_DETAIL_RC

The AFTP return code, error category, index, and primary error message will be output.

AFTP_DETAIL_SECOND

The AFTP secondary error message will be output.

AFTP_DETAIL_LOG

The error logging information will be output.

AFTP_DETAIL_INFO

The informational message associated with the error will be output.

AFTP_DETAIL_ALL

All of the previous detail levels will be output in the error string.

error_str

The buffer into which the error information string will be written.

Use the AFTP_MESSAGE_SIZE constant to define the length of this buffer. Add 1 to the size if you want to be able to add a null terminator to the text in the buffer.

error_str_size

The size of the buffer into which the error information will be written.

returned_length

The actual length of the error_str parameter in bytes.

return_code

The return code issued for this function. See AFTP Return Codes for the list of possible return codes.

Example

{
    AFTP_HANDLE_TYPE        connection_id;
    AFTP_RETURN_CODE_TYPE   aftp_rc;
    unsigned char           error_string[AFTP_MESSAGE_SIZE+1];
    AFTP_LENGTH_TYPE        returned_length;


    /*
     * There are no specific prerequisite calls for this call,
     * but you must issue a call that returns an error return code
     */

    if (aftp_rc != AFTP_RC_OK) {
        /*
         * We had an AFTP error - so let's get
         * the description that corresponds to
         * the error.
         */

        aftp_format_error(
            connection_id,
            AFTP_DETAIL_ALL,
            error_string,
            (AFTP_LENGTH_TYPE)sizeof(error_string)-1,
            &returned_length,
            &aftp_rc);
    }
}
 

Line Flows

None.