ewf_interface.h

Go to the documentation of this file.

/************************************************************************/
#ifndef __ewf_interface__h__included__
#define __ewf_interface__h__included__
 
#include "ewf.h"
#include "ewf_platform.h"
#include "ewf_allocator.h"
#include "ewf_tokenizer.h"
#include "ewf_message.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/************************************************************************/
typedef ewf_message ewf_interface_message;
 
typedef ewf_tokenizer_pattern ewf_interface_tokenizer_pattern;
 
typedef ewf_result(*ewf_interface_response_callback)(ewf_interface* interface_ptr, uint8_t* buffer_ptr, uint32_t length);
 
typedef ewf_result(*ewf_interface_urc_callback)(ewf_interface* interface_ptr, uint8_t* buffer_ptr, uint32_t length);
 
struct _ewf_interface
{
#ifdef EWF_PARAMETER_CHECKING
    uint32_t struct_magic;
    uint32_t struct_size;
    uint32_t struct_version;
    uint32_t struct_type;
#endif /* EWF_PARAMETER_CHECKING */
 
#ifdef EWF_PLATFORM_HAS_THREADING
    ewf_platform_mutex global_mutex;
#endif /* EWF_PLATFORM_HAS_THREADING */
 
    volatile bool command_mode;
 
    volatile bool sync_urc_processing;
 
    /* *** Pointers to other related structures *** */
 
    struct _ewf_adapter* adapter_ptr;
 
    void* implementation_ptr;
 
    ewf_interface_message current_message;
 
    /* *** Pointers to interface callbacks */
 
    ewf_interface_response_callback response_callback;
 
    ewf_interface_urc_callback urc_callback;
 
    ewf_interface_urc_callback user_urc_callback;
 
    /* *** Allocators *** */
 
    ewf_allocator* message_allocator_ptr;
 
    ewf_allocator* data_allocator_ptr;
 
    /* *** Queues *** */
 
    ewf_platform_queue* response_queue_ptr;
 
    ewf_platform_queue* urc_queue_ptr;
 
    /* *** Timeout parameters *** */
 
    volatile uint32_t default_timeout;
 
    /* *** Tokenizer data *** */
 
    ewf_interface_tokenizer_pattern* message_tokenizer_pattern_ptr;
 
    ewf_interface_tokenizer_pattern* command_response_end_tokenizer_pattern_ptr;
 
    ewf_interface_tokenizer_pattern* command_response_tokenizer_pattern_ptr;
 
    ewf_interface_tokenizer_pattern* urc_tokenizer_pattern_ptr;
 
    /* *** Hardware interface *** */
 
    ewf_result(*hardware_start)(ewf_interface* interface_ptr);
 
    ewf_result(*hardware_stop)(ewf_interface* interface_ptr);
 
    ewf_result(*hardware_send)(ewf_interface* interface_ptr, const uint8_t* buffer_ptr, uint32_t buffer_length);
 
    ewf_result(*hardware_receive)(ewf_interface* interface_ptr, uint8_t* buffer_ptr, uint32_t* buffer_length_ptr, bool wait);
};
 
#define EWF_INTERFACE_STRUCT_MAGIC         (0x017eface) /* ~~ i(n)te(r)face */
#define EWF_INTERFACE_STRUCT_SIZE          (sizeof(struct _ewf_interface))
#define EWF_INTERFACE_VERSION              (EWF_DEVELOPER_MICROSOFT | 0x0001)
 
#ifdef EWF_PARAMETER_CHECKING
#define EWF_INTERFACE_VALIDATE_POINTER(interface_ptr)                               \
do {                                                                                \
    if ((interface_ptr == NULL) ||                                                  \
        (interface_ptr->struct_magic != EWF_INTERFACE_STRUCT_MAGIC) ||              \
        (interface_ptr->struct_size != EWF_INTERFACE_STRUCT_SIZE) ||                \
        (interface_ptr->struct_version != EWF_INTERFACE_VERSION) ||                 \
        (interface_ptr->implementation_ptr == NULL))                                \
    {                                                                               \
        EWF_LOG_ERROR("The interface pointer is invalid.");                         \
        return EWF_RESULT_INVALID_FUNCTION_ARGUMENT;                                \
    }                                                                               \
} while(0)
#else
#define EWF_INTERFACE_VALIDATE_POINTER(interface_ptr)                               \
do {                                                                                \
    if ((interface_ptr == NULL) ||                                                  \
        (interface_ptr->implementation_ptr == NULL))                                \
    {                                                                               \
        EWF_LOG_ERROR("The interface pointer is invalid.");                         \
        return EWF_RESULT_INVALID_FUNCTION_ARGUMENT;                                \
    }                                                                               \
} while(0)
#endif /* EWF_PARAMETER_CHECKING */
 
#ifdef EWF_PARAMETER_CHECKING
#define EWF_INTERFACE_VALIDATE_POINTER_TYPE(interface_ptr, interface_type)          \
do {                                                                                \
    if ((interface_ptr == NULL) ||                                                  \
        (interface_ptr->struct_type != interface_type) ||                           \
        (interface_ptr->implementation_ptr == NULL))                                \
    {                                                                               \
        EWF_LOG_ERROR("The interface type is invalid.");                            \
        return EWF_RESULT_INVALID_FUNCTION_ARGUMENT;                                \
    }                                                                               \
} while(0)
#else
#define EWF_INTERFACE_VALIDATE_POINTER_TYPE(interface_ptr, interface_type)
#endif
 
/************************************************************************/
ewf_result ewf_interface_init(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_clean(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_start(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_stop(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_send(ewf_interface* interface_ptr, const uint8_t * buffer_ptr, uint32_t buffer_length);
 
ewf_result ewf_interface_receive_response(ewf_interface* interface_ptr, uint8_t** buffer_ptr_ptr, uint32_t* buffer_length_ptr, uint32_t wait_time);
 
ewf_result ewf_interface_receive_urc(ewf_interface* interface_ptr, uint8_t** buffer, uint32_t * buffer_length_ptr, uint32_t wait_time);
 
ewf_result ewf_interface_message_allocator_set(ewf_interface* interface_ptr, ewf_allocator* allocator_ptr);
 
ewf_result ewf_interface_data_allocator_set(ewf_interface* interface_ptr, ewf_allocator * allocator_ptr);
 
ewf_result ewf_interface_release(ewf_interface* interface_ptr, void* buffer_ptr);
/* TODO: global rename ewf_interface_release -> ewf_interface_release_buffer */
 
ewf_result ewf_interface_release_data(ewf_interface * interface_ptr, void* buffer_ptr);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_default_timeout_set(ewf_interface * interface_ptr, uint32_t timeout);
 
ewf_result ewf_interface_default_timeout_get(ewf_interface * interface_ptr, uint32_t* timeout_ptr);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_tokenizer_message_pattern_set(ewf_interface* interface_ptr, ewf_interface_tokenizer_pattern* tokenizer_patter_ptr);
 
ewf_result ewf_interface_tokenizer_message_pattern_get(ewf_interface* interface_ptr, ewf_interface_tokenizer_pattern** tokenizer_patter_ptr_ptr);
 
ewf_result ewf_interface_tokenizer_command_response_end_pattern_set(ewf_interface * interface_ptr, ewf_interface_tokenizer_pattern * tokenizer_patter_ptr);
 
ewf_result ewf_interface_tokenizer_command_response_end_pattern_get(ewf_interface * interface_ptr, ewf_interface_tokenizer_pattern * *tokenizer_patter_ptr_ptr);
 
ewf_result ewf_interface_tokenizer_command_response_pattern_set(ewf_interface* interface_ptr, ewf_interface_tokenizer_pattern* tokenizer_patter_ptr);
 
ewf_result ewf_interface_tokenizer_command_response_pattern_get(ewf_interface* interface_ptr, ewf_interface_tokenizer_pattern** tokenizer_patter_ptr_ptr);
 
ewf_result ewf_interface_tokenizer_urc_pattern_set(ewf_interface* interface_ptr, ewf_interface_tokenizer_pattern* tokenizer_patter_ptr);
 
ewf_result ewf_interface_tokenizer_urc_pattern_get(ewf_interface* interface_ptr, ewf_interface_tokenizer_pattern** tokenizer_patter_ptr_ptr);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_process_byte(ewf_interface* interface_ptr, uint8_t b);
 
ewf_result ewf_interface_process_buffer(ewf_interface* interface_ptr, uint8_t* buffer_ptr, uint32_t buffer_length);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_urc_processing(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_urc_process_message(ewf_interface* interface_ptr, uint8_t* buffer_ptr, uint32_t buffer_length);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_poll(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_receive_poll(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_process_poll(ewf_interface* interface_ptr);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_set_response_callback(ewf_interface* interface_ptr, ewf_interface_response_callback callback);
 
ewf_result ewf_interface_set_urc_callback(ewf_interface* interface_ptr, ewf_interface_urc_callback callback);
 
ewf_result ewf_interface_set_user_urc_callback(ewf_interface* interface_ptr, ewf_interface_urc_callback callback);
 
/************************************************************************/
/************************************************************************/
ewf_result ewf_interface_send_command(ewf_interface* interface_ptr, const char * command_str);
 
ewf_result ewf_interface_send_commands(ewf_interface* interface_ptr, const char* command_str, ...);
 
ewf_result ewf_interface_drop_all_responses(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_drop_response(ewf_interface* interface_ptr);
 
ewf_result ewf_interface_get_response(ewf_interface* interface_ptr, uint8_t** response_out);
 
ewf_result ewf_interface_verify_response(ewf_interface* interface_ptr, const char* expected_str);
 
ewf_result ewf_interface_verify_responses(ewf_interface* interface_ptr, uint32_t response_count, const char** expected_str_arr);
 
ewf_result ewf_interface_verify_response_starts_with(ewf_interface* interface_ptr, const char* expected_start_str);
 
ewf_result ewf_interface_verify_response_ends_with(ewf_interface* interface_ptr, const char* expected_end_str);
 
/************************************************************************/
/************************************************************************/
#ifdef __cplusplus
}
#endif
 
#endif /* __ewf_interface__h__included__ */