dhcp_service_api.h

00001 /*
00002  * Copyright (c) 2013-2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef DHCP_SERVICE_API_H_
00019 #define DHCP_SERVICE_API_H_
00020 
00021 #include <ns_types.h>
00022 /**
00023  * \file dhcp_service_api.h
00024  * \brief DHCP server connection interfaces
00025  *
00026  * \section dhcp-service DHCP Service Instance
00027  * - dhcp_service_init(), Initializes a DHCP service.
00028  * - dhcp_service_delete(), Removes the DHCP service.
00029  *
00030  * \section dhcp-msg DHCP Service Messages
00031  * - dhcp_service_send_req(), Sends out DHCP request messages.
00032  * - dhcp_service_send_resp(), Sends out DHCP response messages.
00033  *
00034  * \section dhcp-tim DHCP Service Timers (retry timers)
00035  * - dhcp_service_send_req(), Sends out DHCP request messages.
00036  * - dhcp_service_set_retry_timers(), Sets the retransmission parameters.
00037  * - dhcp_service_req_remove(), Stops retrying and retransmissions.
00038  * - dhcp_service_timer_tick(), Indicates if a timeout occurred.
00039  *
00040  */
00041 
00042 /** Defines Debug Trace String for DHCP service */
00043 #define DHCP_SERVICE_API_TRACE_STR "DHcS"
00044 
00045 /*
00046  * Return values for callbacks
00047  */
00048 
00049 /** Message belongs to someone else. */
00050 #define RET_MSG_NOT_MINE 0
00051 /** Message is handled. */
00052 #define RET_MSG_ACCEPTED 1
00053 /** Message is not the final one and needs to hold on a bit. */
00054 #define RET_MSG_WAIT_ANOTHER -1
00055 /** Message is unexpected or corrupted. */
00056 #define RET_MSG_CORRUPTED -2
00057 
00058 /** \name DHCP options */
00059 ///@{
00060 #define TX_OPT_NONE                     0x00    /**< No options. */
00061 #define TX_OPT_USE_SHORT_ADDR           0x01    /**< Use short addresses. */
00062 #define TX_OPT_MULTICAST_HOP_LIMIT_64   0x02    /**< Use multicast hop limit of 64. */
00063 ///@}
00064 
00065 /**
00066  * /enum dhcp_instance_type
00067  * /brief DHCP instance types.
00068  */
00069 typedef enum dhcp_instance_type
00070 {
00071     DHCP_INSTANCE_CLIENT,
00072     DHCP_INSTANCE_SERVER
00073 } dhcp_instance_type_e;
00074 
00075 /**
00076  * \brief DHCP Service receive callback.
00077  *
00078  * When the DHCP service receives a DHCP message it will go through a list of registered DHCP services instances
00079  * until some instance acknowledges that the message belongs to it.
00080  * \param instance_id An instance of registered server.
00081  * \param msg_tr_id The message transaction ID.
00082  * \param msg_name Message type.
00083  * \param msg_ptr An allocated message pointer. Should not deallocate unless RET_MSG_ACCEPTED returned (then responsibility of client).
00084  * \param msg_len The length of the message.
00085  *
00086  * Return values
00087  * \return RET_MSG_ACCEPTED - Message is handled.
00088  * \return RET_MSG_CORRUPTED - Message is corrupted.
00089  * \return RET_MSG_NOT_MINE - Message belongs to someone else.
00090  */
00091 
00092 typedef int (dhcp_service_receive_req_cb)(uint16_t instance_id, uint32_t msg_tr_id, uint8_t msg_name, uint8_t *msg_ptr, uint16_t msg_len);
00093 
00094 /**
00095  * \brief DHCP Service Message Response callback.
00096  *
00097  * When the DHCP service receives a response to a DHCP message, this callback receives it.
00098  *
00099  * \param instance_id An instance of a registered server.
00100  * \param ptr A pointer for the client object.
00101  * \param msg_name Message type.
00102  * \param msg_ptr An allocated message pointer. Should not deallocate unless RET_MSG_ACCEPTED returned (then responsibility of client).
00103  * \param msg_len The length of the message.
00104  *
00105  * Return values
00106  * \return RET_MSG_ACCEPTED - Message is handled
00107  * \return RET_MSG_WAIT_ANOTHER - This message was not the last one for this transaction and a new reply is expected.
00108  */
00109 
00110 typedef int (dhcp_service_receive_resp_cb)(uint16_t instance_id, void *ptr, uint8_t msg_name,  uint8_t *msg_ptr, uint16_t msg_len);
00111 
00112 
00113 /**
00114  * \brief Initialize a new DHCP service instance.
00115  *
00116  * Creates and shares the socket for other DHCP services.
00117  *
00118  * \param interface_id Interface for the new DHCP instance.
00119  * \param instance_type The type of the new DHCP instance.
00120  * \param receive_req_cb A callback function to receive DHCP messages.
00121  *
00122  * \return Instance ID that is used to identify the service.
00123  */
00124 
00125 uint16_t dhcp_service_init(int8_t interface_id, dhcp_instance_type_e instance_type, dhcp_service_receive_req_cb *receive_req_cb);
00126 
00127 /**
00128 * \brief Deletes a server instance.
00129 *
00130 * Removes all data related to this instance.
00131 *
00132 * \param instance The instance ID of the registered server.
00133 */
00134 void dhcp_service_delete(uint16_t instance);
00135 
00136 /**
00137 * \brief Sends a DHCP response message.
00138 *
00139 * \param msg_tr_id The message transaction ID.
00140 * \param options Options for this request.
00141 * \param msg_ptr An allocated message pointer. Should not deallocate unless RET_MSG_ACCEPTED returned (then responsibility of client).
00142 * \param msg_len The length of the message.
00143 *
00144 * \return 0, if everything went fine.
00145 * \return -1, if error occurred.
00146 */
00147 int dhcp_service_send_resp(uint32_t msg_tr_id, uint8_t options, uint8_t *msg_ptr, uint16_t msg_len);
00148 
00149 
00150 /**
00151  * \brief Sends DHCP request message.
00152  *
00153  * Service takes care of retransmissions.
00154  *
00155  * \param instance_id The instance ID of the registered server.
00156  * \param options Options for this request.
00157  * \param ptr A void pointer to the client object.
00158  * \param addr The address of the server.
00159  * \param msg_ptr An allocated message pointer. This pointer is the responsibility of the service after this call.
00160  * \param msg_len The length of the message.
00161  * \param receive_resp_cb Callback pointer
00162  *
00163  * \return Transaction ID of the DHCP transaction
00164  * \return 0, if error occurred.
00165  */
00166 uint32_t dhcp_service_send_req(uint16_t instance_id, uint8_t options, void *ptr, const uint8_t addr[static 16], uint8_t *msg_ptr, uint16_t msg_len, dhcp_service_receive_resp_cb *receive_resp_cb);
00167 
00168 /**
00169  * \brief Setting retransmission parameters.
00170  *
00171  * Sets the retransmission parameters for this transaction.
00172  *
00173  * \param msg_tr_id The message transaction ID.
00174  * \param timeout_init An initial timeout value.
00175  * \param timeout_max The maximum timeout value when initial timeout is doubled with every retry.
00176  * \param retrans_max The maximum number of retries after which an error is received.
00177  *
00178  */
00179 void dhcp_service_set_retry_timers(uint32_t msg_tr_id, uint16_t timeout_init, uint16_t timeout_max, uint8_t retrans_max);
00180 
00181 /**
00182  * \brief Stops transactions for a message (retransmissions).
00183  *
00184  * Clears off sending retransmissions for a particular message transaction by finding it via its message transaction ID.
00185  *
00186  * \param msg_tr_id The message transaction ID.
00187  *
00188  */
00189 void dhcp_service_req_remove(uint32_t msg_tr_id);
00190 
00191 /**
00192  * \brief Timer tick function for retransmissions.
00193  *
00194  * Retransmission timer ticks should be increased with 100ms interval, if necessary. One tick is one millisecond.
00195  *
00196  */
00197 bool dhcp_service_timer_tick(uint16_t ticks);
00198 
00199 
00200 #endif //DHCP_SERVICE_API_H_