API base
Importante
Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).
El entorno de ejecución de aplicaciones de Azure Sphere incluye un conjunto de bibliotecas comunes que definen las API base que hay disponibles para el desarrollo de aplicaciones de alto nivel: una biblioteca estándar de C basada en POSIX, una biblioteca cliente HTTP basada en curl y una biblioteca de SDK de Azure IoT para C.
En este tema se describe cómo determinar qué API base se incluyen en Azure Sphere y dónde buscar la documentación de referencia de las API base. Para más información sobre las API específicas del dispositivo, consulte las API de las bibliotecas de aplicaciones.
Funciones no admitidas
Es importante utilizar solo funciones de API base que se incluyan explícitamente en la superficie de API del entorno de aplicación de Azure Sphere. Las aplicaciones que llaman a funciones no admitidas es posible que no sean compatibles con versiones futuras del sistema operativo Azure Sphere y pueden causar la inestabilidad de dispositivo. Si desea solicitar compatibilidad con funciones adicionales, puede usar el foro de la comunidad de Azure Sphere para realizar la solicitud.
Comprobación de funciones
Para determinar si se admite la llamada a una función, use Autocompletar con IntelliSense en Visual Studio o compruebe que se incluye en los archivos de encabezado del SDK de Azure Sphere. En las secciones siguientes, se enumeran las ubicaciones de los archivos de encabezado para cada biblioteca. Si se agregan o modifican las funciones de estas bibliotecas, las mostraremos en este tema.
biblioteca estándar de musl C
Azure Sphere se incluye con la biblioteca estándar musl C (musl libc). Al igual que glibc, musl libc es una biblioteca C estándar compatible con POSIX. Las diferencias funcionales entre musl libc y glibc se enumeran en la wiki de musl libc.
Coherente con la arquitectura y la directiva de seguridad de Azure Sphere, no todas las funciones POSIX se exponen. Por ejemplo, Azure Sphere no admite las funciones open() o fopen(). Toda la superficie de API compatible de la biblioteca se define en los archivos de encabezado del SDK de Azure Sphere. La implementación actual puede cambiar en una versión posterior.
Referencia de API: especificación POSIX
Ubicación del archivo de encabezado: carpetas Sysroots\API set\usr\include (Sistema operativo Windows) o Sysroots/API set/usr/include (SISTEMA operativo Linux) del directorio de instalación del SDK de Azure Sphere.
Sugerencia
La carpeta Sysroots\API set\usr\include\sys contiene encabezados para las API dependientes del sistema de bajo nivel, mientras que la carpeta principal Sysroots\API set\usr\include contiene encabezados para las API generales. Esto también es cierto para Linux. Se recomienda usar las API generales.
Puede descargar el SDK más reciente aquí.
Características de la biblioteca estándar de C
Partes importantes de las siguientes características de la biblioteca estándar de C están excluidas:
- Rutas de acceso del sistema de archivos
- Compatibilidad con terminales
- Autenticación y autorización
- Funciones syscall
- System V (SysV)
fcntl
Los CMD de función fcntl(int fd, int cmd, .../* arg */) expuestos y disponibles para su uso son los siguientes:
- F_GETFL: recupera el modo de acceso a archivos y las marcas de estado de archivo relacionadas.
- F_SETFL: establece las marcas de estado de archivo, tal como establece el argumento , para un descriptor de archivo.
- O_NONBLOCK: argumento que se expone específicamente para F_SETFL.
Para ver el uso estándar de la función fcntl(), consulte la biblioteca MUSL.
Time_t de tipo C
Como preparación para la sustitución de épocas de UNIX en 2038, musl libc versión 1.2 incluía una actualización, de 32 bits a 64 bits, de tipo time_t C y de todos sus derivados. Para obtener más información sobre esta actualización, vea musl time64 Release Notes( Notas de la versión de musl time64).
Las aplicaciones compiladas con el conjunto de API de destino 20.10 (sysroot 7) y versiones posteriores usan la versión de 64 bits de time_t. Las aplicaciones compiladas con versiones anteriores del SDK de Azure Sphere o la API de destino establecida en 20.04 (sysroot 5) o versiones anteriores pueden seguir usando una definición de 32 bits de time_t. Las nuevas versiones del sistema operativo de Azure Sphere seguirán proporcionando la misma interfaz binaria de aplicación (ABI) a estas aplicaciones.
El código de aplicación que no supone el tamaño de un time_t valor no se ve afectado. Sin embargo, el código de aplicación que asume explícita o implícitamente que time_t los valores son de 32 bits (por ejemplo, al convertir un time_t valor en un uint32_t) se deben volver a escribir para reflejar la versión de 64 bits.
En el fragmento de código siguiente se supone que time_t es un valor de 32 bits y se producirá una saturación del búfer si se vuelve a compilar con el SDK 20.10 (sysroot 7) o posterior:
// Incorrect code that assumes a 32-bit time_t value
time_t t = time(NULL);
char buffer[4];
memcpy(buffer, &t, sizeof(t)); // <-- buffer overrun when time_t is 64 bits
El siguiente código corregido define que el búfer tiene el mismo tamaño que el time_t valor, quitando así cualquier suposición sobre el tamaño de time_t:
// Corrected version of the code. It does not hard-code the size of time_t
time_t t; // time_t represents the 64-bit struct.
char buffer[sizeof(time_t)]; // Buffer size is based on the actual size of time_t
memcpy(buffer, &t, sizeof(t));
Si necesita seguir usando un valor de tiempo de 32 bits, use el time32_t tipo en la nueva versión de musl. El siguiente fragmento de código muestra cómo:
// Corrected version of the code for cases where 32-bit time_t is needed
time32_t t = /* ... initialize 32-bit value ... */;
char buffer[sizeof(time32_t)];
memcpy(buffer, &t, sizeof(t));
Biblioteca de curl
El SDK de Azure Sphere incluye un subconjunto de la biblioteca de transferencia de protocolos múltiples de libcurl. Puede usar esta API para transferir datos a través de HTTP/HTTPS. No se admiten otros protocolos de transferencia. Toda la superficie de API compatible de la biblioteca se define en los archivos de encabezado del SDK de Azure Sphere.
Referencia de API: sitio web de libcurl
Ubicación del archivo de encabezado: carpeta Sysroots\API set\usr\include\curl (SISTEMA operativo Windows) o sysroots/API set/usr/include/curl (SO Linux) del directorio de instalación del SDK de Azure Sphere.