xTimerChangePeriod
[定时器 API ]

 BaseType_t xTimerChangePeriod( TimerHandle_t xTimer,
                                TickType_t xNewPeriod,
                                TickType_t xBlockTime );

软件定时器功能由定时器服务/守护进程任务提供。 许多 公共 FreeRTOS 定时器 API 函数通过定时器命令队列 向定时器服务任务发送命令。 定时器命令队列是 RTOS 内核本身的私有队列， 应用程序代码无法直接访问该队列。 定时器命令队列的长度 由 configTIMER_QUEUE_LENGTH 配置常量设置。

xTimerChangePeriod() 可以改变先前使用 xTimerCreate() API 函数创建的定时器的周期。

可以调用 xTimerChangePeriod() 来更改活动 或休眠状态的定时器的周期。 更改休眠定时器的周期也会启动 定时器。

必须将 configUSE_TIMERS 配置常量设置为 1， xTimerChangePeriod() 才可用。

参数：

xTimer	其周期将改变的定时器的句柄。
xNewPeriod	xTimer 的新周期。定时器周期 在 tick 周期中指定，因此常量 portTICK_PERIOD_MS 可用于转换 已指定的时间（以毫秒为单位）。 例如，如果定时器必须 在100个 tick 后过期，则 xNewPeriod 应设置为100。 或者， 如果定时器必须在500 毫秒后过期，则 xNewPeriod 可以设置为 (500/portTICK_PERIOD_MS) ，前提是 configTICK_RATE_HZ 小于 或等于 1000。定时器周期必须大于 0。
xBlockTime	在调用 xTimerDelete() 时队列已满的情况下， 指定调用任务应保持阻塞状态 以等待变更周期命令成功发送到定时器命令队列的时间 （以 tick 为单位）。 如果在 启动 RTOS 调度器之前调用 xTimerChangePeriod()，则会忽略 xBlockTime。

返回：

如果即使经过 xBlockTime（以 tick 为单位） 之后仍无法将更改周期命令发送到定时器命令队列，则将返回 pdFAIL。 如果能将此命令成功发送到定时器命令队列，则返回 pdPASS 则返回 pdPASS。 实际处理命令的时间取决于 定时器服务/守护进程任务相对于系统中其他任务的 优先级。 定时器服务/守护进程任务的优先级 由 configTIMER_TASK_PRIORITY 配置常量设置。

/* This function assumes xTimer has already been created.  If the timer
referenced by xTimer is already active when it is called, then the timer
is deleted.  If the timer referenced by xTimer is not active when it is
called, then the period of the timer is set to 500ms and the timer is
started. */
void vAFunction( TimerHandle_t xTimer )
{
    /* or more simply and equivalently
    "if( xTimerIsTimerActive( xTimer ) )" */
    if( xTimerIsTimerActive( xTimer ) != pdFALSE )
    {
        /* xTimer is already active - delete it. */
        xTimerDelete( xTimer );
    }
    else
    {
        /* xTimer is not active, change its period to 500ms.  This will also
        cause the timer to start.  Block for a maximum of 100 ticks if the
        change period command cannot immediately be sent to the timer
        command queue. */
        if( xTimerChangePeriod( xTimer, 500 / portTICK_PERIOD_MS, 100 )
                                                            == pdPASS )
        {
            /* The command was successfully sent. */
        }
        else
        {
            /* The command could not be sent, even after waiting for 100 ticks
            to pass.  Take appropriate action here. */
        }
    }
}