dhcp_service_api.h

00001 /*
00002  * Copyright (c) 2013-2018, 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     DHCP_INSTANCE_CLIENT,
00071     DHCP_INSTANCE_SERVER,
00072     DHCP_INTANCE_RELAY_AGENT
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 Enable DHCPv6 Relay Agent to server.
00129 *
00130 *
00131 * \param instance The instance ID of the registered server.
00132 * \param server_address global server IPv6 address
00133 */
00134 void dhcp_service_relay_instance_enable(uint16_t instance, uint8_t *server_address);
00135 
00136 /**
00137 * \brief Get DHCPv6 Relay Agent address pointer.
00138 *
00139 * \param instance The instance ID of the registered server.
00140 *
00141 * \return NULL when address is not available
00142 * {
00143 */
00144 uint8_t *dhcp_service_relay_global_addres_get(uint16_t instance);
00145 
00146 
00147 /**
00148 * \brief Deletes a server instance.
00149 *
00150 * Removes all data related to this instance.
00151 *
00152 * \param instance The instance ID of the registered server.
00153 */
00154 void dhcp_service_delete(uint16_t instance);
00155 
00156 /**
00157 * \brief Sends a DHCP response message.
00158 *
00159 * \param msg_tr_id The message transaction ID.
00160 * \param options Options for this request.
00161 * \param msg_ptr An allocated message pointer. Should not deallocate unless RET_MSG_ACCEPTED returned (then responsibility of client).
00162 * \param msg_len The length of the message.
00163 *
00164 * \return 0, if everything went fine.
00165 * \return -1, if error occurred.
00166 */
00167 int dhcp_service_send_resp(uint32_t msg_tr_id, uint8_t options, uint8_t *msg_ptr, uint16_t msg_len);
00168 
00169 
00170 /**
00171  * \brief Sends DHCP request message.
00172  *
00173  * Service takes care of retransmissions.
00174  *
00175  * \param instance_id The instance ID of the registered server.
00176  * \param options Options for this request.
00177  * \param ptr A void pointer to the client object.
00178  * \param addr The address of the server.
00179  * \param msg_ptr An allocated message pointer. This pointer is the responsibility of the service after this call.
00180  * \param msg_len The length of the message.
00181  * \param receive_resp_cb Callback pointer
00182  *
00183  * \return Transaction ID of the DHCP transaction
00184  * \return 0, if error occurred.
00185  */
00186 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);
00187 
00188 /**
00189  * \brief Setting retransmission parameters.
00190  *
00191  * Sets the retransmission parameters for this transaction.
00192  *
00193  * \param msg_tr_id The message transaction ID.
00194  * \param timeout_init An initial timeout value.
00195  * \param timeout_max The maximum timeout value when initial timeout is doubled with every retry.
00196  * \param retrans_max The maximum number of retries after which an error is received.
00197  *
00198  */
00199 void dhcp_service_set_retry_timers(uint32_t msg_tr_id, uint16_t timeout_init, uint16_t timeout_max, uint8_t retrans_max);
00200 
00201 /**
00202  * \brief Update DHCP service server address to active tx process.
00203  *
00204  * \param msg_tr_id The message transaction ID.
00205  * \param server_address New destination address to server / relay Agent.
00206  *
00207  */
00208 void dhcp_service_update_server_address(uint32_t msg_tr_id, uint8_t *server_address);
00209 
00210 /**
00211  * \brief Stops transactions for a message (retransmissions).
00212  *
00213  * Clears off sending retransmissions for a particular message transaction by finding it via its message transaction ID.
00214  *
00215  * \param msg_tr_id The message transaction ID.
00216  *
00217  */
00218 void dhcp_service_req_remove(uint32_t msg_tr_id);
00219 
00220 /**
00221  * \brief Stops transactions for a messages (retransmissions).
00222  *
00223  * Clears off sending retransmissions for a particular message transaction by finding it via its message class pointer.
00224  *
00225  * \param msg_class_ptr The message class pointer.
00226  *
00227  */
00228 void dhcp_service_req_remove_all(void *msg_class_ptr);
00229 
00230 /**
00231  * \brief Timer tick function for retransmissions.
00232  *
00233  * Retransmission timer ticks should be increased with 100ms interval, if necessary. One tick is one millisecond.
00234  *
00235  */
00236 bool dhcp_service_timer_tick(uint16_t ticks);
00237 
00238 
00239 #endif //DHCP_SERVICE_API_H_