edit-icon download-icon

クライアント操作

最終更新日: Dec 01, 2017

OSS MEDIA C SDKは、クライアント、サーバー、およびHLSの3つの部分に分けられます。次に、主にクライアントに関連する操作について説明します。その他の操作については、次の章を参照してください。

インターフェース

クライアントに関連する操作インターフェースは、すべてoss_media_file.hに配置されます。現在、次のインターフェースが提供されています。

  • oss_media_file_open
  • oss_media_file_stat
  • oss_media_file_tell
  • oss_media_file_seek
  • oss_media_file_read
  • oss_media_file_write
  • oss_media_file_close

次に、さまざまなインターフェースの関数と使用の注意点を詳しく説明します。

基本構造

  1. /**
  2. * Metadata of the OSS MEDIA FILE, including file length, location and type
  3. */
  4. typedef struct {
  5. int64_t length;
  6. int64_t pos;
  7. char *type;
  8. } oss_media_file_stat_t;
  9. /**
  10. * Attributes of the OSS MEDIA FILE
  11. */
  12. typedef struct oss_media_file_s {
  13. void *ipc;
  14. char *endpoint;
  15. int8_t is_cname;
  16. char *bucket_name;
  17. char *object_key;
  18. char *access_key_id;
  19. char *access_key_secret;
  20. char *token;
  21. char *mode;
  22. oss_media_file_stat_t _stat;
  23. time_t expiration;
  24. auth_fn_t auth_func;
  25. } oss_media_file_t;
  • type: ファイルタイプ: normal または appendable。

  • ipc: デバイスの一意の識別子を設定します。この属性は必要に応じてauth funcで使用でき、使用されない場合は無視されます。

  • endpoint: oss-cn-hangzhou.aliyuncs.comなど。

  • is_cname: CNAME が有効かどうか。

  • bucket_name: OSSバケットの名前。

  • object_key: OSSオブジェクトの名前。

  • access_key_id: アクセス制御のためにAlibaba Cloudによって提供されたアクセスキーID。ここでは2つのモードを使用できます。1.マスターアカウントまたはサブアカウントの永久アクセスキーID。この場合、後続のトークンはNULLに設定する必要があります。 2. get_tokenで取得した一時アクセスキーID。

  • access_key_secret: アクセス制御のためにAlibaba Cloudによって提供されるアクセスキーの秘密。ここでは2つのモードも使用できます。1.マスターアカウントまたはサブアカウントの永久アクセスキーの秘密。この場合、後続のトークンはNULLに設定する必要があります。 2. get_tokenで取得した一時アクセス鍵の秘密。 access_key_idとaccess_key_secretは同じモードを同時に使用する必要があります。

  • token: マスターアカウントまたはサブアカウントのaccess_key_id と access_key_secret を同時に使用する場合は、この属性をNULLに設定する必要があります。端末デバイスを使用してリソースをアップロードまたはダウンロードする場合、アプリケーションサーバーは端末デバイスに一時アクセス許可を与える必要があります。一時的なaccess_key_id、access_key_secret、およびトークンは、サーバー上のget_tokenを介して取得できます。トークンをNULL以外の値に設定すると、システムは一時アクセスキーID、一時アクセスキーシークレット、および一時トークンを使用しているとみなします。一時的なトークンを使用しない場合は、この属性をNULLに設定してください。

  • expiration: 認証に失敗した時刻。最初の許可の後、次の許可は、有効期限が過ぎた後にのみ実行されます。

  • auth: 認証機能。関数を実装し、その関数内のホスト、バケット、およびトークンの値に値を与える必要があります。

  • mode: 読み書きモード。

初期化

  1. /**
  2. * @brief Initialize the OSS media
  3. * @note This interface should be called first when the program starts to initialize the OSS MEDIA C SDK.
  4. * @return:
  5. * If 0 is returned, it indicates the operation was successful.
  6. * Otherwise, it indicates an error has occured. Possible causes include: insufficient memory, or the APR or CURL versions are too low.
  7. */
  8. int oss_media_init(aos_log_level_e log_level);

注意: サンプルコードは GitHubで見つけることができます。

破壊する

  1. /**
  2. * @brief Destroy the OSS meida
  3. * @note This interface should be called last when the program ends to destroy the OSS MEDIA C SDK.
  4. */
  5. void oss_media_destroy();

注意: サンプルコードはGitHubで見つけることができます。

オブジェクトを開く

  1. /**
  2. * @brief Open an OSS object
  3. * @param[in] Name of the bucket that stores objects in bucket_name oss
  4. * @param[in] Name of the object in object_key oss
  5. * @param[in] mode:
  6. * 'r': Read mode
  7. * 'w': Overwrite mode
  8. * 'a': Append write mode
  9. * notes: Not allowed to be used in combination
  10. * @param[in] auth_func The authorization function to set access_key_id/access_key_secret
  11. * @return:
  12. * If NULL is returned, it indicates success. Otherwise, it indicates failure.
  13. */
  14. oss_media_file_t* oss_media_file_open(char *bucket_name,
  15. char *object_key,
  16. char *mode,
  17. auth_fn_t auth_func);
  • mode: 読み取り専用、上書き、および書き込みモードがサポートされています。 組み合わせモードはサポートされていません

  • Read mode: オブジェクトを開いた後、オブジェクトコンテンツの一部を一度読み込みます。完全な内容を読み取るには、複数の読み取りが一般的に必要です。

  • Overwrite mode: オブジェクトを開いた後、オブジェクトの内容を一度だけ書き込むことができます。 複数の読み込みがサポートされていますが、最後の書き込みは前に書き込まれたコンテンツを上書きします

  • Append write:オブジェクトを開いた後、追加モードでオブジェクトに複数回コンテンツを書き込むことができます。

注意: サンプルコードは GitHubで見つけることができます。

オブジェクトを閉じる

  1. /**
  2. * @brief Close the OSS object
  3. */
  4. void oss_media_file_close(oss_media_file_t *file);

注意: サンプルコードは GitHubで見つけることができます。

オブジェクトを書く

  1. /**
  2. * @brief Write an object to the OSS
  3. * @return:
  4. * If the request is successful, the size of the written data will be returned. If "-1" is returned, it indicates the data write failed
  5. */
  6. int64_t oss_media_file_write(oss_media_file_t *file, const void *buf, int64_t nbyte);

サンプルプロジェクト:

  1. /* Authorization function */
  2. static void auth_func(oss_media_file_t *file) {
  3. file->endpoint = "your endpoint";
  4. file->is_cname = 0;
  5. file->access_key_id = "Access key ID or temporary access key ID provided by Alibaba Cloud";
  6. file->access_key_secret = "Access key secret or temporary access key secret provided by Alibaba Cloud";
  7. file->token = "Get the temporary token through the get_token interface";
  8. /* Effective time of this authorization */
  9. file->expiration = time(NULL) + 300;
  10. }
  11. static void write_file() {
  12. oss_clean(g_filename);
  13. int64_t write_size;
  14. oss_media_file_t *file;
  15. char *bucket_name = "<your bucket name>";
  16. char *key = "<your object key>";
  17. char *content = "aliyun oss media c sdk";
  18. /* Open an object */
  19. file = oss_media_file_open(bucket_name, key, "w", auth_func);
  20. if (!file) {
  21. printf("open media file failed\n");
  22. return;
  23. }
  24. /* Write an object */
  25. write_size = oss_media_file_write(file, content, strlen(content));
  26. if (-1 != write_size) {
  27. printf("write %" PRId64 " bytes succeeded\n", write_size);
  28. } else {
  29. oss_media_file_close(file);
  30. printf("write failed\n");
  31. return;
  32. }
  33. /* Close the object and release the resource */
  34. oss_media_file_close(file);
  35. }

注意:

  • この例では、オブジェクトを開くためにoverwrite ("w") モードが使用されています。複数の書き込みが実行される場合、後の書き込みは前の書き込みを上書きします。追加書き込みを有効にするには、オブジェクトを開くためのappend write ("a")モードを指定します。

  • サンプルコードはGitHubで見つけることができます。

オブジェクトを読み込む

  1. /**
  2. * @brief Read the data of a fixed number of nbytes
  3. * @note The size of buf should be greater than or equal to nbyte + 1
  4. * @return:
  5. * If 0 is returned, it indicates the operation is successful.
  6. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object was not opened in the "read-only" mode, the object cannot connect to the OSS, or the object has no permission to read the OSS.
  7. */
  8. int64_t oss_media_file_read(oss_media_file_t *file, void *buf, int64_t nbyte);

サンプルプロジェクト:

  1. int ntotal, nread, nbuf = 16;
  2. char buf[nbuf];
  3. char *content;
  4. char *bucket_name = "<your bucket name>";
  5. char *key = "<your object key>";
  6. oss_media_file_t *file;
  7. /* Open the object */
  8. file = oss_media_file_open(bucket_name, key, "r", auth_func);
  9. if (!file) {
  10. printf("open media file failed\n");
  11. return;
  12. }
  13. /* Read the object */
  14. content = malloc(stat.length + 1);
  15. ntotal = 0;
  16. while ((nread = oss_media_file_read(file, buf, nbuf)) > 0) {
  17. memcpy(content + ntotal, buf, nread);
  18. ntotal += nread;
  19. }
  20. content[ntotal] = '\0';
  21. /* Close the object */
  22. oss_media_file_close(file);
  23. free(content);
  24. printf("oss media c sdk read object succeeded\n");
  25. }

注意: サンプルコードは GitHubで見つけることができます。

オブジェクトを管理する

OSS MEDIA FILE はtell、 seek および stat 操作もサポートしています。

  1. /**
  2. * @brief Get the location of the OSS MEDIA FILE
  3. * @return:
  4. * If 0 is returned, it indicates the operation is successful.
  5. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object was not opened in the "read-only" mode, the object cannot connect to the OSS, or the object has no permission to read the OSS.
  6. */
  7. int64_t oss_media_file_tell(oss_media_file_t *file);
  8. /**
  9. * @brief Set the OSS MEDIA FILE pointer to the specified location
  10. * @return:
  11. * If 0 is returned, it indicates the operation is successful.
  12. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object was not opened in the "read-only" mode, the object cannot connect to the OSS, or the object has no permission to read the OSS.
  13. */
  14. int64_t oss_media_file_seek(oss_media_file_t *file, int64_t offset);
  15. /**
  16. * @brief Get the metadata of the OSS MEDIA FILE
  17. * @return:
  18. * If 0 is returned, it indicates the operation is successful.
  19. * Otherwise, if "-1" is returned, it indicates an error may have occurred. Possible causes of the failure include: the object cannot connect to the OSS, or the object has no permission to read the OSS.
  20. */
  21. int oss_media_file_stat(oss_media_file_t *file, oss_media_file_stat_t *stat);

サンプルプロジェクト:

  1. static void seek_tell_stat_file() {
  2. int ntotal, nread, nbuf = 16;
  3. char buf[nbuf];
  4. char *bucket_name = "<your bucket name>";
  5. char *key = "<your object key>";
  6. oss_media_file_t *file;
  7. /* Open the object */
  8. file = oss_media_file_open(bucket_name, key, "r", auth_func);
  9. if (!file) {
  10. printf("open media file failed\n");
  11. return;
  12. }
  13. /* Get the meta information of the object */
  14. oss_media_file_stat_t stat;
  15. if (0 != oss_media_file_stat(file, &stat)) {
  16. oss_media_file_close(file);
  17. oss_media_file_free(file);
  18. printf("stat media file[%s] failed\n", file->object_key);
  19. return;
  20. }
  21. printf("file [name=%s, length=%ld, type=%s]",
  22. file->object_key, stat.length, stat.type);
  23. /* tell */
  24. printf("file [position=%" PRId64 "]", oss_media_file_tell(file));
  25. /* seek */
  26. oss_media_file_seek(file, stat.length / 2);
  27. /* Close the object */
  28. oss_media_file_close(file);
  29. printf("oss media c sdk seek object succeeded\n");
  30. }

注意: サンプルコードは GitHubで見つけることができます。